= LibreNMS =

Shutdown the !NetMon VM by following command as root
{{{
shutdown -now
}}}

start the libreNMS VM as you will install LibreNMS in a seperate VM as recomended.

== Installation == 

NOTE: These instructions assume you are the root user. If you are not, prepend sudo to the shell commands 

=== Installing LibreNMS ===
First install required packages.
{{{
apt-get install apache2 composer fping git graphviz imagemagick libapache2-mod-php7.0 mariadb-client mariadb-server mtr-tiny nmap php7.0-cli php7.0-curl php7.0-gd php7.0-json php7.0-mcrypt php7.0-mysql php7.0-snmp php7.0-xml php7.0-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
}}}
give <class password> as databse root password.

Add librenms user and user's home directory
{{{
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
}}}

Install LibreNMS
{{{
cd /opt
git clone https://github.com/librenms/librenms.git librenms
}}}

=== Database Configuration ===

Configure MySQL
{{{
systemctl restart mysql
mysql -u root -p
}}}

Create '''librenms''' database and '''librenms''' database user. grant all privileges to the created user.
{{{
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 mysql
{{{
exit
}}}

We need to change some mysql server settings. To do that edit '''50-server.cnf''' file
{{{
vi /etc/mysql/mariadb.conf.d/50-server.cnf
}}}

Add the following llines within the '''[mysqld]''' section 
{{{
innodb_file_per_table=1
sql-mode=""
lower_case_table_names=0
}}}

Restart the mysql server
{{{
systemctl restart mysql
}}}

=== Web server Configuration ===

==== Configure PHP ====

To set the correct time zone edit '''php.ini'''
{{{
vi /etc/php/7.0/apache2/php.ini
}}}

Find the line ''';date.timezone''' and change the line as follows
{{{
date.timezone = Asia/Colombo
}}}

Do the same to the '''vi /etc/php/7.0/cli/php.ini'''

Enable php modules in apache
{{{
a2enmod php7.0
a2dismod mpm_event
a2enmod mpm_prefork
phpenmod mcrypt
}}}

==== Configure Apache ====

Create '''librenms.conf''' to enable the site
{{{
vi /etc/apache2/sites-available/librenms.conf
}}}

Add the following lines:
{{{
<VirtualHost *:80>
  DocumentRoot /opt/librenms/html/
  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>
}}}

Enable the librenms site and restart apache server
{{{
a2ensite librenms
a2enmod rewrite
a2dissite 000-default
systemctl restart apache2
}}}

=== Configure snmpd ===

Create the snmpd configuration file
{{{
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
}}}

Edit the text which says '''RANDOMSTRINGGOESHERE''' and set your own community string.

Also add

sysname <your name>

Install the libreNMS agent and restart snmpd
{{{
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
}}}

=== Cron job ===
{{{
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
}}}

Copy logrotate config

LibreNMS keeps logs in /opt/librenms/logs. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
{{{
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
}}}

=== Set permissions ===
{{{
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs
}}}

=== 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://<your ip address>/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 following username, Password and e-mail address. This will become the login you use to access the web interface.

 - Username : '''admin'''
 - Password : < class password >
 - e-mail address : <your e-mailaddress>

Stage 4 should show you the successful user creation, click on '''Generate Config'''. It will show you the config file. Copy all the content and create the config.php file and paste the content in the file.
{{{
vi /opt/librenms/config.php 
}}}
Click Next

Stage 5: the interface should show, at this point:

The config file has been created

You can now click ''''Finish install''''.

== Configuring LibreNMS ==

=== Setting the SNMP community ===

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

First edit the file /opt/librenms/config.php,
{{{
# vi /opt/librenms/config.php
}}}

and find the line:
{{{
$config['snmp']['community'] = array("public");
}}}

And change it to:
{{{
$config['snmp']['community'] = array("<class password>");
 }}}

=== Allowed Subnets ===

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 line:
{{{
#$config['nets'][] = "10.0.0.0/8";
}}}

And replace this with the following to scan our specific subnets in use by our network and the workshop infrastructure.
{{{
$config['nets'][] = "192.248.6.0/23";
}}}

=== Avoid Duplicate devices ===

We need to make one more change...

Tell LibreNMS not to add duplicate devices

To avoid making duplicate devices, add the following line at the bottom of the config.php file:
{{{
$config['allow_duplicate_sysName'] = false;
}}}

=== Discovery Method ===

By default system don't add devices by IP address, we look for a reverse dns name to be found and add with that. If this fails and you would like to still add devices automatically then you will need to set following.
{{{
$config['discovery_by_ip'] = true;
}}}

Finaly we have to define the discovery method. Here we will use ARP to discover devices. to do that add the following line
{{{
$config['discovery_modules']['discovery-arp'] = 1;
}}}

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

 
=== Add a host ===

Let's add localhost (i.e.: YOUR virtual server), using the following commands. you can do this from the Web interface:
{{{
# cd /opt/librenms
# php addhost.php localhost <class password> 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.

=== Final Configuration ===

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.

=== 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 ...
{{{
# editor /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.