LibreNMS Image documentation

Introduction

This documentation is related to 'LibreNMS Image', created by Puppeteers Oy. LibreNMS Image is an open source, pre-built Cloud virtual machine image that runs LibreNMS, "a fully featured network monitoring system that provides a wealth of features and device support". LibreNMS Image contains Apache, PHP, MySQL, LibreNMS, snmpd and large number of other software. Currently it's available for Azure Marketplace and AWS Marketplace. See LibreNMS Image product page for more information on the features.

Security Group setup

The default security groups allow traffic to LibreNMS (tcp/443) from any IPv4 address. SSH access is allowed from anywhere.

Security recommendations

In production setups it is recommended to allow access only from RFC1918 private networks. If you don't have a VPN (e.g. OpenVPN, OpenVPN Access Server or Wireguard) configured and must access a production LibreNMS admin interface directly from the Internet, it is recommended for security reasons to limit access using IP whitelisting in Security Groups.

Logging in to the instance using SSH

Our images are built on top of official Cloud images of various operating system vendors. In AWS login as the "ubuntu" user. In Azure you'd typically log in as "azureuser". You can login using the instance's public IP address.

Note that automated system package upgrade may kick in immediately after you launch the instance. This may manifest itself as slowness in the LibreNMS web interface which should not last very long.

Getting the passwords

LibreNMS Image resets all passwords (MySQL and LibreNMS) to random values on the first boot. The passwords are stored in librenms-passwords.txt under /home/ubuntu (AWS) or /home/azureuser (Azure). It is recommended for security reasons to copy those passwords in a secure password vault (e.g. Keepass) and remove that file.

Logging in to LibreNMS Admin UI

LibreNMS Admin UI can be accessed with a web browser at its public IP address, for example https://150.51.4.123. You can find the public IP address of your LibreNMS instance easily:

  • AWS console -> EC2 -> Instances
  • Azure portal -> Virtual Machines -> <name-of-vm> -> Public IP address

By default LibreNMS uses a self-signed certificate so you will get a certificate warning when you access its web UI the first time. Ignore the warning and login as "admin" using the admin password (see above).

Setting the hostname

On production installations it is recommended to change the hostname of the instance to something reasonable. On Ubuntu you can do that like this:

$ sudo -i
$ hostnamectl set-hostname librenms.example.org

SSL/TLS certificate setup

By default LibreNMS Image uses snakeoil certificates that are generated when the Cloud instance is launched. It is strongly recommended to switch to commercial certificates or Letsencrypt certificates. If you wish to use Letsencrypt and your LibreNMS is not publicly accessible (recommended) we suggest using a Letsencrypt wildcard certificate (e.g. *.example.vpn) that can be obtained with the DNS-01 challenge.

Please follow the instructions of the certificate provider on how to configure Apache to use your own certificates.

Updating LibreNMS

By default LibreNMS updates have been disabled in LibreNMS Image. This is necessary to allow us to produce a product that is guaranteed to work. LibreNMS codebase evolves very rapidly and its dependencies change often, so the default LibreNMS "update the installation daily" strategy would break the product very quickly.

To manage LibreNMS updates you have several options:

  • Enable automatic updates (see below)
  • Update manually
  • Update to newer version of LibreNMS Image

We recommend turning on automatic updates as described in the official documentation. However, if you do that, you should be prepared to fix any issues that will inevitably arise.

Enabling automatic updates takes two steps:

$ sudo -u librenms -i bash
$ cd ~
$ git checkout master

Then enable updates in /opt/librenms/librenms-extra-config.php:

$config['update'] = 1;

Contact and support

If you require more information than given in this LibreNMS Image documentation or have any issues using LibreNMS on a freshly created cloud instance please contact our product support at [email protected]. We will respond on a best effort basis.

We do not provide support for running or configuring LibreNMS for your particular use-case. If you need help, we recommend reaching out to the official community support channels.

menucross-circle