Installing and Configuring LibreNMS (and SNMP on Windows Server)

Original Post Date: 2022-10-18

Updated: 2023-07-08

Before you start

This walkthrough is very similar to the excellent official LibreNMS documentation available here. The intention with this guide is to walk through the installation of LibreNMS on a fresh install of Ubuntu Server 22.04, running the NGINX web server stepping through the entire process and explaining some of the things that caught me out. Additionally, this will also cover how to install and set up SNMP on Windows servers so LibreNMS can monitor your Windows servers too.

Please note that like the official docs I will not be covering HTTPS setup, so your LibreNMS install will not be secure. Don’t expose it to the Internet unless you have configured HTTPS and taken appropriate web server hardening steps.

Installing Ubuntu Server 22.04

Installing Ubuntu Server 22.04 is pretty straight forward, however setting a static IP is different from Windows in that setup expects the subnet to be in CIDR format, for example: 192.168.0.0/24

For the user profile setup in the tutorial we’ll use the following information.

1
2
3
4


your name: LibreNMS
servers name: librenms-host
username: librenms
password: [your-password]

During the install you will be asked if you want to Install OpenSSH server. To allow much easier remote management you should enable this. It will make following this tutorial much easier as you will be able to copy and paste into the SSH window.

VM Quirks

Once the install procedure has completed it may look like it’s frozen. Just press enter and it will continue. Once the VM boots it may look like it’s frozen again and might not display a login prompt. Again just press enter and you will see a login prompt appear.

SSH is enabled, so from here on we’ll use that. In a cmd/PowerShell or Terminal prompt use the following commands to login:

1
2


ssh librenms@ServerIPaddress
[your-password]

We must become the root user to install the required packages:

1

sudo -i

Install Packages

Enter the following commands to install the pre-requisits LibreNMS requires:

1

apt install acl curl fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php-cli php-curl php-fpm php-gd php-gmp php-json php-mbstring php-mysql php-snmp php-xml php-zip rrdtool snmp snmpd whois unzip python3-pymysql python3-dotenv python3-redis python3-setuptools python3-systemd python3-pip

Add The LibreNMS User

This user should already exist if you’ve been following this walkthrough from the top.

Enter the command:

1

useradd librenms -d /opt/librenms -M -r -s "$(which bash)"

Download LibreNMS From GitHub

Run these commands to change directory to the /opt directory and then clone the librenms repository from GitHub:

1
2


cd /opt
git clone https://github.com/librenms/librenms.git

Setting Permissions

Now we’ll change the owner and file permissions on the downloaded files:

1
2
3
4


chown -R librenms:librenms /opt/librenms
chmod 771 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/

Install PHP Dependencies

With the next command we’ll switch user to the librenms user from the root user we’ve been using up to this point:

1

su - librenms

You will now be in the librenms user home directory, so we must change directory to the librenms directory in /opt that was cloned from GitHub:

1

cd /opt/librenms

Now we need to run the following script:

1
2


./scripts/composer_wrapper.php install --no-dev
exit

The exit will switch us back to the root user we were running as before. The reason for this switch to librenms and then back to root is that the script must run as the librenms user, but now we need the root priviledges again.

Set The Time Zone

Now we need to set the time zone in the PHP config and to do that we must edit some config files, we’ll use the “nano” text editor. See here for a list of supported time zones.
Some valid examples are: “America/New_York”, “Australia/Brisbane”, “Etc/UTC”, “Europe/London”.

1

nano /etc/php/8.1/fpm/php.ini

Scroll down to this section:

1
2
3
4


[Date]
; Defines the default timezone used by the date functions
; http://php.net/date.timezone
;date.timezone =

Change: ;date.timezone = to date.timezone = Europe/London using the time zone “Europe/London” as an example.

Save the file with CTRL + O and press enter to overwrite the existing file.
Exit with CTRL + X

Now run this command and edit the file the same way as above.

1

nano /etc/php/8.1/cli/php.ini

We now need to set the system time zone using the command below with “Europe/London” as an example:

1

timedatectl set-timezone Europe/London

Configure MariaDB

