143 lines
5.0 KiB
Plaintext
143 lines
5.0 KiB
Plaintext
$OpenBSD: README,v 1.6 2015/12/27 23:28:40 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 can be heavy; beyond initial testing and
|
|
evaluation, it is probably happier 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
|
|
=======================
|
|
LibreNMS should be run on a dedicated vhost. 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 in bulk:
|
|
|
|
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 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.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 on servers will allow them
|
|
to be found.
|
|
|
|
Upstream documentation is present in ${INSTDIR}/doc and also online at
|
|
http://docs.librenms.org/.
|