1 Configuring LibreNMS

1.1 Goals

1.2 Introduction

In this exercise, we will set up LibreNMS as our network monitoring package.

1.2.1 Connecting to your LibreNMS server

LibreNMS is running on your srv1 server, that is you can connect to the server by going to:

srv1.campusY.ws.nsrc.org

You should do this for these first few steps, then when you are ready to view LibreNMS in your web browser you will go to:

http://librenms.campusY.ws.nsrc.org

The Username is "admin" and the password is "<CLASS_PASSWORD>".

1.3 Looking at the LibreNMS configuration

LibreNMS is already largely set up on your server. The next few exercises will have you look at the libreNMS config.php file to understand some of the basic items that need to be set when you first install the package. Most of these are already set up correctly, but it is good to verify and to know what you would do if you were to install LibreNMS on your own.

1.3.1 Setting the SNMP community

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

First, if you not already root, you should do:

$ sudo bash

Next, edit the file /opt/librenms/config.php,

# editor /opt/librenms/config.php

and find the line:

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

And change it to the following if it has not already been done:

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

1.3.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 on the safe side, and not scan networks outside your organization, 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 lines that look like this:

$config['nets'][] = "10.0.0.0/8";
#$config['nets'][] = "172.16.0.0/12";
#$config['nets'][] = "192.168.0.0/16";

And change this block of nets to look like:

$config['nets'][] = "100.68.Y.128/28";
$config['nets'][] = "172.2Y.0.0/16";

Remember, to replace "Y" with your campus number.

We need to make one more change...

1.3.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, add the following line at the bottom of the config.php file:

(this may already be done)

$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!

1.3.4 Add a host

Let's add localhost (i.e.: YOUR virtual host), 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:

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.

1.4 Final Configuration

1.4.1 Discover and Poll newly added hosts

LibreNMS first “discovers” each host that has been added. This means that it methodically examines each host you added and figures out what it should monitor. The discover.php script does not automatically scan your network to find new devices. To run this script do:

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

NOTE: This could take some time. If you try to add devices that do not yet have an snmp service configured, then the discovery script takes a while to time out.

Once this has finished you can now "poll" the hosts. This means LibreNMS now knows what it wishes to monitor for each host, but it has yet to populate its database with initial values for each item. To do this we do:

# sudo -u librenms php poller.php -h all

As you can see the poller.php script does quite a bit with just a few devices. When we add it to a cronjob below this helps explain why LibreNMS is a resource intensive tool.

1.5 Install complete

That's it! You now should be able to log in to http://librenms.campusY.ws.nsrc.org/ and begin to explore the information being collected for your monitored devices.

You can add some additional devices via the LibreNMS web interface. Why not add:

What about your other hosts? host[1..6].campusY.ws.nsrc.org, srv1.campusY.ws.nsrc.org?

Using the class snmp community. See if you can figure out how to do this on your own.

NOTE: When you first add a device it may end up in the "Generic" devices group. This is because LibreNMS needs to run it's cron job to poll all devices, obtain more specific device information and then classify the device in the proper group. This could take 5 to 10 minutes from the time you add the device.

PLEASE NOTE: 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.

1.6 Customize your Installation

When you first log in to LibreNMS your default screen is empty. This is because you are allowed to edit your default screen using the Dashboard editing tool to make it look as you prefer. To do this do:

* Click on the Edit Dashboard icon that looks like a Pencil next to a Red icon of a garbage 
can. 
* Name your Dashboard or leave it as "Default"
* If you select Private then your dashboard is only available to your user. 
* If you make it Shared (Read) then you control the look, but other can use it.
* If you make it just Shared, then anyone can update the look and feel of the dashboard.
* Click on Add Widgets and select items you would like to see by default when you log in.
 * Place the selected widget on the screen where you want it.
* You can click on the "X" to close the notice about editing dashboards so that it 
does not appear next time you log in.
* If you want specific graphs you can select the "Graph" widget and customize this.
* Many people use the Top-devices and Top-interfaces widgets.
 * For Top-interfaces note you can set the details on this widget. When done, press the "Set" button.

Remember, you can resize the widgets as you like.

When you are done press the "Update" button. Note that the top-devices and top-interfaces widgets will take some time before they populate with interesting information, so they will appear as largely blank for a while.

If you create multiple Dashboards you can switch between your default log in Dashboard by going to the person icon, selecting "My Settings" and going down to "Default Dashboard".

1.7 View a Real-Time Graph on an Interface

In the LibreNMS interface do:

