mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch 'consolidate-install-doc' of https://github.com/murrant/librenms into consolidate-install-doc

Browse Source
This commit is contained in:
Tony Murray
2020-06-04 08:32:27 -05:00
parent d09d0ab5f8 9ab49bf81c
commit 9a16bc4f7a
9 changed files with 65 additions and 1128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
doc/Installation/Install-LibreNMS.md
View File

@@ -33,14 +33,14 @@ you select the same option when they are presented.
=== "CentOS 8"
=== "NGINX"
```
yum install epel-release
yum install cronie fping git ImageMagick mariadb mariadb-server mtr net-snmp net-snmp-utils nginx nmap php-fpm php-cli php-common php-curl php-gd php-json php-mbstring php-process php-snmp php-xml php-zip php-mysqlnd python3-PyMySQL python3-redis python3-memcached rrdtool
dnf install epel-release
dnf install bash-completion cronie fping git ImageMagick mariadb-server mtr net-snmp net-snmp-utils nginx nmap php-fpm php-cli php-common php-curl php-gd php-json php-mbstring php-process php-snmp php-xml php-zip php-mysqlnd python3 python3-PyMySQL python3-redis python3-memcached rrdtool
```
=== "Apache"
```
yum install epel-release
yum install git cronie fping jwhois ImageMagick mtr MySQL-python net-snmp net-snmp-utils nmap python-memcached rrdtool policycoreutils-python httpd mariadb mariadb-server unzip python3 python3-pip
dnf install epel-release
dnf install bash-completion cronie fping git httpd ImageMagick mariadb-server mtr net-snmp net-snmp-utils nmap php-fpm php-cli php-common php-curl php-gd php-json php-mbstring php-process php-snmp php-xml php-zip php-mysqlnd python3 python3-PyMySQL python3-redis python3-memcached rrdtool unzip
```
=== "Debian 10"
@@ -53,6 +53,7 @@ you select the same option when they are presented.
```
useradd librenms -d /opt/librenms -M -r -s /usr/bin/bash
usermod -a -G apache librenms # FIXME needed for CentOS, remove session
```
# Download LibreNMS
@@ -79,9 +80,37 @@ su - librenms
exit
```
# DB Server
# Set timezone
## Configure MySQL
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
Ensure date.timezone is set in php.ini to your preferred time zone.
=== "Ubuntu 20.04"
```bash
vi /etc/php/7.4/fpm/php.ini
vi /etc/php/7.4/cli/php.ini
```
=== "Debian 10"
```bash
vi /etc/php/7.3/fpm/php.ini
vi /etc/php/7.3/cli/php.ini
```
=== "CentOS 8"
```
vi /etc/php.ini
```
Remember to set the system timezone as well.
```
timedatectl set-timezone Etc/UTC
```
# Configure MariaDB
=== "Ubuntu 20.04 / Debian 10"
```
@@ -119,38 +148,7 @@ FLUSH PRIVILEGES;
exit
```
# Configure PHP
## Set timezone
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
Ensure date.timezone is set in php.ini to your preferred time zone.
=== "Ubuntu 20.04"
```bash
vi /etc/php/7.4/fpm/php.ini
vi /etc/php/7.4/cli/php.ini
```
=== "Debian 10"
```bash
vi /etc/php/7.3/fpm/php.ini
vi /etc/php/7.3/cli/php.ini
```
=== "CentOS 8"
```
vi /etc/php.ini
```
Remember to set the system timezone as well.
```
timedatectl set-timezone Etc/UTC
```
## Configure PHP-FPM
# Configure PHP-FPM
=== "Ubuntu 20.04"
```bash
@@ -182,7 +180,7 @@ group = librenms
listen = /run/php-fpm-librenms.sock;
```
# Web Server
# Configure Web Server
=== "Ubuntu 20.04"
=== "NGINX"
@@ -370,7 +368,16 @@ listen = /run/php-fpm-librenms.sock;
AllowOverride All
Options FollowSymLinks MultiViews
</Directory>
</VirtualHost>
# Enable http authorization headers
<IfModule setenvif_module>
SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
</IfModule>
<FilesMatch ".+\.php$">
SetHandler "proxy:unix:/run/php-fpm-librenms.sock|fcgi://localhost"
</FilesMatch>
</VirtualHost>
```
> NOTE: If this is the only site you are hosting on this server (it
@@ -378,6 +385,7 @@ listen = /run/php-fpm-librenms.sock;
```
systemctl enable --now httpd
systemctl enable --now php-fpm
```
# SELinux
@@ -389,7 +397,7 @@ listen = /run/php-fpm-librenms.sock;
Install the policy tool for SELinux:
```
yum install python3-policycoreutils
dnf install policycoreutils-python-utils
```
## Configure the contexts needed by LibreNMS:
@@ -443,11 +451,19 @@ listen = /run/php-fpm-librenms.sock;
Firewall not enabled by default
=== "CentOS 8"
```
firewall-cmd --zone public --add-service http --add-service https
firewall-cmd --permanent --zone public --add-service http --add-service https
```
# Enable lnms command completion
```
ln -s /opt/librenms/lnms /usr/local/bin/lnms
cp /opt/librenms/misc/lnms-completion.bash /etc/bash_completion.d/
```
# Configure snmpd
```

3
doc/Installation/Installation-(Debian-Ubuntu).md
View File

@@ -1,3 +0,0 @@
source: Installation/Installation-(Debian-Ubuntu).md
path: blob/master/doc/
<meta http-equiv="refresh" content="0; url=/Installation/Installation-Ubuntu-1604-Apache/" />

3
doc/Installation/Installation-(RHEL-CentOS).md
View File

@@ -1,3 +0,0 @@
source: Installation/Installation-(RHEL-CentOS).md
path: blob/master/doc/
<meta http-equiv="refresh" content="0; url=/Installation/Installation-CentOS-7-Apache/" />

373
doc/Installation/Installation-Ubuntu-1404-Apache.md
View File

@@ -1,373 +0,0 @@
source: Installation/Installation-Ubuntu-1404-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
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
# On the DB Server
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
## MySQL
```bash
apt-get install mysql-server mysql-client
mysql -uroot -p
```
## MariaDB
```bash
apt-get install mariadb-server mariadb-client
mysql -uroot -p
```
## General
Input the MySQL root password to enter the MySQL command-line interface.
Create the database:
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP or DNS name of the server running
LibreNMS. If your database is on the same server as LibreNMS, you can
use `localhost`.
If you are deploying a separate database server, you need to change
the `bind-address`. If your MySQL database resides on the same server
as LibreNMS, you should skip this step.
```bash
vim /etc/mysql/my.cnf
```
Within the [mysqld] section please add:
```mysql
innodb_file_per_table=1
```
Find the line: `bind-address = 127.0.0.1`
Change `127.0.0.1` to the IP address that your MySQL server should
listen on. Restart MySQL:
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
```bash
service mysql restart
```
# On the NMS
This host is where the web server and SNMP poller run. It could be
the same machine as your database server.
Install the required software:
```bash
apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear php5-curl snmp graphviz php5-mcrypt php5-json apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd php-net-ipv4 php-net-ipv6 rrdtool git
```
The packages listed above are an all-inclusive list of packages that
were necessary on a clean install of Ubuntu 12.04/14.04.
You need to configure snmpd appropriately if you have not already done
so. An absolute minimal config for snmpd is:
```
rocommunity public 127.0.0.1
```
Adding the above line to `/etc/snmp/snmpd.conf` and running `service
snmpd restart` will activate this config.
In `/etc/php5/apache2/php.ini` and `/etc/php5/cli/php.ini`, ensure
date.timezone is set to your preferred time zone. See
<http://php.net/manual/en/timezones.php> for a list of
supported timezones. Valid examples are: "America/New York",
"Australia/Brisbane", "Etc/UTC".
Please also ensure that `allow_url_fopen` is enabled. Other functions
needed for LibreNMS include
`exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
# Adding the librenms-user
```bash
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
# Cloning
LibreNMS is installed using git. If you're not familiar with git,
check out the [git book][2] or the tips at [git ready][3]. The
initial install from github.com is called a `git clone`; subsequent
updates are done through `git pull`.
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure that the appropriate port (443 for HTTPS, 22 for SSH)
is open in the outbound direction for your server.
```bash
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
The recommended method of cloning a git repository is HTTPS. If you
would like to clone via SSH instead, use the command `git clone
git@github.com:librenms/librenms.git librenms` instead.
Sometimes the initial clone can take quite a while (nearly 3 minutes
on a 10 Mbps fibre connection in Australia is a recent example). If
it's a big problem to you, you can save about 50% of the bandwidth by
not pulling down the full git history. This comes with some
limitations (namely that you can't use it as the basis for further git
repos), but if you're not planning to develop for LibreNMS it's an
acceptable option. To perform the initial clone without full history,
run the following instead:
```bash
cd /opt
git clone --depth 1 https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
# Web Interface
To prepare the web interface (and adding devices shortly), you'll need
to create and chown a directory as well as create an Apache vhost.
First, create and chown the `rrd` directory and create the `logs` directory:
```bash
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
> NOTE: If you're not running Ubuntu or Debian, you will need to
> change `www-data` to the user and group which run the Apache web
> server.
> If you're planing on running rrdcached, make sure that the path is
> also chmod'ed to 775 and chown'ed to librenms:librenms.
Next, add the following to `/etc/apache2/sites-available/librenms.conf`:
```apache
<VirtualHost *:80>
DocumentRoot /opt/librenms/html/
ServerName librenms.example.com
CustomLog /opt/librenms/logs/access_log combined
ErrorLog /opt/librenms/logs/error_log
AllowEncodedSlashes On
<Directory "/opt/librenms/html/">
AllowOverride All
Options FollowSymLinks MultiViews
</Directory>
</VirtualHost>
```
If you are running Apache 2.2.18 or higher then change
`AllowEncodedSlashes On` to `AllowEncodedSlashes NoDecode`
If you have Apache 2.3 or newer then please add the following line
before `AllowOverride All`:
```apache
Require all granted
```
On at least Ubuntu 14.04 (and possibly other distributions and
versions as well), mcrypt is not enabled on install. Run the
following to enable it:
```bash
php5enmod mcrypt
```
Change `librenms.example.com` to the appropriate hostname for your
domain, then enable the vhost and restart Apache:
```bash
a2ensite librenms.conf
a2enmod rewrite
service apache2 restart
```
If this is the only site you are hosting on this server (it should be
:)) then you will need to disable the default site setup in Ubuntu:
```bash
a2dissite 000-default
```
(To get to your LibreNMS install externally, you'll also need add it
to your DNS or hosts file.)
# Manual vs. web installer
At this stage you can either launch the web installer by going to
<http://librenms.example.com/install.php>, follow the onscreen
instructions then skip to the 'Add localhost' section. Alternatively
if you want to continue the setup manually then just keep following
these instructions.
```bash
cp config.php.default config.php
vim config.php
```
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as setup above.
Change the value of `$config['snmp']['community']` from `public` to
whatever your read-only SNMP community is. If you have multiple
communities, set it to the most common.
** Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise. **
# Initialise the database
Initiate the follow database with the following command:
```bash
php build-base.php
```
# Create admin user
Create the admin user - priv should be 10
```bash
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and
leave the angled brackets off.
# Validate your install
Run validate.php as root in the librenms directory
```bash
php validate.php
```
This will check your install to verify it is set up correctly.
# Add localhost
```bash
php addhost.php localhost public v2c
```
This assumes you haven't made community changes--if you have, replace
`public` with your community. It also assumes SNMP v2c. If you're
using v3, there are additional steps (NOTE: instructions for SNMPv3 to
come).
Discover localhost::
```bash
php discovery.php -h all
```
# Create cronjob
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the
cron job runs `poller-wrapper.py` with 16 threads. The current
recommendation is to use 4 threads per core as a rule of thumb. If
the thread count needs to be changed, you can do so by editing the
cron file (`/etc/cron.d/librenms`). Just add a number after
`poller-wrapper.py`, as in the example below:
```bash
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
```bash
cp 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:
> <https://docs.librenms.org/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 misc/librenms.logrotate /etc/logrotate.d/librenms
```
# Daily Updates
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
```php
#$config['update'] = 0;
```
so that it looks like this:
```php
$config['update'] = 0;
```
Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer
to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
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.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
[1]: https://github.com/Atrato/observium-poller-wrapper
[2]: http://git-scm.com/book
[3]: http://gitready.com/

