1 LibreNMS

2 Installing and configure LibreNMS

2.1 Goals

Learn how to configure LibreNMS Network Management System

2.2 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.

3 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).

First become root:

    $ sudo bash

Then install mysql if not already done:

    # apt-get install mysql-server mysql-client

You can select any password for the mysql root user. But be absolutely sure that you remember what you choose here. You will use this later.

You need to make a configuration change to mysql for it to work properly with librenms. Create the following file:

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

and paste in the following content:

[mysqld]
innodb_file_per_table=1
sql-mode=""

After making this change, restart mysql:

# service mysql restart

Now you can connect to the database:

# mysql -uroot -p

Input the MySQL root password to enter the MySQL command-line interface where you will get a mysql> prompt.

Create the database:

CREATE DATABASE librenms;
GRANT ALL PRIVILEGES ON librenms.*
  TO 'librenms'@'localhost'
  IDENTIFIED BY '<CLASS_PASSWORD>'
;
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 guessed it, the class password :)

4 Install LibreNMS

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

Install the required software:

    apt-get install libapache2-mod-php php-cli php-mysql php-gd php-snmp \
        php-pear php-curl snmp graphviz php-mcrypt php-json apache2 fping \
        imagemagick whois mtr-tiny nmap python-mysqldb snmpd php-net-ipv4 \
        php-net-ipv6 rrdtool git

Here is the command above on a single line that may be easier to copy and paste in to your terminal:

apt-get install libapache2-mod-php php-cli php-mysql php-gd php-snmp php-pear php-curl snmp graphviz php-mcrypt php-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 16.04.

You need to configure snmpd appropriately if you have not already done so. An absolute minimal config for snmpd is:

    rocommunity NetManage 127.0.0.1

Adding the above line to /etc/snmp/snmpd.conf and running service snmpd restart will activate this config, but please DON'T do this if you've already configured SNMP earlier!

In /etc/php/7.0/apache2/php.ini and /etc/php/7.0/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 linea that reads:

;date.timezone =

and change it to:

date.timezone = Etc/UTC

Save and exit from the files.

4.1 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

4.2 Cloning the LibreNMS source code with git

LibreNMS is installed using git. If you're not familiar with git, check out the git book or the tips at git ready. The initial install from github.com is called a git clone; subsequent updates are done through git pull.

The initial clone can take quite a while (nearly 3 minutes on a 10Mbps connection is typical), so for this workshop we have set up a local mirror for you to use.

Run the following:

    # cd /opt
    # git clone http://www.ws.nsrc.org/git/librenms.git

At this point, you should have a librenms directory, with the most recent revision checked out. It's strongly suggested to check out the most recent stable.

To do this:

    # cd librenms
    # git tag

Look for the most recent tag in the form YYYYMM, and then type:

    # git checkout YYYYMM

For instance, if the newest tag is 201605, then do git checkout 201605.

Note: if for some reason cloming from the NOC above fails, then you can fallback to using the repository on GitHub. This will take longer!

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

4.3 Web Interface

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

First, create and chown the rrd directory and create the logs directory:

    # cd /opt/librenms
    # mkdir rrd logs
    # chown -R librenms:librenms /opt/librenms
    # chmod 775 rrd
    # chown www-data /opt/librenms

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/
  ServerName  librenmsN.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>

Change the N in librenmsN.ws.nsrc.org to your PC number.

On Ubuntu 16.04, mcrypt is not enabled on install. Run the following to enable it:

    # phpenmod mcrypt

Now enable the Virtual Host, and restart Apache

    # a2ensite librenms.conf
    # a2enmod rewrite
    # service apache2 restart

4.4 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, but we'll include the manual configuration as a reference at the end of this document.

At this stage you can launch the web installer by going to

http://librenmsN.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 sysadm, 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://librenmsX.ws.nsrc.org/install.php.

See below if you still have problems.

Stage 6: you are done!

You can now follow the instructions and click where it says click here to login to your new install.

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

Let's try it out:

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

You may see warnings about the software notbeing up to date, and some more about permissions. You can probably ignore these for now, but it might come in useful later if you experience issues with LibreNMS.

We can now secure the /opt/librenms directory again:

    # chown librenms /opt/librenms

=> YOU CAN NOW PROCEEED TO BASIC CONFIGURATION! <=

4.4.1 If you're still experiencing problems...