In this section you’ll see a lot of “mysql” commands even though we’re using MariaDB. In short MariaDB is a fork of MySQL - meaning it’s based off of MySQL. The commands are “mysql” probably for compatibility I would think.

Once again we’re going to be editing a config file using nano:

1

nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add the following inside the [mysqld] section:

1
2


innodb_file_per_table=1
lower_case_table_names=0

Save the file with CTRL + O and press enter to overwrite the existing file.
Exit with CTRL + X

Run these commands to enable MariaDB and start the service:

1
2


systemctl enable mariadb
systemctl restart mariadb

Now we’re going to login to MariaDB and create the database. The 'your-password' should be set to a secure password:

1
2
3
4
5
6


mysql -u root

CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'your-password';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
exit

Configure PHP-FPM

Next we’ll copy a template config file and edit it for librenms:

1
2


cp /etc/php/8.1/fpm/pool.d/www.conf /etc/php/8.1/fpm/pool.d/librenms.conf
nano /etc/php/8.1/fpm/pool.d/librenms.conf

Change [www] to [librenms]

Change “user and group” from:

1
2


user = www-data
group = www-data

to:

1
2


user = librenms
group = librenms

Change listen = to:

1

listen = /run/php-fpm-librenms.sock

Save the file with CTRL + O and press enter to overwrite the existing file.
Exit with CTRL + X

Configure NGINX Web Server

Here we’re going to create a new config file:

1

nano /etc/nginx/conf.d/librenms.conf

Copy and paste the text below remembering to change your-server-ipaddress to your servers IP address.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


server {
 listen      80;
 server_name your-server-ipaddress;
 root        /opt/librenms/html;
 index       index.php;

 charset utf-8;
 gzip on;
 gzip_types text/css application/javascript text/javascript application/x-javascript image/svg+xml text/plain text/xsd text/xsl text/xml image/x-icon;
 location / {
  try_files $uri $uri/ /index.php?$query_string;
 }
 location ~ [^/]\.php(/|$) {
  fastcgi_pass unix:/run/php-fpm-librenms.sock;
  fastcgi_split_path_info ^(.+\.php)(/.+)$;
  include fastcgi.conf;
 }
 location ~ /\.(?!well-known).* {
  deny all;
 }
}

Save the file with CTRL + O and press enter to overwrite the existing file.
Exit with CTRL + X

Next we’re going to delete the default site, and restart the web server and php services:

1
2
3


rm /etc/nginx/sites-enabled/default
systemctl restart nginx
systemctl restart php8.1-fpm

Enable lnms Command Completion

This feature grants you the opportunity to use tab for completion on lnms commands as you would for normal linux commands.

1
2


ln -s /opt/librenms/lnms /usr/bin/lnms
cp /opt/librenms/misc/lnms-completion.bash /etc/bash_completion.d/

Configure snmpd

Now we’re going to copy the example SNMP config file from the LibreNMS directory and edit it:

1
2


cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
nano /etc/snmp/snmpd.conf

You’ll need to change the following line to whatever you decide to use as your SNMP community string, by default most devices use “public”:

1

com2sec readonly  default         RANDOMSTRINGGOESHERE

It should look like this when you’re done:

1

com2sec readonly  default         public

Also it may be worth changing the following lines to the appropriate information:

1
2

syslocation Rack, Room, Building, City, Country [Lat, Lon]
syscontact Your Name <[email protected]>

When you’re done it should look similar to this:

1
2


syslocation [The loction information you want to appear in LibreNMS]
syscontact [The name and e-mail address you want to appear in LibreNMS]

Save the file with CTRL + O and press enter to overwrite the existing file.
Exit with CTRL + X

Finally, we can run the commands below (optionally) to make the LibreNMS host server appear as the specific linux device it is and not a generic one.

1
2
3
4


curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl enable snmpd
systemctl restart snmpd

Setting Up The Cron Job

Use this command to copy the cron job from the LibreNMS files to the system:

1

cp /opt/librenms/dist/librenms.cron /etc/cron.d/librenms

Enable The Scheduler

Run this command to copy the scheduler service from the LibreNMS files to the system, and then start the scheduler for librenms.

