mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
Rework documentation (#13709)
* Rework documentation * Slightly adjust theme * wip * fixes * Remove unneeded header * Re-added Acknowledgement.md file * Added Acknowledgement.md to mkdocs.yml Co-authored-by: Neil Lathwood <gh+n@laf.io>
This commit is contained in:
Jellyfrog
GitHub
@@ -1,3 +0,0 @@
|
||||
source: Installation/CentOS-image.md
|
||||
path: blob/master/doc/
|
||||
<meta http-equiv="refresh" content="0; url=/Installation/Images/" />
|
||||
5
doc/Installation/Docker.md
Normal file
5
doc/Installation/Docker.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# Docker
|
||||
|
||||
An official LibreNMS docker image based on Alpine Linux and Nginx is available
|
||||
on [DockerHub](https://hub.docker.com/r/librenms/librenms/).
|
||||
Documentation can be found on the [GitHub repository](https://github.com/librenms/docker).
|
||||
@@ -1,4 +1,3 @@
|
||||
|
||||
# LibreNMS VMs
|
||||
|
||||
> NOTE: We highly advise that you change all passwords on this image
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Install-LibreNMS.md
|
||||
path: blob/master/doc/
|
||||
|
||||
# Install LibreNMS
|
||||
|
||||
## Prepare Linux Server
|
||||
@@ -418,7 +415,7 @@ Feel free to tune the performance settings in librenms.conf to meet your needs.
|
||||
dnf install policycoreutils-python-utils
|
||||
```
|
||||
|
||||
### Configure the contexts needed by LibreNMS
|
||||
<h3>Configure the contexts needed by LibreNMS</h3>
|
||||
|
||||
```
|
||||
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/html(/.*)?'
|
||||
@@ -430,7 +427,7 @@ Feel free to tune the performance settings in librenms.conf to meet your needs.
|
||||
chcon -t httpd_sys_rw_content_t /opt/librenms/.env
|
||||
```
|
||||
|
||||
### Allow fping
|
||||
<h3>Allow fping</h3>
|
||||
|
||||
Create the file http_fping.tt with the following contents. You can
|
||||
create this file anywhere, as it is a throw-away file. The last step
|
||||
@@ -584,7 +581,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-CentOS-6-Apache-Nginx.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-CentOS-7-Apache.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
@@ -346,7 +343,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-CentOS-7-Nginx.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
@@ -332,7 +329,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1,248 +0,0 @@
|
||||
source: Installation/Installation-Debian-11-Nginx.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
> privileges with `sudo -s` or `sudo -i`.
|
||||
|
||||
**Please note the minimum supported PHP version is @= php.version_min =@**
|
||||
|
||||
# Install Required Packages
|
||||
|
||||
```bash
|
||||
apt install acl curl composer fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php7.4-cli php7.4-curl php7.4-fpm php7.4-gd php7.4-json php7.4-mbstring php7.4-mysql php7.4-snmp php7.4-xml php7.4-zip python-memcache python-mysqldb rrdtool snmp snmpd whois python3-pip python3-pymysql python3-dotenv python3-redis python3-setuptools
|
||||
```
|
||||
|
||||
# Add librenms user
|
||||
|
||||
```bash
|
||||
useradd librenms -d /opt/librenms -M -r
|
||||
usermod -a -G librenms www-data
|
||||
```
|
||||
|
||||
# Download LibreNMS
|
||||
|
||||
```bash
|
||||
cd /opt
|
||||
git clone https://github.com/librenms/librenms.git
|
||||
```
|
||||
|
||||
# Set permissions
|
||||
|
||||
```bash
|
||||
chown -R librenms:librenms /opt/librenms
|
||||
chmod 770 /opt/librenms
|
||||
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
|
||||
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
|
||||
```
|
||||
|
||||
# Install PHP dependencies
|
||||
|
||||
```bash
|
||||
su - librenms
|
||||
./scripts/composer_wrapper.php install --no-dev
|
||||
exit
|
||||
```
|
||||
|
||||
# DB Server
|
||||
|
||||
## Configure MySQL
|
||||
|
||||
```bash
|
||||
service mysql restart
|
||||
mysql -uroot -p
|
||||
```
|
||||
|
||||
> NOTE: Please change the 'password' below to something secure.
|
||||
|
||||
```sql
|
||||
CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
|
||||
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
exit
|
||||
```
|
||||
|
||||
```bash
|
||||
nano /etc/mysql/mariadb.conf.d/50-server.cnf
|
||||
```
|
||||
|
||||
Within the `[mysqld]` section please add:
|
||||
|
||||
```bash
|
||||
innodb_file_per_table=1
|
||||
lower_case_table_names=0
|
||||
```
|
||||
|
||||
```bash
|
||||
service mysql restart
|
||||
```
|
||||
|
||||
# Web Server
|
||||
|
||||
## Configure and Start PHP-FPM
|
||||
|
||||
Ensure date.timezone is set in php.ini to your preferred time zone.
|
||||
See <https://php.net/manual/en/timezones.php> for a list of supported
|
||||
timezones. Valid examples are: "America/New_York",
|
||||
"Australia/Brisbane", "Etc/UTC".
|
||||
|
||||
```bash
|
||||
nano /etc/php/7.4/fpm/php.ini
|
||||
nano /etc/php/7.4/cli/php.ini
|
||||
```
|
||||
|
||||
```bash
|
||||
service php7.4-fpm restart
|
||||
```
|
||||
|
||||
## Configure NGINX
|
||||
|
||||
```bash
|
||||
rm /etc/nginx/sites-enabled/default
|
||||
nano /etc/nginx/sites-available/librenms.vhost
|
||||
```
|
||||
|
||||
Add the following config, edit `server_name` as required:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name librenms.example.com;
|
||||
root /opt/librenms/html;
|
||||
index index.php;
|
||||
|
||||
charset utf-8;
|
||||
gzip on;
|
||||
gzip_types text/css application/javascript text/javascript application/x-javascript image/svg+xml text/plain text/xsd text/xsl text/xml image/x-icon;
|
||||
|
||||
proxy_read_timeout 300;
|
||||
proxy_connect_timeout 300;
|
||||
proxy_send_timeout 300;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.php?$query_string;
|
||||
}
|
||||
location /api/v0 {
|
||||
try_files $uri $uri/ /api_v0.php?$query_string;
|
||||
}
|
||||
location ~ \.php {
|
||||
include fastcgi.conf;
|
||||
fastcgi_split_path_info ^(.+\.php)(/.+)$;
|
||||
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
|
||||
}
|
||||
location ~ /\.ht {
|
||||
deny all;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
ln -s /etc/nginx/sites-available/librenms.vhost /etc/nginx/sites-enabled/librenms.vhost
|
||||
service nginx reload
|
||||
```
|
||||
|
||||
# Configure snmpd
|
||||
|
||||
```bash
|
||||
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
|
||||
chmod 600 /etc/snmp/snmpd.conf
|
||||
nano /etc/snmp/snmpd.conf
|
||||
```
|
||||
|
||||
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
|
||||
|
||||
```bash
|
||||
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
|
||||
chmod +x /usr/bin/distro
|
||||
service snmpd restart
|
||||
```
|
||||
|
||||
# Cron job
|
||||
|
||||
```bash
|
||||
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
|
||||
```
|
||||
|
||||
> NOTE: Keep in mind that cron, by default, only uses a very limited
|
||||
> set of environment variables. You may need to configure proxy
|
||||
> variables for the cron invocation. Alternatively adding the proxy
|
||||
> settings in config.php is possible too. The config.php file will be
|
||||
> created in the upcoming steps. Review the following URL after you
|
||||
> finished librenms install steps:
|
||||
> <@= config.site_url =@/Support/Configuration/#proxy-support>
|
||||
|
||||
# Copy logrotate config
|
||||
|
||||
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
|
||||
become large and be rotated out. To rotate out the old logs you can
|
||||
use the provided logrotate config file:
|
||||
|
||||
```bash
|
||||
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
|
||||
```
|
||||
|
||||
# Web installer
|
||||
|
||||
Now head to the web installer and follow the on-screen instructions.
|
||||
|
||||
<http://librenms.example.com/install.php>
|
||||
|
||||
The web installer might prompt you to create a `config.php` file in
|
||||
your librenms install location manually, copying the content displayed
|
||||
on-screen to the file. If you have to do this, please remember to set
|
||||
the permissions on config.php after you copied the on-screen contents
|
||||
to the file. Run:
|
||||
|
||||
```bash
|
||||
chown librenms:librenms /opt/librenms/config.php
|
||||
```
|
||||
|
||||
# Final steps
|
||||
|
||||
That's it! You now should be able to log in to
|
||||
<http://librenms.example.com/>. Please note that we have not covered
|
||||
HTTPS setup in this example, so your LibreNMS install is not secure by
|
||||
default. Please do not expose it to the public Internet unless you
|
||||
have configured HTTPS and taken appropriate web server hardening
|
||||
steps.
|
||||
|
||||
# Add the first device
|
||||
|
||||
We now suggest that you add localhost as your first device from within
|
||||
the WebUI.
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
If you ever have issues with your install, run validate.php as root in
|
||||
the librenms directory:
|
||||
|
||||
```bash
|
||||
cd /opt/librenms
|
||||
./validate.php
|
||||
```
|
||||
|
||||
There are various options for getting help listed on the LibreNMS web
|
||||
site: <https://www.librenms.org/#support>
|
||||
|
||||
# What next?
|
||||
|
||||
Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
# Closing
|
||||
|
||||
We hope you enjoy using LibreNMS. If you do, it would be great if you
|
||||
would consider opting into the stats system we have, please see [this
|
||||
page](../General/Callback-Stats-and-Privacy.md) on
|
||||
what it is and how to enable it.
|
||||
|
||||
If you would like to help make LibreNMS better there are [many ways to
|
||||
help](../Support/FAQ.md#a-namefaq9-what-can-i-do-to-helpa). You
|
||||
can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-Ubuntu-1604-Apache.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
@@ -210,7 +207,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-Ubuntu-1604-Nginx.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
@@ -223,7 +220,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-Ubuntu-1804-Apache.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
@@ -221,7 +218,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Installation-Ubuntu-1804-Nginx.md
|
||||
path: blob/master/doc/
|
||||
|
||||
> NOTE: These instructions assume you are the **root** user. If you
|
||||
> are not, prepend `sudo` to the shell commands (the ones that aren't
|
||||
> at `mysql>` prompts) or temporarily become a user with root
|
||||
@@ -247,7 +244,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read
|
||||
of a few other docs to get you going:
|
||||
|
||||
- [Performance tuning](../Support/Performance.md)
|
||||
- [Alerting](../Extensions/Alerting.md)
|
||||
- [Alerting](../Alerting/index.md)
|
||||
- [Device Groups](../Extensions/Device-Groups.md)
|
||||
- [Auto discovery](../Extensions/Auto-Discovery.md)
|
||||
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
<meta http-equiv="refresh" content="0; url=/Installation/" />
|
||||
@@ -1,6 +1,3 @@
|
||||
source: Installation/Migrating-from-Observium.md
|
||||
path: blob/master/doc/
|
||||
|
||||
A LibreNMS user, [Dan](https://twitter.com/thedanbrown), has kindly
|
||||
provided full details and scripts to be able to migrate from Observium
|
||||
to LibreNMS.
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
source: Installation/Ubuntu-image.md
|
||||
path: blob/master/doc/
|
||||
<meta http-equiv="refresh" content="0; url=/Installation/Images/" />
|
||||
@@ -1,42 +0,0 @@
|
||||
source: Installation/index.md
|
||||
path: blob/master/doc/
|
||||
|
||||
# Installing LibreNMS
|
||||
|
||||
## Docker
|
||||
|
||||
An official LibreNMS docker image based on Alpine Linux and Nginx is available
|
||||
on [DockerHub](https://hub.docker.com/r/librenms/librenms/). Documentation can
|
||||
be found on the [GitHub repository](https://github.com/librenms/docker).
|
||||
|
||||
## Manually
|
||||
|
||||
If you want to install manually then we have some documentation which should make it easy.
|
||||
|
||||
This document includes instructions for:
|
||||
|
||||
- Ubuntu 20.04
|
||||
- RHEL / CentOS 8
|
||||
- Debian 11
|
||||
|
||||
** [Install LibreNMS](Install-LibreNMS.md) **
|
||||
|
||||
## Images
|
||||
|
||||
We have some pre-built VirtualBox images you can use to get started:
|
||||
|
||||
- [Virtual Machines](Images)
|
||||
|
||||
|
||||
## Old Install Docs
|
||||
|
||||
These install docs are no longer updated and may result in an unsuccessful install.
|
||||
|
||||
- [Ubuntu 18.04 Apache](Installation-Ubuntu-1804-Apache/)
|
||||
- [Ubuntu 18.04 Nginx](Installation-Ubuntu-1804-Nginx/)
|
||||
- [Debian 11 Nginx](Installation-Debian-11-Nginx/)
|
||||
- [RHEL / CentOS 7 Apache](Installation-CentOS-7-Apache/)
|
||||
- [RHEL / CentOS 7 Nginx](Installation-CentOS-7-Nginx/)
|
||||
- [Ubuntu 16.04 Apache](Installation-Ubuntu-1604-Apache/)
|
||||
- [Ubuntu 16.04 Nginx](Installation-Ubuntu-1604-Nginx/)
|
||||
- [RHEL / CentOS 6](Installation-CentOS-6-Apache-Nginx/)
|
||||
Reference in New Issue
Block a user