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.
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
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
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
cd /opt/librenms mkdir rrd logs chown www-data:www-data logs/ rrd/
/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:
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'] = "NetManage";
Save the changes!
Initiate the librenms database with the following command:
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:
and have been tested on a fresh install of Ubuntu 14.04.