1 Installing LibreNMS (HowTo)

1 Installing LibreNMS (HowTo)

1.1 Version

HowTo Document for Installing LibreNMS from source on Ubuntu Server 16.04 LTS

1.2 Goals

Learn how to initially install the LibreNMS Network Management System

1.3 Notes

Commands preceded with "$" imply that you should execute the command as a general user - not as root.
Commands preceded with "#" imply that you should be working as root.
Commands with more specific command lines (e.g. "rtrX>" or "mysql>") imply that you are executing commands on remote equipment, or within another program.
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 invoke root privileges with ''sudo -s''.

1.4 Create database

NOTE: These instructions are based on the official LibreNMS installation notes and have been tested on a fresh install of Ubuntu 16.04.

We will assume that the database is running on the same machine as your network management server (this is the most common initial deployment scenario).

For this class we will install on srv1.campusY.ws.nsrc.org. Connect to this machine and become root:

$ sudo bash

Then install mysql and configure:

# apt update
# apt install mysql-server mysql-client

You will be asked to enter a password for the MySQL root user. Be absolutely sure that you remember what you choose here. You will use this later.

# mysql -uroot -p

Input the MySQL root password (the one you chose in the previous step) to enter the MySQL command-line interface where you will get a mysql> prompt. If you are not sure of the password just use the <CLASS_PASSWORD>':

CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY '\<CLASS_PASSWORD\>';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
exit

PLEASE NOTE

Here we are using <CLASS_PASSWORD> as the password for LibreNMS to access MySQL. Please replace <CLASS_PASSWORD> with, you've guessed it, the class password :)

To optimize the database settings for LibreNMS, you should add the following two lines at the end of the file mysqld.conf:

# editor /etc/mysql/mysql.conf.d/mysqld.cnf

innodb_file_per_table=1
lower_case_table_names=0

Now restart the mysql server to activate these changes. Then check that mysql restarted successfully:

# systemctl restart mysql
# systemctl status mysql

1.5 Install LibreNMS

The NMS is the host is where the web server and SNMP poller run.

Ubuntu 16.04 doesn't ship with a current version of php, so we need to install it from a custom repository. Once we confirm that php7.2 is installed we can enable it in Apache.

# add-apt-repository ppa:ondrej/php
# apt update
# apt install php7.3
# php -v
# a2dismod php7.0
# a2enmod php7.3
# systemctl restart apache2

Don't worry if php is already disabled and enabled in Apache. We run a2dismod and a2enmod to ensure that php is functioning with our Apache web server.

Now, install the required software:

apt install acl apache2 composer fping git graphviz imagemagick libapache2-mod-php7.3 mtr-tiny nmap php7.3-cli php7.3-curl php7.3-gd php7.3-json php7.3-mbstring php7.3-mysql php7.3-snmp php7.3-xml php7.3-zip python-memcache python-mysqldb rrdtool snmp snmpd whois

The packages listed above are an all-inclusive list of packages that were necessary on a clean install of Ubuntu 16.04.

1.5.1 Post install configuration

1.5.1.1 snmp

You need to configure snmpd appropriately if you have not already done so. We will do a minimal snmp configuration on our server -- please DON'T do this if you've already configured SNMP earlier!

# mv /etc/snmp/snmpd.conf /etc/snmp/snmpd.conf.orig
# editor /etc/snmp/snmpd.conf

and, add the following line to the empty file:

rocommunity NetManage 127.0.0.1

And, now restart the snmp service so that the changes become active.

# systemctl restart snmpd

You can verify that snmp now responds to you locally by typing:

# snmpstatus -v2c -c NetManage 127.0.0.1 sysStatus

1.5.1.2 php

In both ''/etc/php/7.3/apache2/php.ini'' and ''/etc/php/7.3/cli/php.ini'', ensure ''date.timezone'' is set to your preferred time zone.

See <http://php.net/manual/en/timezones.php> or files under ''/usr/share/zoneinfo'' for a list of supported timezones. For this workshop we are all going to use the same timezone, that is PLEASE USE UTC only. If you select anything other than UTC then other programs will not work properly.

In the two archives noted above find the line that reads:

;date.timezone =

and change it to:

date.timezone = Etc/UTC

Save and exit from the files.

1.6 Adding the LibreNMS user

We need to create a LibreNMS system user, librenms.

# useradd librenms -d /opt/librenms -M -r
# usermod -a -G librenms www-data

