mirror of
https://github.com/openbsd/ports.git
synced 2026-06-18 07:24:23 +02:00
sthen
198 lines
6.7 KiB
Plaintext
198 lines
6.7 KiB
Plaintext
+-----------------------------------------------------------------------
|
|
| 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
|
|
-------------------------------------
|
|
<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>
|