sudo
to the shell commands (the ones that aren't at mysql>
prompts)
or temporarily invoke root privileges with sudo -s
.NOTE: These instructions are based on the official LibreNMS installation notes/) and have been tested on a fresh install of Ubuntu 14.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 and configure:
# apt-get install mysql-server mysql-client # mysql -uroot -p
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.
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 :)
The NMS is the host is where the web server and SNMP poller run.
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
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-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.
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/php5/apache2/php.ini
and /etc/php5/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. Valid
examples are: “America/New York”, “Australia/Brisbane”, “Etc/UTC”.
LibreNMS is installed using git. If you're not familiar with git, check
out the [git book][2] or the tips at [git ready][3]. 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
Normally the URL to clone would be https://github.com/librenms/librenms.git
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 www-data:www-data logs/ rrd/
Next, create /etc/apache2/sites-available/librenms.conf
containing the
following:
# 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 14.04, mcrypt
is not enabled on install. Run the following to
enable it:
# php5enmod mcrypt
Now enable the Virtual Host, and restart Apache
# a2ensite librenms # a2enmod rewrite # service apache2 restart
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.
To make the web installation easier, at this point you can give access
to the www-data
user to write to the /opt/librenms
directory so
LibreNMS can create the configuration file. Run the following command:
# chown www-data /opt/librenms
We'll change this back to root
, which is safer, once we are done.
At this stage you can launch the web installer by going to
http://librenmsN.ws.nsrc.org/install.php
Follow the onscreen instructions.
<CLASS_PASSWORD>
sysadm
, the class password, and your own E-mail address.
“The config file has been created”
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.
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)
We can now secure the /opt/librenms
directory again:
# chown root /opt/librenms
We're going to make a few changes to the configuration file:
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");
Still in the file /opt/librenms/config.php
, under the line:
$config['snmp']['community'] = array("NetManage");
… add the following:
$config['autodiscovery']['xdp'] = TRUE;
This tells LibreNMS to use CDP and LLDP to find and discover “neighbor” devices automatically.
We have one more change…
To be safe and not scan the Internet by mistake, LibreNMS needs to be tolds 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";
Save the file and exit - we're nearly done!
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
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.
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 # php discovery.php -h all && php poller.php -h all
Create the cronjob which will run periodic tasks required by LibreNMS:
# cd /opt/librenms # cp librenms.cron /etc/cron.d/librenms
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.
If you want to continue the setup manually then follow these instructions. DON'T follow these instructions if you've already done this via the Web install above!
# 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'] = "<CLASS_PASSWORD>"; $config['db_name'] = "librenms";
Initiate the follow 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 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;