1.7 Clone the LibreNMS software with git

# cd /opt
# git clone --depth 1 https://github.com/librenms/librenms.git

Now we need to set the permissions so that the librenms user can access the files.

# chown -R librenms:librenms /opt/librenms

1.8 Install the PHP dependencies with composer

LibreNMS dependencies are installed using composer. The initial install can take quite a while (nearly 3 minutes on a 10Mbps connection is typical) as the size of the software installed is 220+ MB in size.

Run the following:

# su - librenms
$ ./scripts/composer_wrapper.php install --no-dev
$ exit

At this point, you should have a ''librenms'' directory, with the most recent version of the libreNMS software.

1.9 Web Interface

To prepare the web interface (and adding devices shortly), you'll need to create and change the ownership and permissions of a directory as well as create an Apache virtual host definition.

We need to change back to the root user on our srv1.campusY.ws.nsrc.org host so be sure you type exit to and that your command prompt changes to #:

$ exit
# chown -R librenms:librenms /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/

Next, create ''/etc/apache2/sites-available/librenms.conf'':

 # editor /etc/apache2/sites-available/librenms.conf

Add the following lines:

<VirtualHost *:80>
  DocumentRoot /opt/librenms/html/
  ServerAlias librenms*.ws.nsrc.org
  CustomLog /opt/librenms/logs/access_log combined
  ErrorLog /opt/librenms/logs/error_log
  AllowEncodedSlashes NoDecode
  <Directory "/opt/librenms/html/">
    Require all granted
    AllowOverride All
    Options FollowSymLinks MultiViews
  </Directory>
</VirtualHost>

Now enable the Virtual Host, but wait to restart Apache

# a2ensite librenms
# a2enmod rewrite

Now you need to give the web server access to /opt/librenms temporarily. First do:

# chown www-data /opt/librenms

and now restart the web server:

# systemctl restart apache2

1.10 Web installer

You can choose either a web configuration or manual configuration at the command line. We're going to use the Web installer, which is by far the easiest.

At this stage you can launch the web installer by going to http://librenms.campusY.ws.nsrc.org/install.php

Follow the onscreen instructions.

Stage 0 is a summary of the PHP modules installed, normally you should just click on ''Next Stage''
Stage 1 prompts you for the database settings. Enter
- DB Host: localhost
- DB User: librenms
- DB Pass: <CLASS_PASSWORD>
- DB Name: librenms
Stage 2 is the DB creating itself - it should finish correctly, and you simply click on ''Goto Add User'' at the bottom
Stage 3: enter a username, password and E-mail address. This will become the login you use to access the web interface.

We suggest you use ''admin'', the class password, and your own E-mail address.

Stage 4 should show you the successful user creation, click on ''Generate Config''
Stage 5: the interface should show, at this point:

The config file has been created

You can now click ''Finish install''.

Note: IF the installer tells you it can't write the configuration file, it may be that you forgot to run ''chown www-data /opt/librenms''

You should try and fix the problem, and reload http://librenmsN.ws.nsrc.org/install.php

See the end of this exercise if you still have problems.

Stage 6: you are (almost) done!

Click on the link that says, "Click here to Validate your installation and fix any problems". This will take you to the initial login page and you are done with the initial install.

A useful tool is provided with LibreNMS to help verify that the software is installed correctly.

Before we run the tool let's set our directory permissions back to what they should be to secure them properly:

# chown -R librenms:librenms /opt/librenms
# setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
# chmod -R ug=rwX /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/

Let's try running the LibreNMS validation script:

# cd /opt/librenms
# ./validate.php

You should see a warning that no devices have been added. This is fine and we will add devices in the next part of this lab. If you see permission warnings you can choose to fix them as suggested. If you see a warning about modified files in git you can ignore this for now.

Generate the security key for libreNMS:

# sudo -Hu librenms php artisan key:generate

Install the LibreNMS cron job:

# cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms

Set up LibreNMS logs to rotate:

# cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms

=> YOU CAN NOW PROCEED TO THE FINE TUNING LAB ! <=

1.10.1 If you're still experiencing problems...

If it still doesn't work, you will need to copy the generated configuration displayed in the Browser window and place this in a new file:

''/opt/librenms/config.php''

using a text editor of your choice. (Remember if you are using "vi" to enter insert mode before you paste)

LibreNMS

Campus Network Design Workshop