1
2
3


cp /opt/librenms/dist/librenms-scheduler.service /opt/librenms/dist/librenms-scheduler.timer /etc/systemd/system/
systemctl enable librenms-scheduler.timer
systemctl start librenms-scheduler.timer

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:

1

cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms

Final Setup

We need to do some final setup tasks. It’s time to go to a web browser: http://you-server-ip-address

Click on the blue circles to move the setup process along.
For “Configure Database”, fill in the password you set during the MariaDB setup section.
Click “Check Credentials”
Then click “Build Database”
Wait for it to complete.
When it’s done, the scrolling text will disappear and you should click on the next blue circle.
Now we’ll create an admin user - the e-mail can be left blank.
Click on the next blue circle.
Finish Install - Click on “Validate your install”

You will likely see some warnings - luckily in this new version of LibreNMS there’s an “automatically fix” button for database issues.

Once you’re run the fixes refresh the validate page http://ip-address/validate, and the database warnings should be gone.

Adding Your First Device

To add the first device:

Click on the LibreNMS logo to go to the home page.
Hover over Devices on the top bar, then click on Add device.
On the Add Device page, enter the IP of the LibreNMS server and the community string and then click on “Add Device”. If all goes well it should be added successfully.

Configure a Dashboard

The default dashboard is blank, here’s how to add some useful widgets to it.

Click on the edit icon.
In the drop down menu “Select Widget” select “Eventlog”.
The widgets can be resized as needed.
To save the dashboard changes, click on “Update”.
To hide the “Edit Dashboard Bar” hover over “Overview” then “Dashboard” then click on “Hide Dashboard Editor”.

Configure Alerts

There are many ways that LibreNMS can send alerts, but here I’m just going to focus on setting up e-mail alerts.

First we must create the default alert rules.

Hover over “Alerts” on the top bar.
Then click on “Alert Rules”.
Then click on the big green button to set up the default alert rules.

Now we must configure the alert transports.

Hover over “Alerts” on the top bar
Then click on “Alert Transports”.
Click on “Create alert transport” and name it “mail”.
Set “Transport type” to mail.
Set “Default alert” to ON.
Enter the e-mail address that the alerts should be send to.

Next we must configure a transport group.

Still on the Alert Transports page, click on the “Create transport group” button.
Enter the group name “mail group”.
Click on “Group Members” and the “mail” transport we created above will show.
Click on it again, then select “Save Transport Group”.

Finally, we must configure how the e-mails are going to be sent.

Hover over the cog icon in the top right hand corner and click on “Global Settings”.
Then click on the “Alerting” tab, and e-mail options.
Here you can enter the details for the SMTP server to use to sent the e-mails from. It supports Office 365, G-Suite and on-premise Microsoft Exchange servers.

Installing and Configuring SNMP on Windows Servers

Open an elevated PowerShell console and run the following command:

1

Install-WindowsFeature SNMP-Service

Once SNMP is installed, the community and permitted managers will need to be configured. There are a multitude of ways to do this but for a group of domian joined servers the best way is by using group policy.

Group Policy

Either create or edit an existing Group Policy Object and navigate to

Computer Configuration/Administrative Templates/Network/SNMP

To specify the community string, use the “Specify communities” policy.
Set it to “Enabled”.
Click the “Show” button in the options to set one or more community strings.
Use the “Specify permitted managers” policy to set which servers should have access to SNMP.
Set it to “Enabled”.
Click the “Show” button in the options and enter the IP address of the LibreNMS server.

Attach the GPO to the OU containing the servers you want to have SNMP configured and once group policy refreshes you should be able to add your Windows Servers as devices to monitor in the same way you did for the LibreNMS server.

Registry Edits

Navigate to or create the following path in regedit:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\SNMP\Parameters\ValidCommunities

Create a new “String Value” and name it “1” and then enter the name of the community string.

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\SNMP\Parameters\PermittedManagers

Create a new “String Value” and name it “1” and enter the IP address of the LibreNMS server.

Support My Work

If you would like to support me, please check out the link below.

PayPal

If you have any questions or comments, please leave them below.

-Mike