Rebased

2026-07-28 00:24:21 +02:00 · 2016-01-04 12:09:32 +00:00
parent 32f5980523 9b4cfc3977
commit 0f33f6d1fa
316 changed files with 36603 additions and 11399 deletions
@@ -18,6 +18,9 @@ Table of Content:
    - [Pushover](#transports-pushover)
    - [Boxcar](#transports-boxcar)
    - [Pushbullet](#transports-pushbullet)
+    - [Clickatell](#transports-clickatell)
+    - [PlaySMS](#transports-playsms)
+    - [VictorOps](#transports-victorops)
 - [Entities](#entities)
    - [Devices](#entity-devices)
    - [BGP Peers](#entity-bgppeers)
@@ -30,6 +33,7 @@ Table of Content:
    - [Device](#macros-device)
    - [Port](#macros-port)
    - [Time](#macros-time)
+- [Additional Options](#extra)


 # <a name="about">About</a>
@@ -372,6 +376,54 @@ $config['alert']['transports']['pushbullet'] = 'MYFANCYACCESSTOKEN';
 ```
 ~~

+## <a name="transports-clickatell">Clickatell</a>
+
+Clickatell provides a REST-API requiring an Authorization-Token and at least one Cellphone number.  
+Please consult Clickatell's documentation regarding number formating.  
+Here an example using 3 numbers, any amount of numbers is supported:
+
+~~
+```php
+$config['alert']['transports']['clickatell']['token'] = 'MYFANCYACCESSTOKEN';
+$config['alert']['transports']['clickatell']['to'][]  = '+1234567890';
+$config['alert']['transports']['clickatell']['to'][]  = '+1234567891';
+$config['alert']['transports']['clickatell']['to'][]  = '+1234567892';
+```
+~~
+
+## <a name="transports-playsms">PlaySMS</a>
+
+PlaySMS is an OpenSource SMS-Gateway that can be used via their HTTP-API using a Username and WebService-Token.  
+Please consult PlaySMS's documentation regarding number formating.  
+Here an example using 3 numbers, any amount of numbers is supported:
+
+~~
+```php
+$config['alert']['transports']['playsms']['url']   = 'https://localhost/index.php?app=ws';
+$config['alert']['transports']['playsms']['user']  = 'user1';
+$config['alert']['transports']['playsms']['token'] = 'MYFANCYACCESSTOKEN';
+$config['alert']['transports']['playsms']['from']  = '+1234567892'; //Optional
+$config['alert']['transports']['playsms']['to'][]  = '+1234567890';
+$config['alert']['transports']['playsms']['to'][]  = '+1234567891';
+```
+~~
+
+## <a name="transports-victorops">VictorOps</a>
+
+VictorOps provide a webHook url to make integration extremely simple. To get the URL required login to your VictorOps account and go to:
+
+Settings -> Integrations -> REST Endpoint -> Enable Integration.
+
+The URL provided will have $routing_key at the end, you need to change this to something that is unique to the system sending the alerts such as librenms. I.e:
+
+`https://alert.victorops.com/integrations/generic/20132414/alert/2f974ce1-08fc-4dg8-a4f4-9aee6cf35c98/librenms`
+
+~~
+```php
+$config['alert']['transports']['victorops']['url'] = 'https://alert.victorops.com/integrations/generic/20132414/alert/2f974ce1-08fc-4dg8-a4f4-9aee6cf35c98/librenms';
+```
+~~
+
 # <a name="entities">Entities

 Entities as described earlier are based on the table and column names within the database, if you are unsure of what the entity is you want then have a browse around inside MySQL using `show tables` and `desc <tablename>`.
@@ -582,4 +634,14 @@ Description: Packet loss % value for the device within the last 15 minutes.

 Example: `%macros.packet_loss_15m` > 50

+# <a name="extra">Additional Options</a>

+Here are some of the other options available when adding an alerting rule:
+
+- Rule name: The name associated with the rule.
+- Severity: How "important" the rule is.
+- Max alerts: The maximum number of alerts sent for the event.  `-1` means unlimited.
+- Delay: The amount of time to wait after a rule is matched before sending an alert.
+- Interval: The interval of time between alerts for an event until Max is reached.
+- Mute alerts: Disable sending alerts for this rule.
+- Invert match: Invert the matching rule (ie. alert on items that _don't_ match the rule).
@@ -9,7 +9,11 @@ Here we will provide configuration details for these modules.

 - LDAP: ldap

- HTTP Auth: http-auth
+- Active Directory: active_directory
+
+- HTTP Auth: http-auth
+
+- Radius: radius

 #### User levels

@@ -99,3 +103,43 @@ $config['auth_ldap_groupmemberattr'] = "memberUid";
 ```

 Replace {id} with the unique ID provided by Jumpcloud.
+
+#### Active Directory Authentication
+
+Config option: `active_directory`
+
+This is similar to LDAP Authentication. Install __php_ldap__ for CentOS/RHEL or __php5-ldap__ for Debian/Ubuntu.
+
+If you have issues with secure LDAP try setting `$config['auth_ad_check_certificates']` to `0`.
+
+##### Require actual membership of the configured groups
+
+If you set ```$config['auth_ad_require_groupmembership']``` to 1, the authenticated user has to be a member of the specific group. Otherwise all users can authenticate, but are limited to user level 0 and only have access to shared dashboards. 
+
+##### Sample configuration
+
+```
+$config['auth_ad_url'] = "ldaps://your-domain.controll.er";
+$config['auth_ad_check_certificates'] = 1; // or 0
+$config['auth_ad_domain'] = "your-domain.com";
+$config['auth_ad_base_dn'] = "dc=your-domain,dc=com";
+$config['auth_ad_groups']['admin']['level'] = 10;
+$config['auth_ad_groups']['pfy']['level'] = 7;
+$config['auth_ad_require_groupmembership'] = 0;
+```
+
+#### Radius Authentication
+
+Please note that a mysql user is created for each user the logs in successfully. User level 1 is assigned to those accounts so you will then need to assign the relevant permissions unless you set `$config['radius']['userlevel']` to be something other than 1.
+
+> Cleanup of old accounts is done using the authlog. You will need to set the cleanup date for when old accounts will be purged which will happen AUTOMATICALLY.
+> Please ensure that you set the $config['authlog_purge'] value to be greater than $config['radius']['users_purge'] otherwise old users won't be removed.
+
+```php
+$config['radius']['hostname']   = 'localhost';
+$config['radius']['port']       = '1812';
+$config['radius']['secret']     = 'testing123';
+$config['radius']['timeout']    = 3;
+$config['radius']['users_purge'] = 14;//Purge users who haven't logged in for 14 days.
+$config['radius']['default_level'] = 1;//Set the default user level when automatically creating a user. 
+```
@@ -14,3 +14,5 @@ By default values are kept for 4 Minutes inside the memcached, you can adjust th
 It's strongly discouraged to set this above `300` (5 Minutes) to avoid interferences with the polling, discovery and alerting processes.

 If you use the Distributed Poller, you can point this to the same memcached instance. However a local memcached will perform better in any case.
+
+By default `memcached` on many distributions starts itself with 64 MB of memory for it to store data in. If you have lots of devices or look at graphs frequently, it might be worth it to expand `memcached`'s footprint a bit. Generally this can be done in `/etc/memcached.conf`, replacing `-m 64` with `-m 512`, or however many megs of memory you want to allocate for `memcached`. Then restart the `memcached` service.
@@ -40,3 +40,10 @@ You will need to configure default credentials for your devices, LibreNMS doesn'
 ```

 If you have devices which you do not wish to appear in Oxidized then you can edit those devices in Device -> Edit -> Misc and enable "Exclude from Oxidized?"
+
+It's also possible to exclude certain device types and OS' from being output via the API. This is currently only possible via config.php:
+
+```php
+$config['oxidized']['ignore_types'] = array('server');
+$config['oxidized']['ignore_os'] = array('linux');
+```
@@ -1,6 +1,5 @@
 # Proxmox graphing
-
-It is possible to create graphs of the Proxmox VMs that run on your monitored machines. Currently, only trafficgraphs are created. One for each interface on each VM. Possibly, IO grahps will be added later on.
+It is possible to create graphs of the Proxmox **VMs** that run on your monitored machines. Currently, only trafficgraphs are created. One for each interface on each VM. Possibly, IO grahps will be added later on.

 The ultimate goal is to be able to create traffic bills for VMs, no matter on which physical machine that VM runs.

@@ -10,14 +9,20 @@ To enable Proxmox graphs, do the following:

 In config.php, enable Proxmox:
 ```php
-$config['enable_proxmox'] = 1
+$config['enable_proxmox'] = 1;
 ```

-Then, install librenms-agent on the machines running Proxmox, and enable the Proxmox-plugin using:
+Then, install [librenms-agent](http://docs.librenms.org/Extensions/Agent-Setup/) on the machines running Proxmox and enable the Proxmox-script using:
+
 ```bash
-mk_enplug proxmox
+cp /opt/librenms-agent/proxmox /usr/lib/check_mk_agent/local/proxmox
+chmod +x /usr/lib/check_mk_agent/local/proxmox
 ```

-Then, enable the unix-agent on the machines running Proxmox.
+Then, restart the xinetd service
+```bash
+/etc/init.d/xinetd restart
+```

+Then in LibreNMS active the librenms-agent and proxmox application flag for the device you are monitoring.
 You should now see an application in LibreNMS, as well as a new menu-item in the topmenu, allowing you to choose which cluster you want to look at.
@@ -0,0 +1,21 @@
+# RRDTune?
+
+When we create rrd files for ports, we currently do so with a max value of 12500000000 (100G). Because of this if a device sends us bad data back then it can appear as though 
+a 100M port is doing 40G+ which is impossible. To counter this you can enable the rrdtool tune option which will fix the max value to the interfaces physical speed (minimum of 10M).
+
+To enable this you can do so in three ways!
+
+ - Globally under Global Settings -> External Settings -> RRDTool Setup
+ - For the actual device, Edit Device -> Misc
+ - For each port, Edit Device -> Port Settings
+
+Now when a port interface speed changes (this can happen because of a physical change or just because the device has mis-reported) the max value is set. If you don't want to wait until 
+a port speed changes then you can run the included script:
+
+script/tune_port.php -h <hostname> -p <ifName>
+
+Wildcards are supported using *, i.e:
+
+script/tune_port.php -h local* -p eth*
+
+This script will then perform the rrdtool tune on each port found using the provided ifSpeed for that port.
@@ -3,7 +3,7 @@
 Services within LibreNMS provides the ability to use Nagios plugins to perform additional monitoring outside of SNMP.

 These services are tied into an existing device so you need at least one device that supports SNMP to be able to add it 
-to LibreNMS - localhot is a good one.
+to LibreNMS - localhost is a good one.

 ## Setup

@@ -43,3 +43,129 @@ $config['own_hostname']
 ```

 You should now see a new tab in your device page called ping.
+
+
+
+
+### Install and integrate Smokeping [Debian/Ubuntu] ###
+
+> This guide assumes you have already <a href="http://docs.librenms.org/Installation/Installation-(Debian-Ubuntu)/">installed librenms</a>, and you installed apache2 in the process. Tested with Ubuntu 14.04 and Apache 2.4.
+
+Nearly everything we do will require root, and at one point we'll encounter a problem if we just use sudo, so we'll just switch to root at the beginning...
+
+```bash
+sudo su -
+```
+
+### Install Smokeping ###
+
+```bash
+apt-get install smokeping
+```
+
+At the end of installation, you may have gotten this error: `ERROR: /etc/smokeping/config.d/pathnames, line 1: File '/usr/sbin/sendmail' does not exist`
+
+If so, just edit smokeping's pathnames.
+
+```bash
+nano /etc/smokeping/config.d/pathnames
+```
+
+Comment out the first line:
+
+```bash
+#sendmail = /usr/sbin/sendmail
+```
+
+Exit and save.
+
+Check if the smokeping config file was created for apache2:
+
+```bash
+ls /etc/apache2/conf-available/
+```
+
+If you don't see `smokeping.conf` listed, you'll need to create a symlink for it:
+
+```bash
+ln -s /etc/smokeping/apache2.conf /etc/apache2/conf-available/smokeping.conf
+```
+
+Edit the smokeping config so smokeping knows the hostname it's running on:
+
+```bash
+nano /etc/smokeping/config.d/General
+```
+
+Change the `cgiurl` value to `http://yourhost/cgi-bin/smokeping.cgi`
+Modify any other values you wish, then exit and save.
+
+### LibreNMS integration ###
+
+So far this is a relatively normal Smokeping installation; next we'll set up the LibreNMS integration.
+
+Generate the configuration file so Smokeping knows the hosts you have set up for monitoring in LibreNMS.
+
+```bash
+cd /opt/librenms/scripts/
+(echo "+ LibreNMS"; php ./gen_smokeping.php) > /etc/smokeping/config.d/librenms.conf
+```
+
+Add a cron job so as you add or remove hosts in librenms they'll get updated with Smokeping.
+
+```bash
+crontab -e
+```
+
+Add the example cron below; it's set to run daily at 02:05
+
+```bash
+05 02 * * * root cd /opt/librenms/scripts && (echo "+ LibreNMS"; php ./gen_smokeping.php) > /etc/smokeping/config.d/librenms.conf && service smokeping reload >> /dev/null
+```
+
+Exit and save.
+
+Include `librenms.conf` in smokeping's config:
+```bash
+nano /etc/smokeping/config
+```
+
+Add the following line at the end:
+
+```bash
+@include /etc/smokeping/config.d/librenms.conf
+```
+
+Exit and save.
+
+### Configure LibreNMS ###
+
+```bash
+nano /opt/librenms/config.php
+```
+
+Scroll to the bottom, and paste in the following:
+
+```bash
+$config['smokeping']['dir'] = '/var/lib/smokeping';
+$config['smokeping']['integration'] = true;
+```
+
+Exit and save.
+
+Run the following commands:
+```bash
+a2enconf smokeping
+a2enmod cgid
+service apache2 restart
+service smokeping restart
+```
+
+Return to your normal user shell
+
+```bash
+exit
+```
+
+Done! You should be able to load the Smokeping web interface at `http://yourhost/cgi-bin/smokeping.cgi`
+In LibreNMS, a Ping tab should also appear.