If it still doesn't work, you will need to copy the generated config the configuration from the browser window, create a new file /opt/librenms/config.php with a text editor, and paste the config into this file).

(Remember if you are using "vi" to enter insert mode before you paste)

4.5 Basic configuration

We're going to make a few changes to the configuration file:

Change the default SNMP community
Allow xDP (CDP/LLDP) autodiscovery of the network
Tell LibreNMS which networks it's allowed to scan/discover

4.5.1 Setting the SNMP community

First, let's change the SNMP community that LibreNMS will try when discovering and adding new devices.

Edit the file /opt/librenms/config.php, and find the line:

    $config['snmp']['community'] = array("public");

And set it to:

    $config['snmp']['community'] = array("NetManage");

4.5.2 Tell LibreNMS which subnets it's allowed to scan automatically

By default, LibreNMS will try ask for the list of "neighbors" that network devices "see" on the network. This is done using the Link Layer Discovery Protocol (LLDP) or Cisco's CDP (Cisco Discovery Protocol).

But to be, safe and not scan too many hosts outside your own networks, LibreNMS needs to be told which subnets it's allowed to scan for new devices.

Still in the file /opt/librenms/config.php, find the line:

    #$config['nets'][] = "10.0.0.0/8";

... and remove tjhe # in front so it looks like:

    $config['nets'][] = "10.0.0.0/8";

We need to make one more change...

4.5.3 Tell LibreNMS not to add duplicate devices

A situation can happen where two devices have duplicate SNMP sysName. (that's hostname in IOS) They could be two different devices, so it would be a good idea to have LibreNMS automatically add and monitor them.

But it can also happen that the SAME device is seen multiple times by LibreNMS - once using LLDP/CDP, and another time via OSPF (for example).

In that case, it ends up added twice. For instance, you may suddenly see two devices called rtr2-fa0-0.ws.nsrc.org and rtr2, and this is not what we want.

Since "both" devices are in fact the same, their SNMP sysName will be identical, and we can tell LibreNMS to NOT add devices if one already exists with the same sysName - after all, this shouldn't happen in a well configured network! :)

Here's an example of this:

2016-07-06 20:16:47 rtr4 discovery Device rtr4 (10.10.0.224) (port FastEthernet0/0) autodiscovered through CDP on rtr1.ws.nsrc.org
2016-07-06 20:09:45 rtr4-fa0-0 discovery Device rtr4-fa0-0.ws.nsrc.org (10.10.0.224) (port ) autodiscovered through OSPF on rtr1-fa0-0.ws.nsrc.org

To avoid this, we will add the following seting:

$config['allow_duplicate_sysName'] = false;

... this will prevent LibreNMS from adding the device if it exists already with the same sysName. You will be able to see if there are duplicate devices deteced in the Event Log (Overview -> Event Log).

After you've added the above setting, save the file and exit - we're nearly done!

4.5.4 Add a host.

Let's add localhost (i.e.: YOUR virtual server), using the following commands. Later you'll do this from the Web interface:

    # cd /opt/librenms
    # php addhost.php localhost NetManage v2c

You should see:

Trying community NetManage ...
Added device localhost (1)

Notice we explicitly tell LibreNMS which SNMP community to use. We also assume it's SNMP v2c. If you're using v3, there are additional steps which aren't provided here.

4.6 Final configuration

4.6.1 Test poller

We need to tell LibreNMS to discover localhost, and poll it for the first time: do this at the command line so you can see if it is working properly.

    # cd /opt/librenms
    # sudo -u librenms php discovery.php -h all
    # sudo -u librenms php poller.php -h all

4.6.2 Create cronjob

Create the cronjob which will run periodic tasks required by LibreNMS:

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

One last thing: edit the file /etc/cron.d/librenms and find the line:

*/5  * * * *  librenms  /opt/librenms/cronic /opt/librenms/poller-wrapper.py 16

And change the 16 at the end to 4 (we have a single processor, and 4 threads is plenty)

*/5  * * * *  librenms  /opt/librenms/cronic /opt/librenms/poller-wrapper.py 4

Save, and exit.

4.7 Install complete

That's it! You now should be able to log in to http://librenmsN.ws.nsrc.org/. 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.

4.8 About Daily Updates

LibreNMS performs daily updates by default. At 00:15 system time every day, a git pull --no-edit --quiet is performed. If you don't want this, change the 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;