* Select Devices ==> All Devices ==> Server
* Select a server from the resulting screen (click on it's name)
* Click on the "Ports" item near the top.
* Click on network interface "eth0"
* Next to the Graphs item select "Real time"
* Select a "Polling Interval" that is long enough to see information. 
 * Click on "60s"

If you do not see any traffic, go to that host and do something... Like,

$ ping hostX.campusY.ws.nsrc.org

Or some other device or machine, or run an apt-get update, etc...

1.8 A few other items

1.9 Creating an Alert

LibreNMS has a number of built-in alerts that you can add easily. By default you will set up a Default contact for your install. This is the contact that will receive all alerts.

We are going to set up an alert that will trigger if a device goes down and when a device comes backup. You can, also, set up an alert that triggers only when a device goes down - as well as many, many other alerts.

To get started we need to set up our LibreNMS install to work with alerts.

In your LibreNMS interface do the following:

Enable email alerting:          Yes
How to deliver mail:            smtp
From name:                      LibreNMS
From email address:             root@srv1.campusY.ws.nsrc.org
Use HTML emails:                No
Sendmail path:                  /usr/sbin/sendmail
SMTP Host:                      localhost
SMTP Port:                      25
SMTP Timeout:                   10
SMTP secure:                    <blank>
SMTP Auto TLS Support:          false
SMTP Authentication:            No
SMTP Authentication Username:   NULL
SMTP Authentication Password:   <blank>

You can test that your email is working on srv1.campusY.ws.nsrc.org by clicking on the "Test transport" button on the "Email transport" tab.

NOTE: Email may not work for your sysadm@srv1.campusY.ws.nsrc user. To fix this do the following from the command line:

# touch /var/mail/sysadm
# chown sysadm:mail /var/mail/sysadm

You may need to click the "Test Transport" button again, then type:

# su - sysadm
$ mutt

and see if email has arrived from LibreNMS. It should have a subject of " Testing transport from LibreNMS". You can exit from Mutt by press the "q" key twice.

Now we are ready to add an alert to our LibreNMS install.

Now we need to fill in some reasonable choices. The devices.status Entity will alert whenever a device goes down, or comes back up. This means an email will be sent to sysadm@srv1.campusY.ws.nsrc.org from root@srv1.campusY.ws.nsrc.org.

You can enter in the following to the Alert Rules box:

Entity:         devices.status
Condition:      Equals
Value:          <blank>
Connection:     <leave as is>
Severity:       Critical
Max alerts:     1
Delay:          1 m
Interval:       <blank>
Mute alerts:    OFF
Invert match:   OFF
Rule name:      Devices up/down
Map to:         <blank>
Procedure URL:  <blank>

Now press "Save Rule".

To verify that your new alert is working you need to bring down a host that you are monitoring in LibreNMS. Select one of the hosts in your campus that is visible in LibreNMS and halt that host. To do this log in on the host (hostX.campusY.ws.nsrc.org) and type:

$ sudo halt -p

Now go back to the srv1.campusY.ws.nsrc.org command line and type:

$ mutt

and wait for a few minutes. Eventually you should get an email with a subject like:

Alert for device hostX.campusY.ws.nsrc.org - Devices up/down

You can read the alert and it will say something like:

Date: Tue, 20 Feb 2018 10:29:01 +0000
From: root@srv1.campusY.ws.nsrc.org
To: NOC <sysadm@srv1.campusY.ws.nsrc.org>
Subject: Alert for device hostX.campusY.ws.nsrc.org - Devices up/down
X-Mailer: LibreNMS

Alert for device hostX.campusY.ws.nsrc.org - Devices up/down
Severity: critical
Timestamp: 2018-02-20 10:25:28
Unique-ID: 371
Rule: Devices up/down
Faults:
  #1: sysObjectID => enterprises.8072.3.2.10; sysDescr => Linux
hostX.campusY.ws.nsrc.org 4.4.0-96-generic #119-Ubuntu SMP Tue Sep 12
14:59:54 UTC 2017 x86_64;
Alert sent to: NOC <sysadm@srv1.campusY.ws.nsrc.org>

Notice the sysObjectID and the SysDescr items. These are names for OIDs that are contained within install MIB files on the srv1.campusY.ws.nsrc.org host.

Now you can exit from Mutt (press "q" twice) and return to the root prompt

$ exit
#

Note that when we bring your host back up you will receive another alert with a subject like:

Device hostX.campusY.ws.nsrc.org recovered from Devices up/down

If you add an alert with the Entity field of "macros.device_down" you will only be alerted when the device goes down.

Note: You should ask an instructor to restart the host that you brought down at this time.

1.10 Global Frontpage Map

It is possible to create a global map of all your entries that is displayed by LibreNMS. If you are interested you can view the LibreNMS documentation on this at:

* http://docs.librenms.org/Extensions/Globe-Frontpage/
* http://docs.librenms.org/Support/SNMP-Configuration-Examples/

You must use the sysLocation snmp variable on your hosts and network devices providing latitude and longitude information for each item for this to work.

1.11 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;

We recommend that you do not make this change, but it is good to be aware of this option.