$OpenBSD: README,v 1.10 2018/06/28 18:42:57 sthen Exp $
+-----------------------------------------------------------------------
| Running ${FULLPKGNAME} on OpenBSD
+-----------------------------------------------------------------------
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 probably best 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.
On the database server, create a database and user account for LibreNMS:
CREATE DATABASE librenms;
GRANT ALL PRIVILEGES ON librenms.*
TO 'librenms'@'<ip>'
IDENTIFIED BY '<password>';
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. This can either be done from the CLI, or by using the web-based
installer which carries out additional checks. Choose *one* of the following:
Option 1: CLI
-------------
cd ${INSTDIR}
$EDITOR config.php # set database username/password etc.
su -s ${MODPHP_BIN} www ./build-base.php
su -s ${MODPHP_BIN} www ./adduser.php <name> <pass> 10 # 10=admin priv
su -s ${MODPHP_BIN} www ./addhost.php localhost public v2c
su -s ${MODPHP_BIN} www ./discovery.php -h all
su -s ${MODPHP_BIN} www ./poller.php -h all
Option 2: Web-based
-------------------
In order to use the web-based installer, you must first remove the default
configuration file:
rm ${INSTDIR}/config.php
chown www ${INSTDIR} # allow the installer to write config.php
xdg-open http://localhost/install.php
chown root ${INSTDIR} # protect again
Periodic tasks
==============
Cron jobs are used to discover and poll hosts, send alerts, and carry out
other housekeeping. Samples are provided in ${INSTDIR}/librenms.nonroot.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 present in ${INSTDIR}/doc and also online at
http://docs.librenms.org/.
Updating from 1.39 or earlier
=============================
As of 1.40, LibreNMS now uses the Laravel framework which requires some
additional setup. Upstream has code to copy this across from an existing
configuration initially, but it's not functional in this packaged
environment. Until this is done you will see a page with a red block
with white "Whoops, looks like something went wrong" text.
Generate an APP_KEY:
# cd /var/www/librenms
# doas -u _librenms ${MODPHP_BIN} artisan key:generate
Copy this to the clipboard, then edit ${INSTDIR}/.env and fill in the
relevant details.
Make sure that you have the required PHP modules enabled via symlinks in
${SYSCONFDIR}/php-${MODPHP_VERSION}.sample as described in "Webserver
configuration" above. In particular, pdo_mysql is now required.
It may also be necessary to raise max_connections in ${SYSCONFDIR}/my.cnf;
see https://community.librenms.org/t/new-requirements-for-1-40/4057
e8932541e7