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 Nginx, PHP, MariaDB, 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.

Setting admin credentials for LibreNMS

When you go to https:// the first time, you will see a certificate warning. You should ignore the warning and add an exception to your browser; LibreNMS generates self-signed certificates on first boot.

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 -> -> Public IP address

The first time you visit the URL you will get a certificate warning. This is normal: LibreNMS uses self-signed snakeoil certificates created on the first boot of the VM. You have to ignore the warning and save an exception in your browser.

Now you should see the LibreNMS installation wizard. From there you need to create a LibreNMS admin user and configure some basic settings. Once you’ve finished with the installation wizard click on “Dashboard”. Alternatively you can point your browser back to https://. Use your admin credentials to log in to LibreNMS and start using it.

Note on LibreNMS database password

On first boot a systemd service resets the librenms database user’s password to a random value. The password is stored in librenms-passwords.txt under /home/ubuntu (AWS) or /home/azureuser (Azure). It is recommended for security reasons to copy the password to a secure password vault (e.g. Keepass) and remove that file. That said, the database password is also available in /opt/librenms/.env, so that LibreNMS knows what database credentials to use.

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.

LibreNMS base_url

LibreNMS generates some URLs based on the value of base_url configuration option. If base_url is set incorrectly, much of LibreNMS seems to work fine, but many links, in particular some graph links, will be completely broken. In a stable production setup which has a static IP, DNS A records, SSL certificates and all that this is not a problem. It is a problem for LibreNMS image as the instances created for testing might not have static public IPs. LibreNMS developers don’t consider this as a bug, so it is unlikely to get fixed anytime soon.

To work around this feature/bug LibreNMS image includes cloud-init script that runs on every boot and updates LibreNMS base_url to match the current public IP of the VM (e.g. https://150.51.4.123). The script attempts to leave base_url alone when it is not needed.

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.

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 info@puppeteers.net. We will respond on a best effort basis.

We do not provide support for running or configuring LibreNMS for your particular use-case, unless you have a support plan (only available in Azure). If you need help, we recommend reaching out to the official community support channels.