LibreNMS includes a highly customizable alerting system.
The system requires a set of user-defined rules to evaluate the situation of each device, port, service or any other entity.
This document only covers the usage of it. See the [DEVELOPMENT.md](https://github.com/f0o/glowing-tyrion/blob/master/DEVELOPMENT.md) for code-documentation.
# <a name="rules">Rules</a>
Rules are defined using a logical language.
The GUI provides a simple way of creating basic as well as complex Rules in a self-describing manner.
More complex rules can be written manually.
## <a name="rules-syntax">Syntax</a>
Rules must consist of at least 3 elements: An __Entity__, a __Condition__ and a __Value__.
Rules can contain braces and __Glues__.
__Entities__ are provided as `%`-Noted pair of Table and Field. For Example: `%ports.ifOperStatus`.
__Conditions__ can be any of:
- Equals `=`
- Not Equals `!=`
- Matches `~`
- Not Matches `!~`
- Greater `>`
- Greater or Equal `>=`
- Smaller `<`
- Smaller or Equal `<=`
__Values__ can be Entities or any single-quoted data.
__Glues__ can be either `&&` for `AND` or `||` for `OR`.
__Note__: The difference between `Equals` and `Matches` (and it's negation) is that `Equals` does a strict comparison and `Matches` allows the usage of the placeholder `@`. The placeholder `@` is comparable with `.*` in RegExp.
- Faults, Only available on alert (`%state != 0`), must be iterated in a foreach (`{foreach %faults}`). Holds all available information about the Fault, accessable in the format `%value.Column`, for example: `%value.ifDescr`. Special field `%value.string` has most Identification-information (IDs, Names, Descrs) as single string, this is the equivalent of the default used.
Alert sent to: {foreach %contacts}%value <%key> {/foreach}
```
# <a name="transports">Transports</a>
Transports are located within `$config['install_dir']/includes/alerts/transports.*.php` and defined as well as configured via `$config['alert']['transports']['Example'] = 'Some Options'`.
Contacts will be gathered automatically and passed to the configured transports.
The contacts will always include the `SysContact` defined in the Device's SNMP configuration and also every LibreNMS-User that has at least `read`-permissions on the entity that is to be alerted.
At the moment LibreNMS only supports Port or Device permissions.
To include users that have `Global-Read` or `Administrator` permissions it is required to add these additions to the `config.php` respectively:
```php
$config['alert']['globals'] = true; //Include Global-Read into alert-contacts
$config['alert']['admins'] = true; //Include Adminstrators into alert-contacts
```
## <a name="transports-email">E-Mail</a>
E-Mail transport is enabled with adding the following to your `config.php`:
```php
$config['alert']['transports']['mail'] = true;
```
The E-Mail transports uses the same email-configuration like the rest of LibreNMS.
As a small reminder, here is it's configuration directives including defaults:
API transports definitions are a bit more complex than the E-Mail configuration.
The basis for configuration is `$config['alert']['transports']['api'][METHOD]` where `METHOD` can be `get`,`post` or `put`.
This basis has to contain an array with URLs of each API to call.
The URL can have the same placeholders as defined in the [Template-Syntax](#templates-syntax).
If the `METHOD` is `get`, all placeholders will be URL-Encoded.
The API transport uses cURL to call the APIs, therefore you might need to install `php5-curl` or similar in order to make it work.
__Note__: it is highly recommended to define own [Templates](#templates) when you want to use the API transport. The default template might exceed URL-length for GET requests and therefore cause all sorts of errors.
The Slack transport will POST the alert message to your Slack Incoming WebHook, you are able to specify multiple webhooks along with the relevant options to go with it. All options are optional, the only required value is for url, without this then no call to Slack will be made. Below is an example of how to send alerts to two channels with different customised options:
Entities as described earlier are based on the table and column names within the database, if you are ensure of what the entity is you want then have a browse around inside MySQL using `show tables` and `desc <tablename>`.
## <a name="entity-devices">Devices</a>
__devices.hostname__ = The devices hostname.
__devices.location__ = The devices location.
__devices.status__ = The status of the device, 1 = up, 0 = down.
__devices.ignore__ = If the device is ignored this will be set to 1.
__devices.disabled__ = If the device is disabled this will be set to 1.
__devices.last_polled__ = The the last polled datetime (yyyy-mm-dd hh:mm:ss).
__devices.type__ = The device type such as network, server, firewall, etc.
## <a name="entity-bgppeers">BGP Peers</a>
__bgpPeers.astext__ = This is the description of the BGP Peer.
__bgpPeers.bgpPeerIdentifier__ = The IP address of the BGP Peer.
__bgpPeers.bgpPeerRemoteAs__ = The AS number of the BGP Peer.
__bgpPeers.bgpPeerState__ = The operational state of the BGP session.
__bgpPeers.bgpPeerAdminStatus__ = The administrative state of the BGP session.
__bgpPeers.bgpLocalAddr__ = The local address of the BGP session.
## <a name="entity-ipsec">IPSec Tunnels</a>
__ipsec_tunnels.peer_addr__ = The remote VPN peer address.
__ipsec_tunnels.local_addr__ = The local VPN address.
__ipsec_tunnels.tunnel_status__ = The VPN tunnels operational status.
## <a name="entity-mempools">Memory pools</a>
__mempools.mempool_type__ = The memory pool type such as hrstorage, cmp and cemp.
__mempools.mempool_descr__ = The description of the pool such as Physical memory, Virtual memory and System memory.
__mempools.mempool_perc__ = The used percentage of the memory pool.
## <a name="entity-ports">Ports</a>
__ports.ifDescr__ = The interface description.
__ports.ifName__ = The interface name.
__ports.ifSpeed__ = The port speed in bps.
__ports.ifHighSpeed__ = The port speed in mbps.
__ports.ifOperStatus__ = The operational status of the port (up or down).
__ports.ifAdminStatus__ = The administrative status of the port (up or down).
__ports.ifDuplex__ = Duplex setting of the port.
__ports.ifMtu__ = The MTU setting of the port.
## <a name="entity-processors">Processors</a>
__processors.processor_usage__ = The usage of the processor as a percentage.
__processors.processor_descr__ = The description of the processor.
## <a name="entity-storage">Storage</a>
__storage.storage_descr__ = The description of the storage.
__storage.storage_perc__ = The usage of the storage as a percentage.
