librenms-26.9.1.1p0v0

This README contains unresolved ports variables; replace them before using its commands.

+-----------------------------------------------------------------------
| Running librenms 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
-------------------------------------
<VirtualHost *:80>
  DocumentRoot	${INSTDIR}/html/
  ServerName	librenms.example.com
  CustomLog	${INSTDIR}/logs/access_log combined
  ErrorLog	${INSTDIR}/logs/error_log
  AllowEncodedSlashes NoDecode
  <Directory "${INSTDIR}/html/">
    Require all granted    # for Apache 2.3 or newer
    AllowOverride All
    Options FollowSymLinks MultiViews
  </Directory>
</VirtualHost>

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).

SNMP trap handling
==================
LibreNMS can receive notifications from Net-SNMP's snmptrapd and use these
for alerts, updating port status, etc. Example configuration, showing use
of doas to run LibreNMS' acceptor script as the correct user, and to load
various MIBs so that OIDs are converted to textual strings (note that the
directories specified are not parsed recursively, so you will need to add
those for particular vendors you're interested in).

# cat ${SYSCONFDIR}/snmp/snmptrapd.conf
doNotRetainNotificationLogs yes
authCommunity log,execute public
traphandle default /usr/bin/doas -u _librenms /var/www/librenms/snmptrap.php

# grep netsnmp /etc/doas.conf 
permit keepenv nopass _netsnmp as _librenms cmd /var/www/librenms/snmptrap.php

# grep -A3 netsnmp /etc/login.conf
netsnmptrapd:\
	:setenv=MIBDIRS=+/usr/local/share/snmp/mibs\c/var/www/librenms/mibs\c/var/www/librenms/mibs/hp\c/var/www/librenms/mibs/dell\c/var/www/librenms/mibs/cisco,MIBS=+ALL:\
	:tc=daemon:

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 <username>
doas -u _librenms lnms user:add --role=user <username>
doas -u _librenms lnms device:add --v2c --community=<comm> <hostname>
doas -u _librenms lnms device:add --v3 -u <user> -a AES -x SHA \
    -A <authpass> -X <privpass> <hostname>
doas -u _librenms lnms poller:discovery <devicename>
doas -u _librenms lnms device:poll <devicename>