187 lines
6.4 KiB
Plaintext
187 lines
6.4 KiB
Plaintext
$OpenBSD: README,v 1.11 2018/09/04 12:46:17 espie Exp $
|
|
|
|
+-----------------------------------------------------------------------
|
|
| Running ${PKGSTEM} 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
|