Workshops

In this exercise, we will set up LibreNMS as our network monitoring package. The software will poll your routers and switches using SNMP and provide visibility of OSPF sessions and other useful information

Throughout these instructions we will use the names and addresses related to campusX. You should make sure you change any names and addresses in the examples to match your assigned group of machines.

ssh sysadm@pc1-campusX.ws.nsrc.org

The password will be given in class.

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.

LibreNMS stores its data in a MySQL database. 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).

apt-get install mysql-server mysql-client

You will be prompted for a root password for MySQL during the installation. Use the login password you were given in class. Then we can connect to the MySQL server:

mysql -uroot -p

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

Create the librenms database:

CREATE DATABASE librenms;
GRANT ALL PRIVILEGES ON librenms.*
  TO 'librenms'@'localhost'
  IDENTIFIED BY 'abc123'
;
FLUSH PRIVILEGES;
exit

Here we are using “abc123” as the password for librenms to access MySQL.

NOTE: Don't use a password like this on a production server!

Install the required software:

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 mysql-client 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 14.04.

LibreNMS is installed using software called git.

The initial install from github.com is called a git clone; subsequent updates are done through git pull. The command used was:

git clone http://github.com/librenms/librenms.git

but don't run this command on your PC because the initial clone can take quite a while (nearly 5 minutes on a 10Mbps connection is typical). For this workshop the instructors have set up a local mirror on the workshop webserver for you to use.

Run the following:

cd /opt
wget http://www.ws.nsrc.org/downloads/librenms.tar.gz
tar zxf librenms.tar.gz

You should now have a new directory called /opt/librenms which contains the software.

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.

1) Create and chown the rrd directory and create the logs directory:

cd /opt/librenms
mkdir rrd logs
chown www-data:www-data logs/ rrd/

2) Create /etc/apache2/sites-available/librenms.conf containing the following:

<VirtualHost *:80>
  DocumentRoot /opt/librenms/html/
  ServerName  librenms.campusX.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 X in librenms.campus**X**.ws.nsrc.org to correspond to your management PC name. For example:

pc1-campus1.ws.nsrc.org => librenms.campus1.ws.nsrc.org

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

php5enmod mcrypt

4) Now enable the vhost and restart Apache

a2ensite librenms
a2enmod rewrite
service apache2 restart

We need to configure MySQL password details in the LibreNMS software:

cd /opt/librenms
cp config.php.default config.php
editor 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.

$config['db_host'] = "localhost";
$config['db_user'] = "librenms";
$config['db_pass'] = "abc123";
$config['db_name'] = "librenms";

Change the value of $config['snmp']['community'] from public to NetManage:

$config['snmp']['community'] = "NetManage";

Save the changes!

Initiate the librenms database with the following command:

php build-base.php

Create the admin user - priv should be 10

php adduser.php <name> <pass> 10

Substitute your desired username and password – and leave the angled brackets off. We suggest you use sysadm and the class password.

LibreNMS uses hostnames when it monitors devices. Normally we'd add our routers to the DNS but for this workshop we'll just add our ISP routers to the /etc/hosts file. Edit /etc/hosts and add entries for your devices. For example, if you have been allocated 100.68.X.0/24, then your entries would look like:

100.68.X.1  r1-bdr-campusX
100.68.X.2  r1-core-campusX
172.2X.0.2  sd1-b1-campusX
172.2X.0.3  se1-b1-campusX
172.2X.0.4  se2-b1-campusX
172.2X.0.18 sd1-b2-campusX
172.2X.0.19 se1-b2-campusX
172.2X.0.20 se2-b2-campusX

Make sure you change 'X' to match your campus group

Save the changes and check that you can ping the routers using these names.

Now we can add the devices to LibreNMS:

php addhost.php r1-bdr-campusX NetManage v2c
php addhost.php r1-core-campusX NetManage v2c
etc....

This assumes you haven't made SNMP community changes – if you have, replace NetManage with your community. It also assumes SNMP v2c.

Discover the newly added hosts and poll them for the first time: do this at the command line so you can see if it is working properly.

cd /opt/librenms
php discovery.php -h all && php poller.php -h all

Create the cronjob which will run periodic tasks required by librenms

cp librenms.cron /etc/cron.d/librenms

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;

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

You should use your instance of LibreNMS to monitor your routers and switches during the workshop - you'll be able to see information about your OSPF sessions once they're working.

NOTE: These instructions are based on the official LibreNMS installation notes at:

http://docs.librenms.org/Installation/Installation-(Debian-Ubuntu)/

and have been tested on a fresh install of Ubuntu 14.04.