librenms-24.10.1v0 – auto-discovering network management/monitoring system (cvsweb github mirror)

Description

LibreNMS is an autodiscovering PHP/MySQL/SNMP based network monitoring
which includes support for a wide range of network hardware and
operating systems including Cisco, Linux, FreeBSD, Juniper, Brocade,
Foundry, HP and many more. LibreNMS is a community-based fork of
Observium.

LibreNMS is not intended to replace a Nagios-type up/down monitoring
system, but rather to complement it with an easy to manage, intuitive
representation of historical and current performance statistics,
configuration visualisation and syslog capture.

WWW: https://www.librenms.org/

Readme

+-----------------------------------------------------------------------
| Running ${PKGSTEM} on OpenBSD
+-----------------------------------------------------------------------

Standard upgrades
=================
Run daily.sh manually (doas -u _librenms /var/www/librenms/daily.sh)
after upgrading to process database schema changes.


Introduction
============
LibreNMS is primarily PHP-based, however it relies on running a number of
other programs during normal operation. As such it is not suitable for
running in the typical chroot jail used by default on OpenBSD (a chrooted
web server process is OK, provided that PHP is run separately, e.g. via
FastCGI, and PHP itself is not chrooted).

System loads during SNMP polling and graph generation can be heavy;
if monitoring more than a handful of systems beyond initial testing and
evaluation it is recommended to run on a dedicated system.

Database configuration
======================
If the database will be running on the same host as LibreNMS, install
mariadb-server and follow MariaDB's pkg-readmes documentation to create
and secure an initial database. It is recommended that you set
"innodb_file_per_table=1" in the [mysqld] section of my.cnf before
creating the database.

On the database server, create a database and user account for LibreNMS:

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

Webserver configuration
=======================
Run LibreNMS on a dedicated virtual host. Sample configuration sections
for NGINX and Apache httpd 2.x are shown below.

If using php-fpm, disable any "chroot" line from ${SYSCONFDIR}/php-fpm.conf,
or add a new pool for LibreNMS which does not use chroot.

If using Apache mod_php, avoid using chroot.

If you wish to use memcache, install the pecl-memcached package.

Ensure that symbolic links have been created to enable the required
PHP modules; to do this for all installed modules:

  cd ${SYSCONFDIR}/php-${MODPHP_VERSION}.sample
  for i in *; do ln -fs ../php-${MODPHP_VERSION}.sample/$i ../php-${MODPHP_VERSION}/; done

Reload your web server and/or php_fpm so that changes take effect.

Sample php-fpm configuration
----------------------------
[librenms]
user = _librenms
group = _librenms
listen = /var/www/run/php-fpm-lnms.sock
listen.owner = www
listen.group = www
listen.mode = 0660
pm = dynamic
pm.max_children = 20
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

Sample NGINX configuration
--------------------------
server {
  listen	80;
  server_name	librenms.example.com;
  root		${INSTDIR}/html;
  index		index.php;
  location / {
    try_files	$uri $uri/ @librenms;
  }
  location ~ \.php {
    fastcgi_pass	unix:run/php-fpm-lnms.sock;
    fastcgi_index	index.php;
    fastcgi_param	DOCUMENT_ROOT /var/www$document_root;
    fastcgi_param	SCRIPT_FILENAME /var/www$document_root$fastcgi_script_name;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    include		fastcgi_params;
  }
  location ~ ^\.ht {
    deny	all;
  }
  location @librenms {
    rewrite	^api/v0(.*)$ /api_v0.php/$1 last;
    rewrite	^(.+)$ /index.php/$1 last;
  }
}

Sample Apache httpd 2.x configuration
-------------------------------------

  DocumentRoot	${INSTDIR}/html/
  ServerName	librenms.example.com
  CustomLog	${INSTDIR}/logs/access_log combined
  ErrorLog	${INSTDIR}/logs/error_log
  AllowEncodedSlashes NoDecode
  
    Require all granted    # for Apache 2.3 or newer
    AllowOverride All
    Options FollowSymLinks MultiViews
  


Initial LibreNMS configuration
==============================
After creating the database user account and configuring the web server,
it is time to install the database schema and make an initial configuration
of LibreNMS.

Set database access details in the .env file:

# cd /var/www/librenms
# vi .env

and generate an APP_KEY:

# chown _librenms .env
# doas -u _librenms php artisan key:generate
# chown root .env

Remove the default configuration file:

rm ${INSTDIR}/config.php

Then open /install in a web browser (e.g. http://localhost/install).

Periodic tasks
==============
Cron jobs are used to discover and poll hosts, send alerts, and carry out
other housekeeping. Samples are provided in ${INSTDIR}/dist/librenms.cron
and should be added to /etc/crontab (creating the file if necessary).
The parameter to poller-wrapper.py sets the number of threads running
SNMP queries in parallel; you may need to adjust this e.g. if you fetch
results from many hosts and the queries do not finish in time, or if
the machine is getting overloaded.

Further configuration
=====================
See ${INSTDIR}/includes/defaults.php for additional lines that can
be added to ${INSTDIR}/config.php.

LibreNMS is capable of auto-discovery based on CDP/LLDP information from
supported devices (this is possible with many switches); if you have such
a switch and plan to use LibreNMS to monitor servers, running an LLDP agent
(such as ladvd or lldpd) as well as snmpd on servers will allow them
to be found.

Rotate LibreNMS' logs in newsyslog.conf, e.g.:

/var/www/librenms/logs/librenms.log     644  7     250  *     Z
/var/www/librenms/logs/daily.log        644  7     250  *     Z

Upstream documentation is at http://docs.librenms.org/.

Cheat sheet for one-off CLI commands
====================================
doas -u _librenms lnms user:add --role=admin 
doas -u _librenms lnms user:add --role=user 
doas -u _librenms lnms device:add --v2c --community= 
doas -u _librenms lnms device:add --v3 -u  -a AES -x SHA \
    -A  -X  
doas -u _librenms lnms poller:discovery 
doas -u _librenms lnms device:poll 

Maintainer

Stuart Henderson

Categories

lang/php lang/python net www

Build dependencies

Run dependencies

Files