329
doc/Installation/Installation-Ubuntu-1404-Lighttpd.md
View File

@@ -1,329 +0,0 @@
source: Installation/Installation-Ubuntu-1404-Lighttpd.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 5.6.4**
# On the DB Server
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
## MySQL
```bash
apt-get install mysql-server mysql-client
mysql -uroot -p
```
## MariaDN
```bash
apt-get install mariadb-server mariadb-client
mysql -uroot -p
```
## General
Enter the MySQL root password to enter the MySQL command-line interface.
Create database.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP of the server running LibreNMS. If
your database is on the same server as LibreNMS, you can just use
`localhost` as the IP address.
If you are deploying a separate database server, you need to change
the `bind-address`. If your MySQL database resides on the same server
as LibreNMS, you should skip this step.
```
vim /etc/mysql/my.cnf
```
Within the [mysqld] section please add:
```
innodb_file_per_table=1
```
Find the line: `bind-address = 127.0.0.1`
Change `127.0.0.1` to the IP address that your MySQL server should
listen on. Restart MySQL:
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
```
service mysql restart
```
# On the NMS
Install necessary software. The packages listed below are an
all-inclusive list of packages that were necessary on a clean install
of Debian 7.
```
apt-get install lighttpd php5-cli php5-mysql php5-gd php5-snmp php5-cgi php-pear php5-curl snmp graphviz rrdtool sendmail fping imagemagick whois mtr-tiny nmap ipmitool php5-mcrypt php5-json python-mysqldb snmpd php-net-ipv4 php-net-ipv6 rrdtool git
```
# Adding the librenms-user
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
# Cloning
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure the appropriate port (443 for HTTPS, 22 for SSH) is
open in the outbound direction for your server.
```
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
At this stage you can either launch the web installer by going to
<http://IP/install.php>, follow the onscreen instructions then skip to
the 'Web Interface' section further down. Alternatively if you want to
continue the setup manually then just keep following these
instructions.
```
cp config.php.default config.php
vim config.php
```
> NOTE: The recommended method of cloning a git repository is HTTPS.
> If you would like to clone via SSH instead, use the command `git
> clone git@github.com:librenms/librenms.git librenms` instead.
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as setup above.
Change the value of `$config['snmp']['community']` from `public` to
whatever your read-only SNMP community is. If you have multiple
communities, set it to the most common.
** Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise. **
# Initialise the database
Initiate the follow database with the following command:
```
php build-base.php
```
# Create admin user
Create the admin user - priv should be 10
```
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and
leave the angled brackets off.
# Web Interface
To prepare the web interface (and adding devices shortly), you'll need
to set up Lighttpd.
First, create and chown the `rrd` directory and create the `logs` directory
```
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
> NOTE: If you're planing on running rrdcached, make sure that the
> path is also chmod'ed to 775 and chown'ed to librenms:librenms.
Next, add the following to `/etc/lighttpd/librenms.conf`
```
server.document-root = "/opt/librenms/html"
url.rewrite-once = (
"^/(.*)\.(gif|jpg|jpeg|tiff|svg|png|css|php)$" => "/$0",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4&$5&$6&$7&$8&$9&$10",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4&$5&$6&$7&$8&$9",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4&$5&$6&$7&$8",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4&$5&$6&$7",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4&$5&$6",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4&$5",
"^/([a-z|0-9\-]+)/(.+)/(.+)/(.+)/" => "/?page=$1&$2&$3&$4",
"^/([a-z|0-9\-]+)/(.+)/(.+)/" => "/?page=$1&$2&$3",
"^/([a-z|0-9\-]+)/(.+)/" => "/?page=$1&$2",
"^/([a-z|0-9\-]+)/$" => "/?page=$1"
)
```
Next, add the following to `/etc/lighttpd/lighttpd.conf`
```
$HTTP["host"] == "example.com" { include "librenms.conf" }
```
And enable mod_rewrite by uncommenting
```
# "mod_rewrite",
```
to
```
"mod_rewrite",
```
Don't forget to change 'example.com' to your domain
Enable fastcgi in Lighttpd by running the following commands,
```
lighty-enable-mod fastcgi
lighty-enable-mod fastcgi-php
```
And add the following to /etc/php5/cgi/php.ini
```
cgi.fix_pathinfo = 1
```
then restart Lighttpd:
```
service lighttpd restart
```
# Validate your install
Run validate.php as root in the librenms directory
```
php validate.php
```
This will check your install to verify it is set up correctly.
# Add localhost
```
php addhost.php localhost public v2c
```
This assumes you haven't made community changes--if you have, replace
`public` with your community. It also assumes SNMP v2c. If you're
using v3, there are additional steps (NOTE: instructions for SNMPv3 to
come).
Discover localhost:
```
php discovery.php -h all
```
# Create cronjob
The polling method used by LibreNMS is `poller-wrapper.py`, which was
placed in the public domain by its author. By default, the LibreNMS
cronjob runs `poller-wrapper.py` with 16 threads. The current
LibreNMS recommendation is to use 4 threads per core. The default if
no thread count is `16 threads`.
If the thread count needs to be changed, you can do so by editing the
cron file (`/etc/cron.d/librenms`). Just add a number after
`poller-wrapper.py`, as in the below example:
```
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
```
cp 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:
> <https://docs.librenms.org/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:
```
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
# Daily Updates
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
```
#$config['update'] = 0;
```
so that it looks like this:
```
$config['update'] = 0;
```
# Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer
to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
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.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.

372
doc/Installation/Installation-Ubuntu-1404-Nginx.md
View File

@@ -1,372 +0,0 @@
source: Installation/Installation-Ubuntu-1404-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 5.6.4**
# On the DB Server
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
## MySQL
```bash
apt-get install mysql-server mysql-client
mysql -uroot -p
```
## MariaDB
```bash
apt-get install mariadb-server mariadb-client
mysql -uroot -p
```
Input the MySQL root password to enter the MySQL command-line interface.
Create the database:
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP or DNS name of the server running
LibreNMS. If your database is on the same server as LibreNMS, you can
use `localhost`.
If you are deploying a separate database server, you need to change
the `bind-address`. If your MySQL database resides on the same server
as LibreNMS, you should skip this step.
```bash
vim /etc/mysql/my.cnf
```
Within the [mysqld] section please add:
```mysql
innodb_file_per_table=1
```
Find the line: `bind-address = 127.0.0.1`
Change `127.0.0.1` to the IP address that your MySQL server should
listen on. Restart MySQL:
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
```bash
service mysql restart
```
# On the NMS
This host is where the web server and SNMP poller run. It could be
the same machine as your database server.
Install the required software:
```bash
apt-get install nginx-full php5-fpm php5-cli php5-mysql php5-gd php5-snmp php-pear php5-curl php5-mcrypt php5-json php-net-ipv4 php-net-ipv6 snmp snmpd graphviz fping imagemagick whois mtr-tiny nmap python-mysqldb rrdtool git
```
The packages listed above are an all-inclusive list of packages that
were necessary on a clean install of Ubuntu 12.04/14.04.
You need to configure snmpd appropriately if you have not already done
so. An absolute minimal config for snmpd is:
```snmp
rocommunity public 127.0.0.1
```
Adding the above line to `/etc/snmp/snmpd.conf` and running `service
snmpd restart` will activate this config.
In `/etc/php5/fpm/php.ini` and `/etc/php5/cli/php.ini`, ensure
date.timezone is set to your preferred time zone. See
<http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New York", "Australia/Brisbane", "Etc/UTC".
Please also ensure that `allow_url_fopen` is enabled. Other functions
needed for LibreNMS include
`exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
# Adding the librenms-user
```bash
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
# Cloning
LibreNMS is installed using git. If you're not familiar with git,
check out the [git book][2] or the tips at [git ready][3]. The
initial install from github.com is called a `git clone`; subsequent
updates are done through `git pull`.
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure that the appropriate port (443 for HTTPS, 22 for SSH)
is open in the outbound direction for your server.
```bash
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
The recommended method of cloning a git repository is HTTPS. If you
would like to clone via SSH instead, use the command `git clone
git@github.com:librenms/librenms.git librenms` instead.
Sometimes the initial clone can take quite a while (nearly 3 minutes
on a 10 Mbps fibre connection in Australia is a recent example). If
it's a big problem to you, you can save about 50% of the bandwidth by
not pulling down the full git history. This comes with some
limitations (namely that you can't use it as the basis for further git
repos), but if you're not planning to develop for LibreNMS it's an
acceptable option. To perform the initial clone without full history,
run the following instead:
```bash
cd /opt
git clone --depth 1 https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
# Web Interface
To prepare the web interface (and adding devices shortly), you'll need
to create and chown a directory as well as create a Nginx vhost.
First, create and chown the `rrd` directory and create the `logs` directory:
```bash
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
> NOTE: If you're not running Ubuntu or Debian, you will need to
> change `www-data` to the user and group which run the Nginx web
> server. If you're planing on running rrdcached, make sure that the path is
> also chmod'ed to 775 and chown'ed to librenms:librenms.
Add configuration for `nginx` at `/etc/nginx/conf.d/librenms.conf`
with the following content:
```nginx
server {
listen 80;
server_name librenms.example.com;
root /opt/librenms/html;
index index.php;
access_log /opt/librenms/logs/access_log;
error_log /opt/librenms/logs/error_log;
gzip on;
gzip_types text/css application/x-javascript text/richtext image/svg+xml text/plain text/xsd text/xsl text/xml image/x-icon;
location / {
try_files $uri $uri/ @librenms;
}
location ~ \.php {
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/var/run/php5-fpm.sock;
}
location ~ /\.ht {
deny all;
}
location @librenms {
rewrite api/v0(.*)$ /api_v0.php/$1 last;
rewrite ^(.+)$ /index.php/$1 last;
}
}
```
On at least Ubuntu 14.04 (and possibly other distributions and
versions as well), mcrypt is not enabled on install. Run the
following to enable it:
```bash
php5enmod mcrypt
```
(To get to your LibreNMS install externally, you'll also need add it
to your DNS or hosts file.)
# Start the web-server
Restart nginx:
```bashg
service nginx restart
```
Restart php5-fpm:
```bash
service php5-fpm restart
```
# Manual vs. web installer
At this stage you can either launch the web installer by going to
<http://librenms.example.com/install.php>, follow the onscreen
instructions then skip to the 'Add localhost' section. Alternatively
if you want to continue the setup manually then just keep following
these instructions.
```bash
cp config.php.default config.php
vim config.php
```
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as setup above.
Change the value of `$config['snmp']['community']` from `public` to
whatever your read-only SNMP community is. If you have multiple
communities, set it to the most common.
** Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise. **
# Initialise the database
Initiate the follow database with the following command:
```bash
php build-base.php
```
# Create admin user
Create the admin user - priv should be 10
```bash
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and
leave the angled brackets off.
# Validate your install
Run validate.php as root in the librenms directory
```bash
php validate.php
```
This will check your install to verify it is set up correctly.
# Add localhost
```bash
php addhost.php localhost public v2c
```
This assumes you haven't made community changes--if you have, replace
`public` with your community. It also assumes SNMP v2c. If you're
using v3, there are additional steps (NOTE: instructions for SNMPv3 to
come).
Discover localhost::
```bash
php discovery.php -h all
```
# Create cronjob
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the
cron job runs `poller-wrapper.py` with 16 threads. The current
recommendation is to use 4 threads per core as a rule of thumb. If
the thread count needs to be changed, you can do so by editing the
cron file (`/etc/cron.d/librenms`). Just add a number after
`poller-wrapper.py`, as in the example below:
```bash
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
```bash
cp 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:
> <https://docs.librenms.org/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 misc/librenms.logrotate /etc/logrotate.d/librenms
```
# Daily Updates
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
```php
#$config['update'] = 0;
```
so that it looks like this:
```php
$config['update'] = 0;
```
# Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer to the
[FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
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.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
[1]: https://github.com/Atrato/observium-poller-wrapper
[2]: http://git-scm.com/book
[3]: http://gitready.com/

5
doc/Installation/index.md
View File

@@ -39,7 +39,4 @@ These install docs are no longer updated and may result in an unsuccessful insta
- [RHEL / CentOS 7 Nginx](Installation-CentOS-7-Nginx/)
- [Ubuntu 16.04 Apache](Installation-Ubuntu-1604-Apache/)
- [Ubuntu 16.04 Nginx](Installation-Ubuntu-1604-Nginx/)
- [Debian/Ubuntu](Installation-Ubuntu-1404-Apache/)
- [RHEL/CentOS](Installation-CentOS-6-Apache-Nginx/)
- [Debian/Ubuntu Lighttpd](Installation-Ubuntu-1404-Lighttpd/)
- [Debian/Ubuntu Nginx](Installation-Ubuntu-1404-Nginx/)
- [RHEL / CentOS 6](Installation-CentOS-6-Apache-Nginx/)

6
doc/index.md
View File

@@ -7,9 +7,9 @@ path: blob/master/doc/
<span> Installing</span>
</a>
</div>
<a href="/Installation/">Installing LibreNMS</a><br />
<a href="/Installation/Installation-Ubuntu-1804-Nginx/">Ubuntu 18.04 + Nginx</a><br />
<a href="/Installation/Installation-CentOS-7-Nginx/">CentOS 7 + Nginx</a><br />
<a href="/Installation/">Ways to install</a><br />
<a href="/Installation/Install-LibreNMS/">Install LibreNMS Now</a><br />
<a href="https://github.com/librenms/docker">Install Using Docker</a><br />
<a href="/Installation/Installing-LibreNMS/"><strong>More...</strong></a>
</div>
<div class="home-box">

4
scripts/deploy-docs.sh
View File

@@ -10,6 +10,7 @@ fi
pip3 install --upgrade pip
pip3 install --user --requirement <(cat <<EOF
future==0.18.2
Jinja2==2.11.2
livereload==2.6.1
lunr==0.5.8
Markdown==3.2.2
@@ -17,7 +18,10 @@ mkdocs==1.1.2
mkdocs-material==5.2.2
nltk==3.5
pymdown-extensions==7.1
PyYAML==5.3.1
six==1.15.0
tornado==6.0.4
MarkupSafe==1.1.1
EOF
)