more documentation clean up (#10577)

* fix a few bare URLs

* make mdl happy

* make Weathermap.md as mdl happy as possible

* make Varnish.md as mdl happy as possible

* make Two-Factor-Auth.md mdl happy

* touch one header for Syslog.md, but little can be done about the rest

* make Sub-Directory.md as mdl happy as possible

* make SNMP-Trap-Handler.md lint happy

* make SNMP-Proxy.md mdl happy

* make Smokeping.md as mdl happy as possible

* make Services.md mdl happy

* make RRDTune.md mdl happy

* cleanup RRDCached.md as much as possible

* make RRDCached-Security.md mdl happy

* make Rancid.md as mdl happy as possible

* make Proxmox.md mdl happy

* make Plugin-System.md as mdl happy as possible

* make PeeringDB.md mdl happy

* make Oxidized.md more lint happy

* make Network-Map.md mdl happy

* make MIB-based-polling.md as mdl happy as possible

* make Metric-Storage.md mdl happy

* make IRC-Bot.md as mdl happy as possible

* make IRC-Bot-Extensions.md as mdl happy as possible

* make

* make Graylog.md mdl happy

* make Gateone.md mdl happy

* make Fast-Ping-Check.md mdl happy

* make Distributed-Poller.md as mdl happy as possible

* make Dispatcher-Service.md as mdl happy as possible

* make Device-Groups.md mdl happy

* make Dell-OpenManage.md mdl happy

* make Dashboard.md mdl happy

* make Customizing-the-Web-UI.md as mdl happy as possible

* make Component.md mdl happy

* make Billing-Module.md mdl happy

* make Auto-Discovery.md mostly mdl happy

* make Authentication.md as mdl happy as possible

* tidy up a few lines in Applications.md

* make Agent-Setup.md as mdl happy as possible

* make metrics/OpenTSDB.md mdl happy

* spelling fix
This commit is contained in:
Zane C. Bowers-Hadley 2019-09-09 05:48:35 -05:00 committed by Jellyfrog
parent 52f1bc9e8c
commit e4c9153d16
43 changed files with 1704 additions and 870 deletions

View File

@ -1,16 +1,23 @@
source: Extensions/Agent-Setup.md
path: blob/master/doc/
The agent can be used to gather data from remote systems you can use LibreNMS in combination with check_mk (found [here](https://github.com/librenms/librenms-agent)).
The agent can be extended to include data about [applications](Applications.md) on the remote system.
The agent can be used to gather data from remote systems you can use
LibreNMS in combination with check_mk (found
[here](https://github.com/librenms/librenms-agent)). The agent can be
extended to include data about [applications](Applications.md) on the
remote system.
Make sure that systemd or xinetd is installed on the host you want to run the agent on.
Make sure that systemd or xinetd is installed on the host you want to
run the agent on.
The agent uses TCP-Port 6556, please allow access from the **LibreNMS host** and **poller nodes** if you're using the [Distributed Polling](http://docs.librenms.org/Extensions/Distributed-Poller/) setup.
The agent uses TCP-Port 6556, please allow access from the **LibreNMS
host** and **poller nodes** if you're using the [Distributed
Polling](http://docs.librenms.org/Extensions/Distributed-Poller/)
setup.
On each of the hosts you would like to use the agent on, you need to do the following:
1. Clone the `librenms-agent` repository:
1: Clone the `librenms-agent` repository:
```shell
cd /opt/
@ -18,7 +25,7 @@ git clone https://github.com/librenms/librenms-agent.git
cd librenms-agent
```
2. Copy the relevant check_mk_agent to `/usr/bin`:
2: Copy the relevant check_mk_agent to `/usr/bin`:
| linux | freebsd |
| --- | --- |
@ -28,26 +35,36 @@ cd librenms-agent
chmod +x /usr/bin/check_mk_agent
```
3. Copy the service file(s) into place.
3: Copy the service file(s) into place.
| xinetd | systemd |
| --- | --- |
| `cp check_mk_xinetd /etc/xinetd.d/check_mk` | `cp check_mk@.service check_mk.socket /etc/systemd/system` |
4. Create the relevant directories.
4: Create the relevant directories.
```shell
mkdir -p /usr/lib/check_mk_agent/plugins /usr/lib/check_mk_agent/local
```
5. Copy each of the scripts from `agent-local/` into `/usr/lib/check_mk_agent/local` that you require to be graphed. You can find detail setup instructions for specific applications above.
6. Make each one executable that you want to use with `chmod +x /usr/lib/check_mk_agent/local/$script`
7. Enable the check_mk service
5: Copy each of the scripts from `agent-local/` into
`/usr/lib/check_mk_agent/local` that you require to be graphed. You
can find detail setup instructions for specific applications above.
6: Make each one executable that you want to use with `chmod +x
/usr/lib/check_mk_agent/local/$script`
7: Enable the check_mk service
| xinetd | systemd |
| --- | --- |
| `/etc/init.d/xinetd restart` | `systemctl enable check_mk.socket && systemctl start check_mk.socket` |
8. Login to the LibreNMS web interface and edit the device you want to monitor. Under the modules section, ensure that unix-agent is enabled.
9. Then under Applications, enable the apps that you plan to monitor.
10. Wait for around 10 minutes and you should start seeing data in your graphs under Apps for the device.
8: Login to the LibreNMS web interface and edit the device you want to
monitor. Under the modules section, ensure that unix-agent is enabled.
9: Then under Applications, enable the apps that you plan to monitor.
10: Wait for around 10 minutes and you should start seeing data in
your graphs under Apps for the device.

View File

@ -196,7 +196,6 @@ mkdir -p /var/cache/librenms/
3: On the device page in Librenms, edit your host and check the
`Apache` under the Applications tab.
# Asterisk
A small shell script that reports various Asterisk call status.
@ -727,19 +726,22 @@ Extend` heading top of page.
This shell script checks mdadm health and array data
## SNMP Extend
1. Download the script onto the desired host.
1: Download the script onto the desired host.
```
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/mdadm -O /etc/snmp/mdadm
```
2. Run `chmod +x /etc/snmp/mdadm`
2: Run `chmod +x /etc/snmp/mdadm`
3: Edit your snmpd.conf file (usually /etc/snmp/snmpd.conf) and add:
3. Edit your snmpd.conf file (usually /etc/snmp/snmpd.conf) and add:
```
extend mdadm /etc/snmp/mdadm
```
4. Restart snmpd on your host
4: Restart snmpd on your host
The application should be auto-discovered as described at the
top of the page. If it is not, please follow the steps set out

View File

@ -1,11 +1,12 @@
source: Extensions/Authentication.md
path: blob/master/doc/
# Authentication modules
LibreNMS supports multiple authentication modules along with [Two Factor Auth](http://docs.librenms.org/Extensions/Two-Factor-Auth/).
Here we will provide configuration details for these modules.
### Available authentication modules
# Available authentication modules
- MySQL: [mysql](#mysql-authentication)
@ -15,52 +16,68 @@ Here we will provide configuration details for these modules.
- Radius: [radius](#radius-authentication)
- HTTP Auth: [http-auth](#http-authentication), [ad_authorization](#http-authentication-ad-authorization), [ldap_authorization](#http-authentication-ldap-authorization)
- HTTP Auth: [http-auth](#http-authentication),
[ad_authorization](#http-authentication-ad-authorization),
[ldap_authorization](#http-authentication-ldap-authorization)
- Single Sign-on: [sso](#single-sign-on)
⚠️ **When enabling a new authentication module, the local users will no longer be available to log in.**
⚠️ **When enabling a new authentication module, the local users will no
longer be available to log in.**
### Enable authentication module
# Enable authentication module
To enable a particular authentication module you need to set this up in config.php. Please note that only ONE module can be enabled. LibreNMS doesn't support multiple authentication mechanism at the same time.
To enable a particular authentication module you need to set this up
in config.php. Please note that only ONE module can be
enabled. LibreNMS doesn't support multiple authentication mechanism at
the same time.
```php
$config['auth_mechanism'] = "mysql";
```
### User levels and User account type
# User levels and User account type
- 1: **Normal User**: You will need to assign device / port permissions for users at this level.
- 1: **Normal User**: You will need to assign device / port
permissions for users at this level.
- 5: **Global Read**: Read only Administrator.
- 5: **Global Read**: Read only Administrator.
- 10: **Administrator**: This is a global read/write admin account.
- 11: **Demo Account**: Provides full read/write with certain restrictions (i.e can't delete devices).
- 11: **Demo Account**: Provides full read/write with certain
restrictions (i.e can't delete devices).
**Note** Oxidized configs can often contain sensitive data. Because of that only Administrator account type can see configs.
**Note** Oxidized configs can often contain sensitive data. Because of
that only Administrator account type can see configs.
### Note for SELinux users
When using SELinux on the LibreNMS server, you need to allow Apache (httpd) to connect LDAP/Active Directory server, this is disabled by default. You can use SELinux Booleans to allow network access to LDAP resources with this command:
# Note for SELinux users
When using SELinux on the LibreNMS server, you need to allow Apache
(httpd) to connect LDAP/Active Directory server, this is disabled by
default. You can use SELinux Booleans to allow network access to LDAP
resources with this command:
```shell
setsebool -P httpd_can_connect_ldap=1
```
### Testing authentication
# Testing authentication
You can test authentication with this script:
```shell
./scripts/auth_test.php
```
Enable debug output to troubleshoot issues
Enable debug output to troubleshoot issues
# MySQL Authentication
Config option: `mysql`
This is default option with LibreNMS so you should have already have the configuration setup.
This is default option with LibreNMS so you should have already have
the configuration setup.
```php
$config['db_host'] = "HOSTNAME";
@ -69,26 +86,36 @@ $config['db_pass'] = "DBPASS";
$config['db_name'] = "DBNAME";
```
# Active Directory Authentication
Config option: `active_directory`
Install __php_ldap__ or __php7.0-ldap__, making sure to install the same version as PHP.
Install __php_ldap__ or __php7.0-ldap__, making sure to install the
same version as PHP.
If you have issues with secure LDAP try setting `$config['auth_ad_check_certificates']` to `0`, this will ignore certificate errors.
If you have issues with secure LDAP try setting
`$config['auth_ad_check_certificates']` to `0`, this will ignore
certificate errors.
### Require actual membership of the configured groups
## 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, and will be either level 0 or you may set `$config['auth_ad_global_read']` to 1 and all users will have read only access unless otherwise specified.
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, and will be either level 0 or
you may set `$config['auth_ad_global_read']` to 1 and all users will
have read only access unless otherwise specified.
#### Old account cleanup
Cleanup of old accounts is done by checking the authlog. You will need to set the number of days when old accounts will be purged AUTOMATICALLY by daily.sh.
## Old account cleanup
> Please ensure that you set the $config['authlog_purge'] value to be greater than $config['active_directory']['users_purge'] otherwise old users won't be removed.
Cleanup of old accounts is done by checking the authlog. You will need
to set the number of days when old accounts will be purged
AUTOMATICALLY by daily.sh.
### Sample configuration
Please ensure that you set the $config['authlog_purge'] value to be
greater than $config['active_directory']['users_purge'] otherwise old
users won't be removed.
## Sample configuration
```php
$config['auth_mechanism'] = 'active_directory';
@ -107,18 +134,21 @@ $config['auth_ad_groups']['ad-usergroup']['level'] = 5; // set the "AD UserGro
```
Replace `ad-admingroup` with your Active Directory admin-user group and `ad-usergroup` with your standard user group.
It is __highly suggested__ to create a bind user, otherwise "remember me", alerting users, and the API will not work.
Replace `ad-admingroup` with your Active Directory admin-user group
and `ad-usergroup` with your standard user group. It is __highly
suggested__ to create a bind user, otherwise "remember me", alerting
users, and the API will not work.
### Active Directory redundancy
## Active Directory redundancy
You can set two Active Directory servers by editing the `$config['auth_ad_url']` like this example:
You can set two Active Directory servers by editing the
`$config['auth_ad_url']` like this example:
```
$config['auth_ad_url'] = "ldaps://dc1.example.com ldaps://dc2.example.com";
```
### Active Directory LDAP filters
## Active Directory LDAP filters
You can add an LDAP filter to be ANDed with the builtin user filter (`(sAMAccountName=$username)`).
@ -129,16 +159,18 @@ $config['auth_ad_user_filter'] = "(objectclass=user)";
$config['auth_ad_group_filter'] = "(objectclass=group)";
```
This yields `(&(objectclass=user)(sAMAccountName=$username))` for the user filter and `(&(objectclass=group)(sAMAccountName=$group))` for the group filter.
This yields `(&(objectclass=user)(sAMAccountName=$username))` for the
user filter and `(&(objectclass=group)(sAMAccountName=$group))` for
the group filter.
# LDAP Authentication
Config option: `ldap`
Install __php_ldap__ or __php7.0-ldap__, making sure to install the same version as PHP.
Install __php_ldap__ or __php7.0-ldap__, making sure to install the
same version as PHP.
### Standard config
## Standard config
```php
$config['auth_mechanism'] = 'ldap';
@ -150,7 +182,7 @@ $config['auth_ldap_groups']['pfy']['level'] = 5; // set pfy group
$config['auth_ldap_groups']['support']['level'] = 1; // set support group as a normal user
```
### Additional options (usually not needed):
## Additional options (usually not needed)
```php
$config['auth_ldap_version'] = 3; # v2 or v3
@ -165,17 +197,22 @@ $config['auth_ldap_userdn'] = true; // Uses a users full DN as t
$config['auth_ldap_userlist_filter'] = 'service=informatique'; // Replace 'service=informatique' by your ldap filter to limit the number of responses if you have an ldap directory with thousand of users
```
### LDAP bind user (optional)
If your ldap server does not allow anonymous bind, it is highly suggested to create a bind user, otherwise "remember me", alerting users, and the API will not work.
## LDAP bind user (optional)
If your ldap server does not allow anonymous bind, it is highly
suggested to create a bind user, otherwise "remember me", alerting
users, and the API will not work.
```php
$config['auth_ldap_binduser'] = 'ldapbind'; // will use auth_ldap_prefix and auth_ldap_suffix
#$config['auth_ldap_binddn'] = 'CN=John.Smith,CN=Users,DC=MyDomain,DC=com'; // overrides binduser
$config['auth_ldap_bindpassword'] = 'password';
```
### LDAP server redundancy
## LDAP server redundancy
You can set two LDAP servers by editing the `$config['auth_ldap_server']` like this example:
You can set two LDAP servers by editing the
`$config['auth_ldap_server']` like this example:
```
$config['auth_ldap_server'] = "ldaps://dir1.example.com ldaps://dir2.example.com";
@ -195,9 +232,15 @@ $config['auth_ldap_groupmemberattr'] = "member";
$config['auth_ldap_groups'] = ['{group}' => ['level' => 10],];
$config['auth_ldap_userdn'] = true;
```
Replace {id} with the unique ID provided by Jumpcloud. Replace {group} with the unique group name created in Jumpcloud. This field is case sensitive.
Note: If you have multiple user groups to define individual access levels replace the `$config['auth_ldap_groups']` line with the following:
Replace {id} with the unique ID provided by Jumpcloud. Replace
{group} with the unique group name created in Jumpcloud. This field
is case sensitive.
Note: If you have multiple user groups to define individual access
levels replace the `$config['auth_ldap_groups']` line with the
following:
```php
$config['auth_ldap_groups'] = [
'{admin_group}' => ['level' => 10],
@ -205,10 +248,12 @@ $config['auth_ldap_groups'] = [
];
```
# 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.
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.
```php
$config['radius']['hostname'] = 'localhost';
@ -219,27 +264,33 @@ $config['radius']['users_purge'] = 14;//Purge users who haven't logged in for 14
$config['radius']['default_level'] = 1;//Set the default user level when automatically creating a user.
```
#### Old account cleanup
Cleanup of old accounts is done by checking the authlog. You will need to set the number of days when old accounts will be purged AUTOMATICALLY by daily.sh.
## Old account cleanup
> 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.
Cleanup of old accounts is done by checking the authlog. You will need
to set the number of days when old accounts will be purged
AUTOMATICALLY by daily.sh.
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.
# HTTP Authentication
Config option: `http-auth`
LibreNMS will expect the user to have authenticated via your webservice already. At this stage it will need to assign a
userlevel for that user which is done in one of two ways:
LibreNMS will expect the user to have authenticated via your
webservice already. At this stage it will need to assign a userlevel
for that user which is done in one of two ways:
- A user exists in MySQL still where the usernames match up.
- A global guest user (which still needs to be added into MySQL:
```php
$config['http_auth_guest'] = "guest";
```
This will then assign the userlevel for guest to all authenticated users.
This will then assign the userlevel for guest to all authenticated users.
## HTTP Authentication / AD Authorization
@ -247,15 +298,24 @@ Config option: `ad-authorization`
This module is a combination of ___http-auth___ and ___active_directory___
LibreNMS will expect the user to have authenticated via your webservice already (e.g. using Kerberos Authentication in Apache) but will use Active Directory lookups to determine and assign the userlevel of a user.
The userlevel will be calculated by using AD group membership information as the ___active_directory___ module does.
LibreNMS will expect the user to have authenticated via your
webservice already (e.g. using Kerberos Authentication in Apache) but
will use Active Directory lookups to determine and assign the
userlevel of a user. The userlevel will be calculated by using AD
group membership information as the ___active_directory___ module
does.
The configuration is the same as for the ___active_directory___ module with two extra, optional options: auth_ad_binduser and auth_ad_bindpassword.
These should be set to a AD user with read capabilities in your AD Domain in order to be able to perform searches.
If these options are omitted, the module will attempt an anonymous bind (which then of course must be allowed by your Active Directory server(s)).
The configuration is the same as for the ___active_directory___ module
with two extra, optional options: auth_ad_binduser and
auth_ad_bindpassword. These should be set to a AD user with read
capabilities in your AD Domain in order to be able to perform
searches. If these options are omitted, the module will attempt an
anonymous bind (which then of course must be allowed by your Active
Directory server(s)).
There is also one extra option for controlling user information caching: auth_ldap_cache_ttl.
This option allows to control how long user information (user_exists, userid, userlevel) are cached within the PHP Session.
This option allows to control how long user information (user_exists,
userid, userlevel) are cached within the PHP Session.
The default value is 300 seconds.
To disable this caching (highly discourage) set this option to 0.
@ -265,15 +325,17 @@ $config['auth_ad_bindpassword'] = "ad_bindpassword";
$config['auth_ldap_cache_ttl'] = 300;
```
## HTTP Authentication / LDAP Authorization
Config option: `ldap-authorization`
This module is a combination of ___http-auth___ and ___ldap___
LibreNMS will expect the user to have authenticated via your webservice already (e.g. using Kerberos Authentication in Apache) but will use LDAP to determine and assign the userlevel of a user.
The userlevel will be calculated by using LDAP group membership information as the ___ldap___ module does.
LibreNMS will expect the user to have authenticated via your
webservice already (e.g. using Kerberos Authentication in Apache) but
will use LDAP to determine and assign the userlevel of a user. The
userlevel will be calculated by using LDAP group membership
information as the ___ldap___ module does.
The configuration is the same as for the ___ldap___ module with one extra option: auth_ldap_cache_ttl.
This option allows to control how long user information (user_exists, userid, userlevel) are cached within the PHP Session.
@ -284,7 +346,8 @@ To disabled this caching (highly discourage) set this option to 0.
$config['auth_ldap_cache_ttl'] = 300;
```
## View/embedded graphs without being logged into LibreNMS
# View/embedded graphs without being logged into LibreNMS
```php
$config['allow_unauth_graphs_cidr'] = array('127.0.0.1/32');
$config['allow_unauth_graphs'] = true;
@ -292,12 +355,25 @@ $config['allow_unauth_graphs'] = true;
# Single Sign-on
The single sign-on mechanism is used to integrate with third party authentication providers that are managed outside of LibreNMS - such as ADFS, Shibboleth, EZProxy, BeyondCorp, and others.
A large number of these methods use [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) - the module has been written assuming the use of SAML, and therefore these instructions contain some SAML terminology, but it should be possible to use any software that works in a similar way.
The single sign-on mechanism is used to integrate with third party
authentication providers that are managed outside of LibreNMS - such
as ADFS, Shibboleth, EZProxy, BeyondCorp, and others. A large number
of these methods use
[SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language)
the module has been written assuming the use of SAML, and therefore
these instructions contain some SAML terminology, but it should be
possible to use any software that works in a similar way.
In order to make use of the single sign-on module, you need to have an Identity Provider up and running, and know how to configure your Relying Party to pass attributes to LibreNMS via header injection or environment variables. Setting these up is outside of the scope of this documentation.
In order to make use of the single sign-on module, you need to have an
Identity Provider up and running, and know how to configure your
Relying Party to pass attributes to LibreNMS via header injection or
environment variables. Setting these up is outside of the scope of
this documentation.
As this module deals with authentication, it is extremely careful about validating the configuration - if it finds that certain values in the configuration are not set, it will reject access rather than try and guess.
As this module deals with authentication, it is extremely careful
about validating the configuration - if it finds that certain values
in the configuration are not set, it will reject access rather than
try and guess.
## Basic Configuration
@ -311,38 +387,57 @@ $config['sso']['static_level'] = 10;
```
This, along with the defaults, sets up a basic Single Sign-on setup that:
* Reads values from environment variables
* Automatically creates users when they're first seen
* Authomatically updates users with new values
* Gives everyone privilege level 10
This happens to mimic the behaviour of [http-auth](#http-auth), so if this is the kind of setup you want, you're probably better of just going and using that mechanism.
- Reads values from environment variables
- Automatically creates users when they're first seen
- Authomatically updates users with new values
- Gives everyone privilege level 10
This happens to mimic the behaviour of [http-auth](#http-auth), so if
this is the kind of setup you want, you're probably better of just
going and using that mechanism.
## Security
If there is a proxy involved (e.g. EZProxy, Azure AD Application Proxy, NGINX, mod_proxy) it's ___essential___ that you have some means in place to prevent headers being injected between the proxy and the end user, and also prevent end users from contacting LibreNMS directly.
If there is a proxy involved (e.g. EZProxy, Azure AD Application
Proxy, NGINX, mod_proxy) it's ___essential___ that you have some means
in place to prevent headers being injected between the proxy and the
end user, and also prevent end users from contacting LibreNMS
directly.
This should also apply to user connections to the proxy itself - the proxy ___must not___ be allowed to blindly pass through HTTP headers. ___mod_security___ should be considered a minimum, with a full [WAF](https://en.wikipedia.org/wiki/Web_application_firewall) being strongly recommended. This advice applies to the IDP too.
This should also apply to user connections to the proxy itself - the
proxy ___must not___ be allowed to blindly pass through HTTP
headers. ___mod_security___ should be considered a minimum, with a
full [WAF](https://en.wikipedia.org/wiki/Web_application_firewall)
being strongly recommended. This advice applies to the IDP too.
The mechanism includes very basic protection, in the form of an IP whitelist with should contain the source addresses of your proxies:
The mechanism includes very basic protection, in the form of an IP
whitelist with should contain the source addresses of your proxies:
```php
$config['sso']['trusted_proxies'] = ['127.0.0.1/8', '::1/128', '192.0.2.0', '2001:DB8::'];
```
This configuration item should contain an array with a list of IP addresses or CIDR prefixes that are allowed to connect to LibreNMS and supply environment variables or headers.
This configuration item should contain an array with a list of IP
addresses or CIDR prefixes that are allowed to connect to LibreNMS and
supply environment variables or headers.
## Advanced Configuration Options
### User Attribute
If for some reason your relying party doesn't store the username in ___REMOTE_USER___, you can override this choice.
If for some reason your relying party doesn't store the username in
___REMOTE_USER___, you can override this choice.
```php
$config['sso']['user_attr'] = 'HTTP_UID';
```
Note that the user lookup is a little special - normally headers are prefixed with ___HTTP\____, however this is not the case for remote user - it's a special case. If you're using something different you need to figure out of the ___HTTP\____ prefix is required or not yourself.
Note that the user lookup is a little special - normally headers are
prefixed with ___HTTP\____, however this is not the case for remote
user - it's a special case. If you're using something different you
need to figure out of the ___HTTP\____ prefix is required or not
yourself.
### Automatic User Create/Update
@ -353,11 +448,16 @@ $config['sso']['create_users'] = true;
$config['sso']['update_users'] = true;
```
If these are not enabled, user logins will be (somewhat silently) rejected unless an administrator has created the account in advance. Note that in the case of SAML federations, unless release of the users true identity has been negotiated with the IDP, the username (probably ePTID) is not likely to be predicable.
If these are not enabled, user logins will be (somewhat silently)
rejected unless an administrator has created the account in
advance. Note that in the case of SAML federations, unless release of
the users true identity has been negotiated with the IDP, the username
(probably ePTID) is not likely to be predicable.
### Personalisation
If the attributes are being populated, you can instruct the mechanism to add additional information to the user's database entry:
If the attributes are being populated, you can instruct the mechanism
to add additional information to the user's database entry:
```php
$config['sso']['email_attr'] = "mail";
@ -369,7 +469,9 @@ $config['sso']['descr_attr'] = "unscoped-affiliation
#### Static
As used above, ___static___ gives every single user the same privilege level. If you're working with a small team, or don't need access control, this is probably suitable.
As used above, ___static___ gives every single user the same privilege
level. If you're working with a small team, or don't need access
control, this is probably suitable.
#### Attribute
@ -378,9 +480,14 @@ $config['sso']['group_strategy'] = "attribute";
$config['sso']['level_attr'] = "entitlement";
```
If your Relying Party is capable of calculating the necessary privilege level, you can configure the module to read the privilege number straight from an attribute. ___sso_level_attr___ should contain the name of the attribute that the Relying Party exposes to LibreNMS - as long as ___sso_mode___ is correctly set, the mechanism should find the value.
If your Relying Party is capable of calculating the necessary
privilege level, you can configure the module to read the privilege
number straight from an attribute. ___sso_level_attr___ should contain
the name of the attribute that the Relying Party exposes to LibreNMS -
as long as ___sso_mode___ is correctly set, the mechanism should find
the value.
### Group Map
#### Group Map
This is the most flexible (and complex) way of assigning privileges.
@ -391,10 +498,16 @@ $config['sso']['group_level_map'] = ['librenms-admins' => 10, 'librenms-readers'
$config['sso']['group_delimiter'] = ';';
```
The mechanism expects to find a delimited list of groups within the attribute that ___sso_group_attr___ points to. This should be an associative array of group name keys, with privilege levels as values.
The mechanism will scan the list and find the ___highest___ privilege level that the user is entitled to, and assign that value to the user.
The mechanism expects to find a delimited list of groups within the
attribute that ___sso_group_attr___ points to. This should be an
associative array of group name keys, with privilege levels as
values. The mechanism will scan the list and find the ___highest___
privilege level that the user is entitled to, and assign that value to
the user.
This format may be specific to Shibboleth; other relying party software may need changes to the mechanism (e.g. ___mod_auth_mellon___ may create pseudo arrays).
This format may be specific to Shibboleth; other relying party
software may need changes to the mechanism (e.g. ___mod_auth_mellon___
may create pseudo arrays).
There is an optional value for sites with large numbers of groups:
@ -406,9 +519,11 @@ This filter causes the mechanism to only consider groups matching a regular expr
### Logout Behaviour
LibreNMS has no capability to log out a user authenticated via Single Sign-On - that responsability falls to the Relying Party.
LibreNMS has no capability to log out a user authenticated via Single
Sign-On - that responsability falls to the Relying Party.
If your Relying Party has a magic URL that needs to be called to end a session, you can configure LibreNMS to direct the user to it:
If your Relying Party has a magic URL that needs to be called to end a
session, you can configure LibreNMS to direct the user to it:
```php
$config['post_logout_action'] = '/Shibboleth.sso/Logout';
@ -418,7 +533,9 @@ This option functions independantly of the Single Sign-on mechanism.
## Complete Configuration
This configuration works on my deployment with a Shibboleth relying party, injecting environment variables, with the IDP supplying a list of groups.
This configuration works on my deployment with a Shibboleth relying
party, injecting environment variables, with the IDP supplying a list
of groups.
```php
$config['auth_mechanism'] = 'sso';

View File

@ -1,21 +1,26 @@
source: Extensions/Auto-Discovery.md
path: blob/master/doc/
# Auto Discovery Support
### Getting Started
## Getting Started
LibreNMS provides the ability to automatically add devices on your network, we can do this via
a few methods which will be explained below and also indicate if they are enabled by default.
LibreNMS provides the ability to automatically add devices on your
network, we can do this via a few methods which will be explained
below and also indicate if they are enabled by default.
All discovery methods run when discovery runs (every 6 hours by default and within 5 minutes for new devices).
All discovery methods run when discovery runs (every 6 hours by
default and within 5 minutes for new devices).
> Please note that you need at least ONE device added before auto-discovery will work.
Please note that you need at least ONE device added before
auto-discovery will work.
The first thing to do though is add the required configuration options to `config.php`.
### SNMP Details
## SNMP Details
To add devices automatically we need to know your snmp details, examples of SNMP v1, v2c and v3 are below:
To add devices automatically we need to know your snmp details,
examples of SNMP v1, v2c and v3 are below:
```php
// v1 or v2c
@ -31,56 +36,71 @@ $config['snmp']['v3'][0]['cryptopass'] = 'my_crypto';
$config['snmp']['v3'][0]['cryptoalgo'] = 'AES';
```
These details will be attempted when adding devices, you can specify any mixture of these.
These details will be attempted when adding devices, you can specify
any mixture of these.
### Allowed Networks
#### Your Networks
## Allowed Networks
To add devices, we need to know what are your subnets so we don't go blindly attempting to add devices not
under your control.
### Your Networks
To add devices, we need to know what are your subnets so we don't go
blindly attempting to add devices not under your control.
```php
$config['nets'][] = '192.168.0.0/24';
$config['nets'][] = '172.2.4.0/22';
```
### Exclusions
## Exclusions
If you have added a network as above but a single device exists within it that you can't auto
add, then you can exclude this with the following:
If you have added a network as above but a single device exists within
it that you can't auto add, then you can exclude this with the following:
```php
$config['autodiscovery']['nets-exclude'][] = '192.168.0.1/32';
```
## Additional Options
#### Discovering devices by IP
# Additional Options
By default we don't add devices by IP address, we look for a reverse dns name to be found and add with that. If this fails
and you would like to still add devices automatically then you will need to set `$config['discovery_by_ip'] = true;`
## Discovering devices by IP
#### Short hostnames
By default we don't add devices by IP address, we look for a reverse
dns name to be found and add with that. If this fails
and you would like to still add devices automatically then you will
need to set `$config['discovery_by_ip'] = true;`
If your devices only return a short hostname such as lax-fa0-dc01 but the full name should be lax-fa0-dc01.example.com then you can
### Short hostnames
If your devices only return a short hostname such as lax-fa0-dc01 but
the full name should be lax-fa0-dc01.example.com then you can
set `$config['mydomain'] = 'example.com';`
#### Allow Duplicate sysName
### Allow Duplicate sysName
By default we require unique sysNames when adding devices (this is returned over snmp by your devices). If you would like to allow
devices to be added with duplicate sysNames then please set `$config['allow_duplicate_sysName'] = true;`.
By default we require unique sysNames when adding devices (this is
returned over snmp by your devices). If you would like to allow
devices to be added with duplicate sysNames then please set
`$config['allow_duplicate_sysName'] = true;`.
# Discovery Methods
## Discovery Methods
Below are the methods for auto discovering devices. Each one can be enabled or disabled and may have additional configuration options.
Below are the methods for auto discovering devices. Each one can be
enabled or disabled and may have additional configuration options.
## ARP
### ARP
Disabled by default.
Adds devices that are listed in another device's arp table. This module depends on the arp-table module being enabled and returning data.
Adds devices that are listed in another device's arp table. This
module depends on the arp-table module being enabled and returning
data.
To enable, switch on globally the `$config['discovery_modules']['discovery-arp'] = true;` or per device within the Modules section.
To enable, switch on globally the
`$config['discovery_modules']['discovery-arp'] = true;` or per device
within the Modules section.
## XDP
### XDP
Enabled by default.
`$config['autodiscovery']['xdp'] = false;` to disable.
@ -113,12 +133,14 @@ $config['autodiscovery']['xdp_exclude']['sysdesc_regexp'][] = '/-K9W8-/'; // Cis
$config['autodiscovery']['cdp_exclude']['platform_regexp'][] = '/^Cisco IP Phone/'; //Cisco IP Phone
```
### OSPF
## OSPF
Enabled by default.
`$config['autodiscovery']['ospf'] = false;` to disable.
### BGP
## BGP
Enabled by default.
`$config['autodiscovery']['bgp'] = false;` to disable.
@ -126,13 +148,18 @@ Enabled by default.
This module is invoked from bgp-peers discovery module.
## SNMP Scan
Apart from the aforementioned Auto-Discovery options, LibreNMS is also able to proactively scan a network for SNMP-enabled devices using the configured version/credentials.
Apart from the aforementioned Auto-Discovery options, LibreNMS is also
able to proactively scan a network for SNMP-enabled devices using the
configured version/credentials.
SNMP Scan will scan `$config['nets']` by default and respects `$config['autodiscovery']['nets-exclude']`.
To run the SNMP-Scanner you need to execute the `snmp-scan.py` from within your LibreNMS installation directory.
To run the SNMP-Scanner you need to execute the `snmp-scan.py` from
within your LibreNMS installation directory.
Here the script's help-page for reference:
```text
usage: snmp-scan.py [-h] [-r NETWORK] [-t THREADS] [-l] [-v]

View File

@ -1,9 +1,11 @@
source: Extensions/Billing-Module.md
path: blob/master/doc/
# Billing Module
With the billing module you can create a bill, assign a quota to it and add ports to it.
It then tracks the ports usage and shows you the usage in the bill, including any overage.
With the billing module you can create a bill, assign a quota to it
and add ports to it. It then tracks the ports usage and shows you the
usage in the bill, including any overage.
Accounting by both total transferred data and 95th percentile is supported.
To enable and use the billing module you need to perform the following steps:
@ -25,22 +27,23 @@ Create billing graphs as required.
## Data Retention
Billing data is stored in the MySQL database, and you may wish to purge the detailed
stats for old data (per-month totals will always be kept). To enable this, add the
Billing data is stored in the MySQL database, and you may wish to
purge the detailed stats for old data (per-month totals will always be
kept). To enable this, add the
following to `config.php`:
```php
$config['billing_data_purge'] = 12; // Number of months to retain
```
Data for the last complete billing cycle will always be retained - only data older than
this by the configured number of months will be removed. This task is performed in the
daily cleanup tasks.
Data for the last complete billing cycle will always be retained -
only data older than this by the configured number of months will be
removed. This task is performed in the daily cleanup tasks.
## 95th Percentile Calculation
For 95th Percentile billing, the default behavior is to use the highest of the input
or output 95th Percentile calculation.
For 95th Percentile billing, the default behavior is to use the
highest of the input or output 95th Percentile calculation.
To instead use the combined total of inout + output to derive the 95th percentile,
This can be changed on a per bill basis by setting 95th Calculation to "Aggregate".
@ -52,5 +55,5 @@ add the following the `config.php`:
$config['billing']['95th_default_agg'] = 1; // Set aggregate 95th as default
```
This configuration setting is cosmetic and only changes the default selected option
when adding a new bill
This configuration setting is cosmetic and only changes the default
selected option when adding a new bill.

View File

@ -3,10 +3,13 @@ path: blob/master/doc/
# About
The Component extension provides a generic database storage mechanism for discovery and poller modules.
The Driver behind this extension was to provide the features of ports, in a generic manner to discovery/poller modules.
The Component extension provides a generic database storage mechanism
for discovery and poller modules. The Driver behind this extension was
to provide the features of ports, in a generic manner to
discovery/poller modules.
It provides a status (Nagios convention), the ability to Disable (do not poll), or Ignore (do not Alert).
It provides a status (Nagios convention), the ability to Disable (do
not poll), or Ignore (do not Alert).
# Database Structure
@ -47,9 +50,13 @@ mysql> select * from component_prefs limit 1;
## Reserved Fields
When this data from both the `component` and `component_prefs` tables is returned in one single consolidated array, there is the potential for someone to attempt to set an attribute (in the `component_prefs`) table that is used in the `component` table.
Because of this all fields of the `component` table are reserved, they cannot be used as custom attributes, if you update these the module will attempt to write them to the `component` table, not the `component_prefs` table.
When this data from both the `component` and `component_prefs` tables
is returned in one single consolidated array, there is the potential
for someone to attempt to set an attribute (in the `component_prefs`)
table that is used in the `component` table. Because of this all
fields of the `component` table are reserved, they cannot be used as
custom attributes, if you update these the module will attempt to
write them to the `component` table, not the `component_prefs` table.
# Using Components
@ -105,15 +112,18 @@ Array
)
```
Where X is the Device ID and Y1/Y2 is the Component ID. In the example above, `TEST_ATTR` is a custom field, the rest are reserved fields.
Where X is the Device ID and Y1/Y2 is the Component ID. In the example
above, `TEST_ATTR` is a custom field, the rest are reserved fields.
### Options
Options can be supplied to `getComponents` to influence which and how components are returned.
Options can be supplied to `getComponents` to influence which and how
components are returned.
#### Filtering
You can filter on any of the [reserved](#reserved) fields. Filters are created in the following format:
You can filter on any of the [reserved](#reserved) fields. Filters are
created in the following format:
```php
$options['filter']['FIELD'] = array ('OPERATOR', 'CRITERIA');
@ -122,10 +132,10 @@ $options['filter']['FIELD'] = array ('OPERATOR', 'CRITERIA');
Where:
- `FIELD` - The [reserved](#reserved) field to filter on
- `OPERATOR` - 'LIKE' or '=', are we checking if the FIELD equals or contains the CRITERIA.
- `OPERATOR` - 'LIKE' or '=', are we checking if the FIELD equals or
contains the CRITERIA.
- `CRITERIA` - The criteria to search on
There are 2 filtering shortcuts:
`$DEVICE_ID` is a synonym for:
@ -153,7 +163,6 @@ Where Direction is one of:
- `ASC` - Ascending, from Low to High
- `DESC` - Descending, from High to Low
## Creating Components
To create a new component, run the `createComponent` function.
@ -161,12 +170,14 @@ To create a new component, run the `createComponent` function.
```php
$ARRAY = $COMPONENT->createComponent($DEVICE_ID, $TYPE);
```
`createComponent` takes 2 arguments:
- `DEVICE_ID` - The ID of the device to attach the component to.
- `TYPE` - The unique type for your module.
This will return a new, empty array with a component ID and Type set, all other fields will be set to defaults.
This will return a new, empty array with a component ID and Type set,
all other fields will be set to defaults.
```php
Array
@ -193,18 +204,20 @@ $COMPONENT->deleteComponent($COMPONENT_ID)
This will return `True` on success or `False` on failure.
## Editing Components
To edit a component, the procedure is:
1. [Get the Current Components](#get)
2. [Edit the array](#update-edit)
3. [Write the components](#update-write)
1. [Edit the array](#update-edit)
1. [Write the components](#update-write)
### Edit the Array
Once you have a component array from `getComponents` the first thing to do is extract the components for only the single device you are editing. This is required because the `setComponentPrefs` function only saves a single device at a time.
Once you have a component array from `getComponents` the first thing
to do is extract the components for only the single device you are
editing. This is required because the `setComponentPrefs` function
only saves a single device at a time.
```php
$ARRAY = $COMPONENT->getComponents($DEVICE_ID, $OPTIONS);
@ -238,14 +251,17 @@ To write component changes back to the database simply:
$COMPONENT->setComponentPrefs($DEVICE_ID, $ARRAY)
```
When writing the component array there are several caveats to be aware of, these are:
When writing the component array there are several caveats to be aware
of, these are:
- `$ARRAY` must be in the format of a single device ID - `$ARRAY[$COMPONENT_ID][Attribute] = 'Value';` NOT in the multi device format returned by `getComponents` - `$ARRAY[$DEVICE_ID][$COMPONENT_ID][Attribute] = 'Value';`
- `$ARRAY` must be in the format of a single device ID -
`$ARRAY[$COMPONENT_ID][Attribute] = 'Value';` NOT in the multi
device format returned by `getComponents` -
`$ARRAY[$DEVICE_ID][$COMPONENT_ID][Attribute] = 'Value';`
- You cannot edit the Component ID or the Device ID
- [reserved](#reserved) fields can not be removed
- if a change is found an entry will be written to the eventlog.
## API
Component details are available via the API.
@ -253,26 +269,40 @@ Please see the [API-Docs](/API/#function-get_components) for details.
## Alerting
It is intended that discovery/poller modules will detect the status of a component during the polling cycle.
Status is logged using the Nagios convention for status codes, where:
0 = Ok,
1 = Warning,
2 = Critical
It is intended that discovery/poller modules will detect the status of
a component during the polling cycle. Status is logged using the
Nagios convention for status codes, where:
If you are creating a poller module which can detect a fault condition simply set STATUS to something other than 0 and ERROR to a message that indicates the problem.
```
0 = Ok,
1 = Warning,
2 = Critical
```
To actually raise an alert, the user will need to create an alert rule. To assist with this several Alerting Macro's have been created:
If you are creating a poller module which can detect a fault condition
simply set STATUS to something other than 0 and ERROR to a message
that indicates the problem.
- `%macro.component_normal` - A component that is not disabled or ignored and in a Normal state.
- `%macro.component_warning` - A component that is not disabled or ignored and NOT in a Warning state.
- `%macro.component_critical` - A component that is not disabled or ignored and NOT in a Critical state.
To actually raise an alert, the user will need to create an alert
rule. To assist with this several Alerting Macro's have been created:
- `%macro.component_normal` - A component that is not disabled or
ignored and in a Normal state.
- `%macro.component_warning` - A component that is not disabled or
ignored and NOT in a Warning state.
- `%macro.component_critical` - A component that is not disabled or
ignored and NOT in a Critical state.
To raise alerts for components, the following rules could be created:
- `%macros.component_critical = "1"` - To alert on all Critical components
- `%macros.component_critical = "1" && %component.type = "<Type of Component>"` - To alert on all Critical components of a particular type.
- `%macros.component_critical = "1"` - To alert on all Critical
components
- `%macros.component_critical = "1" && %component.type = "<Type of
Component>"` - To alert on all Critical components of a particular
type.
If there is a particular component you would like excluded from alerting, simply set the ignore field to 1.
If there is a particular component you would like excluded from
alerting, simply set the ignore field to 1.
The data that is written to each alert when it is raised is in the following format:
@ -280,14 +310,15 @@ The data that is written to each alert when it is raised is in the following for
# Example Code
To see an example of how the component module can used, please see the following modules:
To see an example of how the component module can used, please see the
following modules:
- Cisco CBQoS
- `includes/discovery/cisco-cbqos.inc.php`
- `includes/polling/cisco-cbqos.inc.php`
- `html/includes/graphs/device/cbqos_traffic.inc.php`
- `includes/discovery/cisco-cbqos.inc.php`
- `includes/polling/cisco-cbqos.inc.php`
- `html/includes/graphs/device/cbqos_traffic.inc.php`
- Cisco OTV
- `includes/discovery/cisco-otv.inc.php`
- `includes/polling/cisco-otv.inc.php`
- `html/includes/graphs/device/cisco-otv-mac.inc.php`
- `html/pages/routing/cisco-otv.inc.php`
- `includes/discovery/cisco-otv.inc.php`
- `includes/polling/cisco-otv.inc.php`
- `html/includes/graphs/device/cisco-otv-mac.inc.php`
- `html/pages/routing/cisco-otv.inc.php`

View File

@ -8,6 +8,7 @@ path: blob/master/doc/
Create the file `resources/views/menu/custom.blade.php`
Example contents:
```blade
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-hover="dropdown" data-toggle="dropdown"><i class="fa fa-star fa-fw fa-lg fa-nav-icons hidden-md" aria-hidden="true"></i>
@ -28,15 +29,16 @@ Example contents:
</ul>
</li>
```
## Custom device menu entry
You can add custom external links in the menu on the device page.
This feature allows you to easily link applications to related systems, as shown in the example of Open-audIT.
This feature allows you to easily link applications to related
systems, as shown in the example of Open-audIT.
The Links value is parsed by Laravel Blade's templating engine so you can use Device variables such as `hostname`, `sysName` and more.
The Links value is parsed by Laravel Blade's templating engine so you
can use Device variables such as `hostname`, `sysName` and more.
`config.php:`

View File

@ -2,79 +2,102 @@ source: Extensions/Dashboards.md
path: blob/master/doc/
# Dashboards
Create customised dashboards in LibreNMS per user. You can share dashboards with other users. You can also make a custom dashboard and
Create customised dashboards in LibreNMS per user. You can share
dashboards with other users. You can also make a custom dashboard and
default it for all users in LibreNMS.
Example Dashboard
![Example Dashboard](/img/example-dashboard.png)
### Widgets
LibreNMS has a whole list of Widgets to select from.
## Widgets
+ Alerts Widget: Displays all alert notifications.
+ Availability Map: Displays all devices with colored tiles, green up, yellow for warning (device has been restarted in last 24 hours),red for down. You can also list all services and ignored/disabled devcies in this widget.
+ Componet Status: List all componets Ok state, Warning state, Critical state.
+ Device Summary horizontal: List device totals, up, down, ignored, disabled. Same for ports and services.
+ Device Summary vertical: List device totals, up, down, ignored, disabled. Same for ports and services.
+ Eventlog: Displays all events with your devices and LibreNMS.
+ External Image: can be used to show external images on your dashboard. Or images from inside LibreNMS.
+ Globe Map: Will display map of the globe.
+ Graph: Can be used to display graphs from devices.
+ Graylog: Displays all Graylog's syslog entries.
+ Notes: use for html tags, embed links and external web pages. Or just notes in general.
+ Server Stats: Will display gauges for CPU, Memory, Storage usage. Note the device type has to be listed as "Server".
+ Syslog: Displays all syslog entries.
+ Top Devices: By Traffic, or Uptime, or Response time, or Poller Duration, or Procssor load, or Memory Usage, or Storage Usage.
+ Top Interfaces: Lists top interfaces by traffic utilization.
+ Worldmap: displays all your devices locations. From syslocation or from override sysLocation.
LibreNMS has a whole list of Widgets to select from.
List of Widgets:
- Alerts Widget: Displays all alert notifications.
- Availability Map: Displays all devices with colored tiles, green up,
yellow for warning (device has been restarted in last 24 hours),red
for down. You can also list all services and ignored/disabled
devcies in this widget.
- Componet Status: List all componets Ok state, Warning state, Critical state.
- Device Summary horizontal: List device totals, up, down, ignored,
disabled. Same for ports and services.
- Device Summary vertical: List device totals, up, down, ignored,
disabled. Same for ports and services.
- Eventlog: Displays all events with your devices and LibreNMS.
- External Image: can be used to show external images on your
dashboard. Or images from inside LibreNMS.
- Globe Map: Will display map of the globe.
- Graph: Can be used to display graphs from devices.
- Graylog: Displays all Graylog's syslog entries.
- Notes: use for html tags, embed links and external web pages. Or
just notes in general.
- Server Stats: Will display gauges for CPU, Memory, Storage
usage. Note the device type has to be listed as "Server".
- Syslog: Displays all syslog entries.
- Top Devices: By Traffic, or Uptime, or Response time, or Poller
Duration, or Procssor load, or Memory Usage, or Storage Usage.
- Top Interfaces: Lists top interfaces by traffic utilization.
- Worldmap: displays all your devices locations. From syslocation or
from override sysLocation.
List of Widgets:
![List of Widgets][image of widgets]
[image of widgets]: /img/list-widgets.png "List of the widgets"
## Dashboard Permissions
### Dashboard Permissions
- Private: Sets the dashabord to only the user that created the dashboard can view and edit.
- Shared Read: Sets the dashboard to allow other users to view the dashboard, but cant make changes to the dashboard.
- Private: Sets the dashabord to only the user that created the
dashboard can view and edit.
- Shared Read: Sets the dashboard to allow other users to view the
dashboard, but cant make changes to the dashboard.
- Shared: Allows all users to view the dashboard and make changes.
### Setting a global default dashboard
## Setting a global default dashboard
Step 1: Set the dashboard to either shared read or shared, depending on what you want the users access to change.
Step 1: Set the dashboard to either shared read or shared, depending
on what you want the users access to change.
Step 2: Then go to Settings -> WebUI settings -> Dashboard Settings and set the global default dashboard.
Step 2: Then go to Settings -> WebUI settings -> Dashboard Settings
and set the global default dashboard.
### Setting embeded webpage
## Setting embeded webpage
Using the Notes Widget.
```html
<iframe src="your_url" frameBorder="0" width="100%" height = "100%">
<p>Your browser does not support iframes.</p>
</iframe>
```
Note you may need to play with the width and height and also size your widget properly.
``` src="url" ``` needs to be URL to webpage your linking to.
Also some web pages may not support html embeded or iframe.
![Example embed webpage](/img/example-embed-website.png)
### How to create ports graph
## How to create ports graph
In the dashboard, you want to create an interface graph select the widget called
* Graph: then select "Port" "Bits"
'Graph' then select "Port" "Bits"
![port-bits-graph](/img/port-bits-graph.png)
* Note: you can map the port by description or the alias or by port id. You will need to know this in order to map the port to the graph.
Note: you can map the port by description or the alias or by port
id. You will need to know this in order to map the port to the graph.
![port-bits-graph](/img/port-bits-port.png)
### Dimension parameter replacement for Generic-image widget
## Dimension parameter replacement for Generic-image widget
When using the Generic-image widget you can provide the width and height of the widget with your request.
This will ensure that the image will fit nicely with the dimensions if the Generic-image widget.
When using the Generic-image widget you can provide the width and
height of the widget with your request. This will ensure that the
image will fit nicely with the dimensions if the Generic-image widget.
You can add @AUTO_HEIGHT@ and @AUTO_WIDTH@ to the Image URL as parameters.
#### Examples:
+ http://librenms.example.com/graph.php?id=333%2C444&type=multiport_bits_separate&legend=no&absolute=1&from=-14200&width=@AUTO_WIDTH@&height=@AUTO_HEIGHT@
+ http://example.com/myimage.php?size=@AUTO_WIDTH@x@AUTO_HEIGHT@
Examples:
- <http://librenms.example.com/graph.php?id=333%2C444&type=multiport_bits_separate&legend=no&absolute=1&from=-14200&width=@AUTO_WIDTH@&height=@AUTO_HEIGHT@>
- <http://example.com/myimage.php?size=@AUTO_WIDTH@x@AUTO_HEIGHT@>

View File

@ -2,9 +2,11 @@ source: Extensions/Dell-OpenManage.md
path: blob/master/doc/
# Dell OpenManage Support
-----------------------
For Dell OpenManage support you will need to install Dell OpenManage (yeah - really :)) (minimum 5.1) onto the device you want to monitor. Ensure that net-snmp is using srvadmin, you should see something similar to:
For Dell OpenManage support you will need to install Dell OpenManage
(yeah - really :)) (minimum 5.1) onto the device you want to
monitor. Ensure that net-snmp is using srvadmin, you should see
something similar to:
```bash
master agentx
@ -25,10 +27,15 @@ Ensure that srvadmin is started, this is usually done by executing:
/opt/dell/srvadmin/sbin/srvadmin-services.sh start
```
Once this has been done, add the device to LibreNMS as normal and you will start to receive Temperatures and Fanspeed data.
Once this has been done, add the device to LibreNMS as normal and you
will start to receive Temperatures and Fanspeed data.
### Windows
Download OpenManage from Dell's support page [Link](http://www.dell.com/support/contents/us/en/04/article/product-support/self-support-knowledgebase/enterprise-resource-center/systemsmanagement/OMSA) and install OpenManage on your windows server. Make sure you have SNMP setup and running on your windows server.
# Windows
Download OpenManage from Dell's support page
[Link](http://www.dell.com/support/contents/us/en/04/article/product-support/self-support-knowledgebase/enterprise-resource-center/systemsmanagement/OMSA)
and install OpenManage onyour windows server. Make sure you have SNMP
setup and running on your windows server.

View File

@ -1,28 +1,39 @@
source: Extensions/Device-Groups.md
path: blob/master/doc/
LibreNMS supports grouping your devices together in much the same way as you can configure alerts. This document will hopefully help you get started.
LibreNMS supports grouping your devices together in much the same way
as you can configure alerts. This document will hopefully help you get
started.
# Dynamic Groups
### Rule Editor
## Rule Editor
The rule is based on the MySQL structure your data is in. Such as __tablename.columnname__.
If you already know the entity you want, you can browse around inside MySQL using `show tables` and `desc <tablename>`.
If you already know the entity you want, you can browse around inside
MySQL using `show tables` and `desc <tablename>`.
As a working example and a common question, let's assume you want to group devices by hostname. If your hostname format is dcX.[devicetype].example.com. You would use the field
`devices.hostname`.
As a working example and a common question, let's assume you want to
group devices by hostname. If your hostname format is
dcX.[devicetype].example.com. You would use the field
`devices.hostname`.
If you want to group them by device type, you would add a rule for routers of `devices.hostname` endswith `rtr.example.com`.
If you want to group them by device type, you would add a rule for
routers of `devices.hostname` endswith `rtr.example.com`.
If you want to group them by DC, you could use the rule `devices.hostname` regex `dc1\..*\.example\.com` (Don't forget to escape periods in the regex)
If you want to group them by DC, you could use the rule
`devices.hostname` regex `dc1\..*\.example\.com` (Don't forget to
escape periods in the regex)
# Static Groups
You can create static groups (and convert dynamic groups to static) to put specific devices in a group.
Just select static as the type and select the devices you want in the group.
You can create static groups (and convert dynamic groups to static) to
put specific devices in a group. Just select static as the type and
select the devices you want in the group.
![Device Groups](/img/device_groups.png)
You can now select this group from the Devices -> All Devices link in the navigation at the top. You can also use the group to map alert rules to by creating an alert mapping
You can now select this group from the Devices -> All Devices link in
the navigation at the top. You can also use the group to map alert
rules to by creating an alert mapping
`Overview -> Alerts -> Rule Mapping`.

View File

@ -5,44 +5,66 @@ path: blob/master/doc/
> Status: Release Candidate
The new LibreNMS dispatcher service (`librenms-service.py`) replaces the old poller service (`poller-service.py`), improving its reliability. It's mostly a drop in replacement for the old service, but testing is recommended before switching over.
The new LibreNMS dispatcher service (`librenms-service.py`) replaces
the old poller service (`poller-service.py`), improving its
reliability. It's mostly a drop in replacement for the old service,
but testing is recommended before switching over.
If you are currently using the old poller service, it's strongly recommended that you migrate away - it has a serious defect under certain versions of mysql/mariadb, and may be inadvertently DoS'ing your devices. The new service does not have this issue,
If you are currently using the old poller service, it's strongly
recommended that you migrate away - it has a serious defect under
certain versions of mysql/mariadb, and may be inadvertently DoS'ing
your devices. The new service does not have this issue,
Make sure you uninstall the old poller service before deploying the new service.
The dispatcher does not replace the php scripts, but the cron entries running them. It attempts to do a better job than simple time based scheduling.
The dispatcher does not replace the php scripts, but the cron entries
running them. It attempts to do a better job than simple time based
scheduling.
## External Requirements
#### A recent version of Python
The LibreNMS service requires Python 3 and some features require behaviour only found in Python3.4+.
# External Requirements
#### Python modules
- PyMySQL is recommended as it requires no C compiler to install. MySQLclient can also be used, but does require compilation.
- python-dotenv .env loader
- redis-py 3.0+ and Redis 5.0+ (if using distributed polling)
## A recent version of Python
The LibreNMS service requires Python 3 and some features require
behaviour only found in Python3.4+.
## Python modules
- PyMySQL is recommended as it requires no C compiler to
install. MySQLclient can also be used, but does require compilation.
- python-dotenv .env loader
- redis-py 3.0+ and Redis 5.0+ (if using distributed polling)
These can be obtained from your OS package manager, or from PyPI with the below commands.
```bash
pip3 install -r requirements.txt
```
#### Redis (distributed polling)
If you want to use distributed polling, you'll need a Redis instance to coordinate the nodes.
It's recommended that you do not share the Redis database with any other system - by default, Redis supports up to 16 databases (numbered 0-15).
You can also use Redis on a single host if you want
## Redis (distributed polling)
It's strongly recommended that you deploy a resilient cluster of redis systems, and use redis-sentinel.
If you want to use distributed polling, you'll need a Redis instance
to coordinate the nodes. It's recommended that you do not share the
Redis database with any other system - by default, Redis supports up
to 16 databases (numbered 0-15). You can also use Redis on a single host if you want
You should not rely on the password for the security of your system. See https://redis.io/topics/security
It's strongly recommended that you deploy a resilient cluster of redis
systems, and use redis-sentinel.
You should not rely on the password for the security of your
system. See <https://redis.io/topics/security>
#### MySQL
You should already have this, but the pollers do need access to the SQL database. The LibreNMS service runs faster and more aggressively than the standard poller, so keep an eye on the number of open connections and other important health metrics.
## MySQL
## Configuration
You should already have this, but the pollers do need access to the
SQL database. The LibreNMS service runs faster and more aggressively
than the standard poller, so keep an eye on the number of open
connections and other important health metrics.
Connection settings are required in `.env`. The `.env` file is generated after composer install and APP_KEY and NODE_ID are set.
# Configuration
Connection settings are required in `.env`. The `.env` file is
generated after composer install and APP_KEY and NODE_ID are set.
```dotenv
#APP_KEY= #Required, generated by composer install
@ -54,7 +76,7 @@ DB_USERNAME=librenms
DB_PASSWORD=
```
### Distributed Polling Configuration
## Distributed Polling Configuration
Once you have your Redis database set up, configure it in the .env file on each node.
@ -65,11 +87,13 @@ REDIS_HOST=127.0.0.1
#REDIS_PORT=6379
```
### Basic Configuration
## Basic Configuration
Additional configuration settings can be set in `config.php` or directly into the database.
Additional configuration settings can be set in `config.php` or
directly into the database.
The defaults are shown here - it's recommended that you at least tune the number of workers.
The defaults are shown here - it's recommended that you at least tune
the number of workers.
```php
$config['service_poller_workers'] = 24; # Processes spawned for polling
@ -78,20 +102,23 @@ $config['service_discovery_workers'] = 16; # Processes spawned for
//Optional Settings
$config['service_poller_frequency'] = 300; # Seconds between polling attempts
$config['service_poller_frequency'] = 300; # Seconds between polling attempts
$config['service_services_frequency'] = 300; # Seconds between service polling attempts
$config['service_discovery_frequency'] = 21600; # Seconds between discovery runs
$config['service_discovery_frequency'] = 21600; # Seconds between discovery runs
$config['service_billing_frequency'] = 300; # Seconds between billing calculations
$config['service_billing_calculate_frequency'] = 60; # Billing interval
$config['service_billing_calculate_frequency'] = 60; # Billing interval
$config['service_poller_down_retry'] = 60; # Seconds between failed polling attempts
$config['service_loglevel'] = 'INFO'; # Must be one of 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
$config['service_update_frequency'] = 86400; # Seconds between LibreNMS update checks
$config['service_update_frequency'] = 86400; # Seconds between LibreNMS update checks
```
There are also some SQL options, but these should be inherited from your LibreNMS web UI configuration.
Logs are sent to the system logging service (usually `journald` or `rsyslog`) - see https://docs.python.org/3/library/logging.html#logging-levels for the options available.
There are also some SQL options, but these should be inherited from
your LibreNMS web UI configuration.
Logs are sent to the system logging service (usually `journald` or
`rsyslog`) - see
<https://docs.python.org/3/library/logging.html#logging-levels> for the
options available.
```php
distributed_poller = true; # Set to true to enable distributed polling
@ -99,34 +126,50 @@ distributed_poller_name = null; # Uniquely identifies th
distributed_poller_group = 0; # Which group to poll
```
## Fast Ping
The [fast ping](Fast-Ping-Check.md) scheduler is disabled by default. You can enable it by setting the following:
# Fast Ping
The [fast ping](Fast-Ping-Check.md) scheduler is disabled by default.
You can enable it by setting the following:
```php
$config['service_ping_enabled'] = true;
```
## Cron Scripts
Once the LibreNMS service is installed, the cron scripts used by LibreNMS are no longer required and must be removed.
# Cron Scripts
## Service Installation
A systemd unit file is provided - the sysv and upstart init scripts could also be used with a little modification.
Once the LibreNMS service is installed, the cron scripts used by
LibreNMS are no longer required and must be removed.
### systemd
A systemd unit file can be found in `misc/librenms.service`. To install run `cp /opt/librenms/misc/librenms.service /etc/systemd/system/librenms.service && systemctl enable --now librenms.service`
# Service Installation
A systemd unit file is provided - the sysv and upstart init scripts
could also be used with a little modification.
## systemd
A systemd unit file can be found in `misc/librenms.service`. To
install run `cp /opt/librenms/misc/librenms.service
/etc/systemd/system/librenms.service && systemctl enable --now
librenms.service`
## OS-Specific Instructions
### RHEL/CentOS
To get the LibreNMS service running under python3.4+ on RHEL-derivatives with minimal fuss, you can use the software collections build:
To get the LibreNMS service running under python3.4+ on
RHEL-derivatives with minimal fuss, you can use the software
collections build:
First, enable SCL's on your system:
#### CentOS 7
```
# yum install centos-release-scl
```
#### RHEL 7
```
# subscription-manager repos --enable rhel-server-rhscl-7-rpms
```
@ -145,13 +188,18 @@ Then install and configure the runtime and service:
# systemctl enable --now librenms.service
```
If you want to use another version of python 3, change `rh-python36` in the unit file and the commands above to match the name of the replacement scl.
If you want to use another version of python 3, change `rh-python36`
in the unit file and the commands above to match the name of the
replacement scl.
### Debian/Ubuntu
#### Debian 9 (stretch)
install python3 and python-mysqldb. python-dotenv is not yes available, but the testing package is working fine, you can grab it on https://packages.debian.org/fr/buster/all/python3-dotenv/download (the package may be updated and have a new version number).
install python3 and python-mysqldb. python-dotenv is not yes
available, but the testing package is working fine, you can grab it on
<https://packages.debian.org/fr/buster/all/python3-dotenv/download> (the
package may be updated and have a new version number).
```
apt install python3 python-mysqldb

View File

@ -1,89 +1,164 @@
source: Extensions/Distributed-Poller.md
path: blob/master/doc/
# Distributed Poller
LibreNMS has the ability to distribute polling of devices to other machines.
These machines can be in a different physical location and therefore minimize network latency for devices that are a considerable
distance away or are behind NAT firewalls.
These machines can be in a different physical location and therefore
minimize network latency for devices that are a considerable distance
away or are behind NAT firewalls.
Devices can be grouped together into a `poller_group` to pin these devices to a single or a group of designated pollers.
Devices can be grouped together into a `poller_group` to pin these
devices to a single or a group of designated pollers.
> All pollers need to share their RRD-folder, for example via NFS or a combination of NFS and rrdcached.
All pollers need to share their RRD-folder, for example via NFS or a
combination of NFS and rrdcached.
It is a requirement that all pollers can access the central memcached to communicate with each other.
It is a requirement that all pollers can access the central memcached
to communicate with each other.
### Requirements
# Requirements
> These requirements are above the normal requirements for a full LibreNMS install.
These requirements are above the normal requirements for a full LibreNMS install.
- rrdtool version 1.4 or above
- python-memcached package
- a memcached install
- a rrdcached install
- rrdtool version 1.4 or above
- python-memcached package
- a memcached install
- a rrdcached install
By default, all hosts are shared and have the `poller_group = 0`. To pin a device to a poller, set it to a value greater than 0 and set the same value in the poller's config with `$config['distributed_poller_group']`. One can also specify a comma separated string of poller groups in $config['distributed_poller_group']. The poller will then poll devices from any of the groups listed. If new devices get added from the poller they will be assigned to the first poller group in the list unless the group is specified when adding the device.
By default, all hosts are shared and have the `poller_group = 0`. To
pin a device to a poller, set it to a value greater than 0 and set the
same value in the poller's config with
`$config['distributed_poller_group']`. One can also specify a comma
separated string of poller groups in
$config['distributed_poller_group']. The poller will then poll
devices from any of the groups listed. If new devices get added from
the poller they will be assigned to the first poller group in the list
unless the group is specified when adding the device.
A standard configuration for a distributed poller would look like:
```php
// Distributed Poller-Settings
$config['distributed_poller'] = true;
#$config['distributed_poller_name'] = 'custom'; // optional: defaults to hostname
// optional: defaults to hostname
#$config['distributed_poller_name'] = 'custom';
$config['distributed_poller_group'] = 0;
$config['distributed_poller_memcached_host'] = 'example.net';
$config['distributed_poller_memcached_port'] = '11211';
```
## Example Setup
Below is an example setup based on a real deployment which at the time of writing covers over 2,500 devices and 50,000 ports. The setup is running within an OpenStack environment with some commodity hardware for remote pollers. Here's a diagram of how you can scale LibreNMS out:
Below is an example setup based on a real deployment which at the time
of writing covers over 2,500 devices and 50,000 ports. The setup is
running within an OpenStack environment with some commodity hardware
for remote pollers. Here's a diagram of how you can scale LibreNMS
out:
![Example Setup](http://docs.librenms.org/img/librenms-distributed-diagram.png)
### Architecture
How you setup the distribution is entirely up to you, you can choose to host the majority of the required services on a single virtual machine or server and then a poller to actually query the devices being monitored all the way through to having a dedicated server for each of the individual roles. Below are notes on what you need to consider both from the software layer but also connectivity.
## Architecture
#### Web / API Layer
This is typically Apache but we have setup guides for both Nginx and Lighttpd which should work perfectly fine. There is nothing unique about the role this service is providing except that if you are adding devices from this layer then the web service will need to be able to connect to the end device via SNMP and perform an ICMP test.
How you setup the distribution is entirely up to you, you can choose
to host the majority of the required services on a single virtual
machine or server and then a poller to actually query the devices
being monitored all the way through to having a dedicated server for
each of the individual roles. Below are notes on what you need to
consider both from the software layer but also connectivity.
It is advisable to run RRDCached within this setup so that you don't need to share the rrd folder via a remote file share such as NFS. The web service can then generate rrd graphs via RRDCached. If RRDCached isn't an option then you can mount the rrd directory to read the RRD files directly.
### Web / API Layer
#### Database Server
MySQL / MariaDB - At the moment these are the only database servers that are supported, work is being done to ensure MySQL Strict mode is also supported but this should be considered to be incomplete still and therefor disabled.
This is typically Apache but we have setup guides for both Nginx and
Lighttpd which should work perfectly fine. There is nothing unique
about the role this service is providing except that if you are adding
devices from this layer then the web service will need to be able to
connect to the end device via SNMP and perform an ICMP test.
The pollers, web and API layers should all be able to access the database server directly.
It is advisable to run RRDCached within this setup so that you don't
need to share the rrd folder via a remote file share such as NFS. The
web service can then generate rrd graphs via RRDCached. If RRDCached
isn't an option then you can mount the rrd directory to read the RRD
files directly.
#### RRD Storage
Central storage should be provided so all RRD files can be read from and written to in one location. As suggested above, it's recommended that RRD Cached is configured and used.
### Database Server
For this example, we are running RRDCached to allow all pollers and web/api servers to read/write to the rrd files with the rrd directory also exported by NFS for simple access and maintenance.
MySQL / MariaDB - At the moment these are the only database servers
that are supported, work is being done to ensure MySQL Strict mode is
also supported but this should be considered to be incomplete still
and therefor disabled.
#### Memcache
Memcache is required for the distributed pollers to be able to register to a central location and record what devices are polled. Memcache can run from any of the servers so long as it is accessible by all pollers.
The pollers, web and API layers should all be able to access the
database server directly.
### RRD Storage
Central storage should be provided so all RRD files can be read from
and written to in one location. As suggested above, it's recommended
that RRD Cached is configured and used.
For this example, we are running RRDCached to allow all pollers and
web/api servers to read/write to the rrd files with the rrd directory
also exported by NFS for simple access and maintenance.
### Memcache
Memcache is required for the distributed pollers to be able to
register to a central location and record what devices are
polled. Memcache can run from any of the servers so long as it is
accessible by all pollers.
### Pollers
#### Pollers
Pollers can be installed and run from anywhere, the only requirements are:
They can access the Memcache instance
They can create RRD files via some method such as a shared filesystem or RRDTool >=1.5.5
They can access the MySQL server
- They can access the Memcache instance
- They can create RRD files via some method such as a shared
filesystem or RRDTool >=1.5.5
- They can access the MySQL server
You can either assign pollers into groups and set a poller group against certain devices, this will mean that those devices will only be processed by certain pollers (default poller group is 0) or you can assign all pollers to the default poller group for them to process any and all devices.
You can either assign pollers into groups and set a poller group
against certain devices, this will mean that those devices will only
be processed by certain pollers (default poller group is 0) or you can
assign all pollers to the default poller group for them to process any
and all devices.
This will provide the ability to have a single poller behind a NAT firewall monitor internal devices and report back to your central system. You will then be able to monitor those devices from the Web UI as normal.
This will provide the ability to have a single poller behind a NAT
firewall monitor internal devices and report back to your central
system. You will then be able to monitor those devices from the Web UI
as normal.
Another benefit to this is that you can provide N+x pollers, i.e if you know that you require three pollers to process all devices within 300 seconds then adding a 4th poller will mean that should any one single poller fail then the remaining three will complete polling in time. You could also use this to take a poller out of service for maintenance, i.e OS updates and software updates.
Another benefit to this is that you can provide N+x pollers, i.e if
you know that you require three pollers to process all devices within
300 seconds then adding a 4th poller will mean that should any one
single poller fail then the remaining three will complete polling in
time. You could also use this to take a poller out of service for
maintenance, i.e OS updates and software updates.
It is extremely advisable to either run a central recursive dns server such as pdns-recursor and have all of your pollers use this or install a recursive dns server on each poller - the volume of DNS requests on large installs can be significant and will slow polling down enough to cause issues with a large number of devices.
It is extremely advisable to either run a central recursive dns server
such as pdns-recursor and have all of your pollers use this or install
a recursive dns server on each poller - the volume of DNS requests on
large installs can be significant and will slow polling down enough to
cause issues with a large number of devices.
#### Discovery
It's not necessary to run discovery services on all pollers. In fact, you should only run one discovery process per poller group. Designate a single poller to run discovery (or a separate server if required).
### Discovery
#### Config sample
The following config is taken from a live setup which consists of a Web server, DB server, RRDCached server and 3 pollers.
It's not necessary to run discovery services on all pollers. In fact,
you should only run one discovery process per poller group. Designate
a single poller to run discovery (or a separate server if required).
### Config sample
The following config is taken from a live setup which consists of a
Web server, DB server, RRDCached server and 3 pollers.
Web Server:
Running Apache and an install of LibreNMS in /opt/librenms
- config.php
- config.php
```php
$config['distributed_poller'] = true;
$config['rrdcached'] = "example.com:42217";
@ -91,9 +166,11 @@ $config['rrdcached'] = "example.com:42217";
Database Server:
Running Memcache and MariaDB
- Memcache
- Memcache
Ubuntu (/etc/memcached.conf)
```conf
-d
-m 64
@ -104,16 +181,20 @@ Ubuntu (/etc/memcached.conf)
RRDCached Server:
Running RRDCached
- RRDCached
- RRDCached
Ubuntu (/etc/default/rrdcached)
```conf
OPTS="-l 0:42217"
OPTS="$OPTS -j /var/lib/rrdcached/journal/ -F"
OPTS="$OPTS -b /opt/librenms/rrd -B"
OPTS="$OPTS -w 1800 -z 900"
```
Ubuntu (/etc/default/rrdcached) - RRDCached 1.5.5 and above.
```
OPTS="-l 0:42217"
OPTS="$OPTS -R -j /var/lib/rrdcached/journal/ -F"
@ -125,6 +206,7 @@ Poller 1:
Running an install of LibreNMS in /opt/librenms
`config.php`
```php
$config['distributed_poller_name'] = php_uname('n');
$config['distributed_poller_group'] = '0';
@ -136,7 +218,10 @@ $config['update'] = 0;
```
`/etc/cron.d/librenms`
Runs discovery and polling for group 0, daily.sh to deal with notifications and DB cleanup and alerts.
Runs discovery and polling for group 0, daily.sh to deal with
notifications and DB cleanup and alerts.
```conf
33 */6 * * * librenms /opt/librenms/cronic /opt/librenms/discovery-wrapper.py 1
*/5 * * * * librenms /opt/librenms/discovery.php -h new >> /dev/null 2>&1
@ -149,6 +234,7 @@ Poller 2:
Running an install of LibreNMS in /opt/librenms
`config.php`
```php
$config['distributed_poller_name'] = php_uname('n');
$config['distributed_poller_group'] = '0';
@ -160,7 +246,9 @@ $config['update'] = 0;
```
`/etc/cron.d/librenms`
Runs billing as well as polling for group 0.
```conf
*/5 * * * * librenms /opt/librenms/poller-wrapper.py 16 >> /opt/librenms/logs/wrapper.log
*/5 * * * * librenms /opt/librenms/poll-billing.php >> /dev/null 2>&1
@ -172,6 +260,7 @@ Poller 3:
Running an install of LibreNMS in /opt/librenms
`config.php`
```php
$config['distributed_poller_name'] = php_uname('n');
$config['distributed_poller_group'] = '2,3';
@ -184,10 +273,10 @@ $config['update'] = 0;
`/etc/cron.d/librenms`
Runs discovery and polling for groups 2 and 3.
```conf
33 */6 * * * librenms /opt/librenms/cronic /opt/librenms/discovery-wrapper.py 1
*/5 * * * * librenms /opt/librenms/discovery.php -h new >> /dev/null 2>&1
*/5 * * * * librenms /opt/librenms/cronic /opt/librenms/poller-wrapper.py 16
15 0 * * * librenms /opt/librenms/daily.sh >> /dev/null 2>&1
```

View File

@ -1,58 +1,70 @@
source: Extensions/Fast-Ping-Check.md
path: blob/master/doc/
## Fast up/down checking
# Fast up/down checking
Normally, LibreNMS sends an ICMP ping to the device before polling to check if it is up or down.
This check is tied to the poller frequency, which is normally 5 minutes. This means it may take up to 5 minutes
Normally, LibreNMS sends an ICMP ping to the device before polling to
check if it is up or down. This check is tied to the poller frequency,
which is normally 5 minutes. This means it may take up to 5 minutes
to find out if a device is down.
Some users may want to know if devices stop responding to ping more quickly than that. LibreNMS offers a ping.php script
to run ping checks as quickly as possible without increasing snmp load on your devices by switching to 1 minute polling.
Some users may want to know if devices stop responding to ping more
quickly than that. LibreNMS offers a ping.php script to run ping
checks as quickly as possible without increasing snmp load on your
devices by switching to 1 minute polling.
> **WARNING**: If you do not have an alert rule that alerts on device status, enabling this will be a waste of resources.
> You can find one in the [Alert Rules Collection](../Alerting/Rules.md#alert-rules-collection).
**WARNING**: If you do not have an alert rule that alerts on device
status, enabling this will be a waste of resources. You can find one
in the [Alert Rules
Collection](../Alerting/Rules.md#alert-rules-collection).
## Setting the ping check to 1 minute
### Setting the ping check to 1 minute
1: Change the ping_rrd_step setting in config.php
1. Change the ping_rrd_step setting in config.php
```
$config['ping_rrd_step'] = 60;
```
```
$config['ping_rrd_step'] = 60;
```
2. Update the rrd files to change the step (step is hardcoded at file creation in rrd files)
```
./scripts/rrdstep.php -h all
```
2: Update the rrd files to change the step (step is hardcoded at file
creation in rrd files)
3. Add the following line to /etc/cron.d/librenms to allow 1 minute ping checks
```
./scripts/rrdstep.php -h all
```
3: Add the following line to /etc/cron.d/librenms to allow 1 minute
ping checks
```
* * * * * librenms /opt/librenms/ping.php >> /dev/null 2>&1
```
> **NOTE**: If you are using distributed pollers you can restrict a poller to a group by appending `-g` to the cron entry. Alternatively, you should only run ping.php on a single node.
**NOTE**: If you are using distributed pollers you can restrict a
poller to a group by appending `-g` to the cron entry. Alternatively,
you should only run ping.php on a single node.
#### Sub minute ping check
## Sub minute ping check
Cron only has a resolution of one minute, so we have to use a trick to allow sub minute checks.
We add two entries, but add a delay before one.
Cron only has a resolution of one minute, so we have to use a trick to
allow sub minute checks. We add two entries, but add a delay before one.
>Alerts are only run every minute, so you will have to modify them as well. Remove the original alerts.php entry.
Alerts are only run every minute, so you will have to modify them as
well. Remove the original alerts.php entry.
1. Set ping_rrd_step
```
$config['ping_rrd_step'] = 30;
```
2. Update the rrd files
```
./scripts/rrdstep.php -h all
```
1: Set ping_rrd_step
3. Update cron (removing any other ping.php or alert.php entries)
```
$config['ping_rrd_step'] = 30;
```
2: Update the rrd files
```
./scripts/rrdstep.php -h all
```
3: Update cron (removing any other ping.php or alert.php entries)
```
* * * * * librenms /opt/librenms/ping.php >> /dev/null 2>&1
@ -61,16 +73,19 @@ We add two entries, but add a delay before one.
* * * * * librenms sleep 45 && /opt/librenms/alerts.php >> /dev/null 2>&1
```
### Device dependencies
# Device dependencies
The ping.php script respects device dependencies, but the main poller does not (for technical reasons).
However, using this script does not disable the icmp check in the poller and a child may be reported as
The ping.php script respects device dependencies, but the main poller
does not (for technical reasons). However, using this script does not
disable the icmp check in the poller and a child may be reported as
down before the parent.
### Settings
# Settings
ping.php uses much the same settings as the poller fping with one exception: retries is used instead of count.
ping.php does not measure loss and avg response time, only up/down, so once a device responds it stops pinging it.
ping.php uses much the same settings as the poller fping with one
exception: retries is used instead of count.
ping.php does not measure loss and avg response time, only up/down, so
once a device responds it stops pinging it.
```
$config['fping_options']['retries'] = 2;

View File

@ -1,21 +1,30 @@
source: Extensions/Gateone.md
path: blob/master/doc/
# GateOne integration
We have simple integration for [GateOne](https://github.com/liftoff/GateOne), you will be redirected to your Gateone command line frontend to access your equipment. (Currently this only works with SSH)
We have simple integration for
[GateOne](https://github.com/liftoff/GateOne), you will be redirected
to your Gateone command line frontend to access your
equipment. (Currently this only works with SSH)
GateOne itself isn't included within LibreNMS, you will need to install this separately either on the same infrastructure as LibreNMS or as a totally
standalone appliance. The installation is beyond the scope of this document.
GateOne itself isn't included within LibreNMS, you will need to
install this separately either on the same infrastructure as LibreNMS
or as a totally standalone appliance. The installation is beyond the
scope of this document.
Config is simple, include the following in your `config.php`:
```php
$config['gateone']['server'] = 'http://<your_gateone_url/';
```
**Note:** You *must* use the full url including the trailing `/`!
We also support prefixing the currently logged in Librenms user to the SSH connection URL that is created, eg. `ssh://admin@localhost`\
To enable this, put the following in your `config.php`:
We also support prefixing the currently logged in Librenms user to the
SSH connection URL that is created, eg. `ssh://admin@localhost`\ To
enable this, put the following in your `config.php`:
```php
$config['gateone']['use_librenms_user'] = true;
```

View File

@ -1,19 +1,29 @@
source: Extensions/Graylog.md
path: blob/master/doc/
# Graylog integration
We have simple integration for Graylog, you will be able to view any logs from within LibreNMS that have been parsed by the syslog input from within
Graylog itself. This includes logs from devices which aren't in LibreNMS still, you can also see logs for a specific device under the logs section
for the device.
We have simple integration for Graylog, you will be able to view any
logs from within LibreNMS that have been parsed by the syslog input
from within Graylog itself. This includes logs from devices which
aren't in LibreNMS still, you can also see logs for a specific device
under the logs section for the device.
Currently, LibreNMS does not associate shortnames from Graylog with full FQDNS. If you have your devices in LibreNMS using full FQDNs, such as hostname.example.com, be aware that rsyslogd, by default, sends the shortname only. To fix this, add
Currently, LibreNMS does not associate shortnames from Graylog with
full FQDNS. If you have your devices in LibreNMS using full FQDNs,
such as hostname.example.com, be aware that rsyslogd, by default,
sends the shortname only. To fix this, add
`$PreserveFQDN on`
to your rsyslog config to send the full FQDN so device logs will be associated correctly in LibreNMS. Also see near the bottom of this document for tips on how to enable/suppress the domain part of hostnames in syslog-messages for some platforms.
to your rsyslog config to send the full FQDN so device logs will be
associated correctly in LibreNMS. Also see near the bottom of this
document for tips on how to enable/suppress the domain part of
hostnames in syslog-messages for some platforms.
Graylog itself isn't included within LibreNMS, you will need to install this separately either on the same infrastructure as LibreNMS or as a totally
standalone appliance.
Graylog itself isn't included within LibreNMS, you will need to
install this separately either on the same infrastructure as LibreNMS
or as a totally standalone appliance.
Config is simple, here's an example based on Graylog 2.4:
@ -25,56 +35,83 @@ $config['graylog']['password'] = 'admin';
$config['graylog']['version'] = '2.4';
```
Graylog messages are stored using GMT timezone. You can display graylog messages in LibreNMS webui using your desired timezone by setting following option in config.php:
Graylog messages are stored using GMT timezone. You can display
graylog messages in LibreNMS webui using your desired timezone by
setting following option in config.php:
```php
$config['graylog']['timezone'] = 'Europe/Bucharest';
```
> Timezone must be PHP supported timezones, available at: <a href="http://php.net/manual/en/timezones.php">http://php.net/manual/en/timezones.php</a>
If you are running a version earlier than Graylog then please set `$config['graylog']['version']` to the version
number of your Graylog install. Earlier versions than 2.1 use the default port `12900`
Timezone must be PHP supported timezones, available at:
<http://php.net/manual/en/timezones.php>
If you have altered the default uri for your Graylog setup then you can override the default of `/api/` using
`$config['graylog']['base_uri'] = '/somepath/';`
If you are running a version earlier than Graylog then please set
`$config['graylog']['version']` to the version number of your Graylog
install. Earlier versions than 2.1 use the default port `12900`
If you choose to use another user besides the admin user, please note that currently you must give the user "admin" permissions from within Graylog, "read" permissions alone are not sufficient.
If you have altered the default uri for your Graylog setup then you
can override the default of `/api/` using `$config['graylog']['base_uri'] = '/somepath/';`
If you have enabled TLS for the Graylog API and you are using a self-signed certificate, please make sure that the certificate is trusted by your LibreNMS host, otherwise the connection will fail.
Additionally, the certificate's Common Name (CN) has to match the FQDN or IP address specified in `$config['graylog']['server']`.
If you choose to use another user besides the admin user, please note
that currently you must give the user "admin" permissions from within
Graylog, "read" permissions alone are not sufficient.
If you want to match the source address of the log entries against any IP address of a device instead of only against
the primary address and the host name to assign the log entries to a device, you can activate this function using
$config['graylog']['match-any-address'] = 'true';
If you have enabled TLS for the Graylog API and you are using a
self-signed certificate, please make sure that the certificate is
trusted by your LibreNMS host, otherwise the connection will
fail. Additionally, the certificate's Common Name (CN) has to match
the FQDN or IP address specified in `$config['graylog']['server']`.
There are 2 configuration parameters to influence the behaviour of the "Recent Graylog" table on the overview page of the devices.
$config['graylog']['device-page']['rowCount'] sets the maximum number of rows to be displayed (default: 10)
With $config['graylog']['device-page']['loglevel'] you can set which loglevels should be displayed on the overview page. (default: 7, min: 0, max: 7)
$config['graylog']['device-page']['loglevel'] = 4 shows only entries with a log level less than or equal to 4 (Emergency, Alert, Critical, Error, Warning).
If you want to match the source address of the log entries against any
IP address of a device instead of only against the primary address and
the host name to assign the log entries to a device, you can activate
this function using $config['graylog']['match-any-address'] = 'true';
You can set a default Log Level Filter with $config['graylog']['loglevel'] (applies to /graylog and /device/device=/tab=logs/section=graylog/ (min: 0, max: 7)
There are 2 configuration parameters to influence the behaviour of the
"Recent Graylog" table on the overview page of the
devices. $config['graylog']['device-page']['rowCount'] sets the
maximum number of rows to be displayed (default: 10) With
$config['graylog']['device-page']['loglevel'] you can set which
loglevels should be displayed on the overview page. (default: 7, min:
0, max: 7) $config['graylog']['device-page']['loglevel'] = 4 shows
only entries with a log level less than or equal to 4 (Emergency,
Alert, Critical, Error, Warning).
## Suppressing/enabling the domain part of a hostname for specific platforms
You should see if what you get in syslog/Graylog matches up with your configured hosts first. If you need to modify the syslog messages from specific platforms, this may be of assistance:
You can set a default Log Level Filter with
$config['graylog']['loglevel'] (applies to /graylog and
/device/device=/tab=logs/section=graylog/ (min: 0, max: 7)
# Suppressing/enabling the domain part of a hostname for specific platforms
You should see if what you get in syslog/Graylog matches up with your
configured hosts first. If you need to modify the syslog messages from
specific platforms, this may be of assistance:
## IOS (Cisco)
### IOS (Cisco)
```
router(config)# logging origin-id hostname
```
or
```
router(config)# logging origin-id string
```
### JunOS (Juniper Networks)
## JunOS (Juniper Networks)
```
set system syslog host yourlogserver.corp log-prefix YOUR_PREFERRED_STRING
```
### PanOS (Palo Alto Networks)
## PanOS (Palo Alto Networks)
```
set deviceconfig setting management hostname-type-in-syslog hostname
```
or
```

View File

@ -1,20 +1,25 @@
source: Extensions/IRC-Bot-Extensions.md
path: blob/master/doc/
# Quick Guide
Okay this is a very quick walk-through in writing own `commands` for the IRC-Bot.
First of all, create a file in `includes/ircbot`, the file-name should be in this format: `command.inc.php`.
First of all, create a file in `includes/ircbot`, the file-name should
be in this format: `command.inc.php`.
When editing the file, do not open nor close PHP-tags.
Any variable you assign will be discarded as soon as your command returns.
Some variables, specially all listed under `$this->`, have special meanings or effects.
Before a command is executed, the IRC-Bot ensures that the MySQL-Socket is working, that `$this->user` points to the right user and that the user is authenticated.
Before a command is executed, the IRC-Bot ensures that the
MySQL-Socket is working, that `$this->user` points to the right user
and that the user is authenticated.
Below you will find a table with related functions and attributes.
You can chain-load any built-in command by calling `$this->_command("My Parameters")`.
You cannot chain-load external commands.
To enable your command, edit your `config.php` and add something like this:
```php
...
$config['irc_external'][] = "mycommand";
@ -24,9 +29,10 @@ To enable your command, edit your `config.php` and add something like this:
See: [Example](#example)
# Functions and Attributes
... that are accessible from within an extension
### <a name="glob.func">Functions</a>
## Functions
Function( (Type) $Variable [= Default] [,...] ) | Returns | Description
--- | --- | ---
@ -41,7 +47,8 @@ Function( (Type) $Variable [= Default] [,...] ) | Returns | Description
`$this->read( (string) $Buffer )` | `String/Boolean` | Returns a `line` from given `$Buffer` or `false` if there's nothing suitable inside the Buffer. Please use `$this->getData()` for handler-safe data retrieval.
`$this->respond( (string) $Message )` | `Boolean` | Responds to the `request` auto-detecting channel or private message.
### <a name="glob.attr">Attributes</a>
## Attributes
Attribute | Type | Description
--- | --- | ---
`$params` | `String` | Contains all arguments that are passed to the `.command`.
@ -59,9 +66,10 @@ Attribute | Type | Description
`$this->tick` | `Int` | Interval to check buffers in microseconds.
`$this->user` | `Array` | Array containing details about the `user` that sent the `request`.
# <a name="example">Example!</a>
# Example
`includes/ircbot/join-ng.inc.php`
```php
if( $this->user['level'] != 10 ) {
return $this->respond("Sorry only admins can make me join.");
@ -75,6 +83,7 @@ Attribute | Type | Description
```
`config.php`
```php
...
$config['irc_external'][] = "join-ng";

View File

@ -4,16 +4,22 @@ path: blob/master/doc/
# About
LibreNMS has an easy to use IRC-Interface for basic tasks like viewing last log-entry, current device/port status and such.
LibreNMS has an easy to use IRC-Interface for basic tasks like viewing
last log-entry, current device/port status and such.
By default the IRC-Bot will not start when executed and will return an error until at least `$config['irc_host']` and `$config['irc_port']` has been specified inside `config.php`. (To start the IRC-Bot run ./irc.php )
By default the IRC-Bot will not start when executed and will return an
error until at least `$config['irc_host']` and `$config['irc_port']`
has been specified inside `config.php`. (To start the IRC-Bot run
./irc.php )
If no channel has been specified with `$config['irc_chan']`, `##librenms` will be used.
The default Nick for the bot is `LibreNMS`.
If no channel has been specified with `$config['irc_chan']`,
`##librenms` will be used. The default Nick for the bot is `LibreNMS`.
The Bot will reply the same way it's being called. If you send it the commands via Query, it will respond in the Query. If you send the commands via a Channel, then it will respond in the Channel.
The Bot will reply the same way it's being called. If you send it the
commands via Query, it will respond in the Query. If you send the
commands via a Channel, then it will respond in the Channel.
### Configuration & Defaults
## Configuration & Defaults
Option | Default-Value | Notes
--- | --- | ---
@ -30,9 +36,9 @@ Option | Default-Value | Notes
`$config['irc_nick']` | `LibreNMS` | Optional;
`$config['irc_pass']` | | Optional; This sends the IRC-PASS Sequence to IRC-Servers that require Password on Connect
`$config['irc_port']` | `6667` | Required; To enable SSL append a `+` before the Port. (Example: `+6697`)
`$config['irc_ctcp']` | `false` | Optional; Enable/disable ctcp-replies from the bot (currently VERSION, PING and TIME).
`$config['irc_ctcp']` | `false` | Optional; Enable/disable ctcp-replies from the bot (currently VERSION, PING and TIME).
`$config['irc_ctcp_version']` | `LibreNMS IRCbot. https://www.librenms.org/` | Optional: Reply-string to CTCP VERSION requests
`$config['irc_auth']` | | Optional: Array of hostmasks that are automatically authenticated.
`$config['irc_auth']` | | Optional: Array of hostmasks that are automatically authenticated.
### IRC-Commands
@ -55,7 +61,7 @@ Command | Description
# Examples
### Server examples:
## Server examples:
Unencrypted Connection to `irc.freenode.org`:
@ -85,9 +91,10 @@ SSL-Encrypted Connection to `irc.localdomain` with Server-Password and odd port:
...
```
### Channel notations:
## Channel notations:
Channels can be defined using Array-Notation like:
```php
...
$config['irc_chan'][] = "#librenms";
@ -95,13 +102,17 @@ Channels can be defined using Array-Notation like:
$config['irc_chan'][] = "#noc";
...
```
Or using a single string using `,` as delimiter between various channels:
```php
...
$config['irc_chan'] = "#librenms,#otherchan,#noc";
...
```
### Hostmask authentication:
## Hostmask authentication:
```php
...
$config['irc_auth']['admin'][] = "*!root@nms.host.invalid";
@ -109,28 +120,38 @@ Or using a single string using `,` as delimiter between various channels:
$config['irc_auth']['john][] = "john!doe@login.server.invalid";
...
```
Any client matching one of the first two hostmasks will automatically be authenticated as the "admin" user in LibreNMS, and clients matching the last line will be authenticated as the user "john" in LibreNMS, without using .auth and a waiting for a valid token.
Any client matching one of the first two hostmasks will automatically
be authenticated as the "admin" user in LibreNMS, and clients matching
the last line will be authenticated as the user "john" in LibreNMS,
without using .auth and a waiting for a valid token.
# Extensions?!
The bot is coded in a unified way.
This makes writing extensions by far less painful.
Simply add your `command` to the `$config['irc_external']` directive and create a file called `includes/ircbot/command.inc.php` containing your code.
The string behind the call of `.command` is passed as `$params`.
Simply add your `command` to the `$config['irc_external']` directive
and create a file called `includes/ircbot/command.inc.php` containing
your code. The string behind the call of `.command` is passed as `$params`.
The user who requested something is accessible via `$this->user`.
Send your reply/ies via `$this->respond($string)`.
A more detailed documentation of the functions and variables available for extensions can be found at [IRC-Bot Extensions](IRC-Bot-Extensions);
A more detailed documentation of the functions and variables available
for extensions can be found at [IRC-Bot
Extensions](IRC-Bot-Extensions);
Confused? Here an Echo-Example:
File: config.php
```php
...
$config['irc_external'][] = "echo";
...
```
File: includes/ircbot/echo.inc.php
```php
//Prefix everything with `You said: '...'` and return what was sent.
if( $this->user['name'] != "root" ) {
@ -142,18 +163,21 @@ File: includes/ircbot/echo.inc.php
# Systemd start up script
Basic systemd start up script to be placed in /etc/systemd/system/ to start irc service at boot.
Basic systemd start up script to be placed in /etc/systemd/system/ to
start irc service at boot.
librenms-irc.service script is located at /opt/librenms/misc/
Once copied to /etc/systemd/system/ you must run the following commands:
a) chmod 664 /etc/systemd/system/librenms-irc.service
b) systemctl daemon-reload
c) systemctl enable librenms-irc.service
d) systemctl start librenms-irc.service
It can be stopped or started just like any other systemd script such as systemctl start librenms-irc.service
It can be stopped or started just like any other systemd script such
as systemctl start librenms-irc.service

View File

@ -1,27 +1,30 @@
source: Extensions/Interface-Description-Parsing.md
path: blob/master/doc/
## About
Librenms can interpret, display and group certain additional information on ports.
This is done based on the format that the port description is written although it's possible
to customise the parser to be specific for your setup.
## Keywords
# About
Librenms can interpret, display and group certain additional information on ports.
This is done based on the format that the port description is written
although it's possible to customise the parser to be specific for your setup.
# Keywords
See [examples](#examples) for formats.
- **Keywords**
- `Cust` - Customer
- `Transit` - Transit link
- `Peering` - Peering link
- `Core` - Infrastructure link (non-customer)
- Info-keywords
- `()` contains a note
- `{}` contains *your* circuit id
- `[]` contains the service type or speed
- **Keywords**
- `Cust` - Customer
- `Transit` - Transit link
- `Peering` - Peering link
- `Core` - Infrastructure link (non-customer)
- Info-keywords
- `()` contains a note
- `{}` contains *your* circuit id
- `[]` contains the service type or speed
## Examples
# Examples
Cisco IOS / NXOS / IOSXR:
```text
interface Gi0/1
descr Transit: Example Provider (AS65000)
@ -34,7 +37,9 @@ descr Cust: Example Customer [10Mbit] (T1 Telco Y CCID129031) {EXAMP0001}
```
Unix / Linux:
> This requires an additional script to be [setup](#setup)
This requires an additional script to be [setup](#setup)
```text
# eth3: Cust: Example Customer [10Mbit] (T1 Telco Y CCID129031) {EXAMP0001}
# eth0: Transit: Example Provider (AS65000)
@ -42,9 +47,10 @@ Unix / Linux:
# eth2: Peering: Peering Exchange
```
## Customisation
# Customisation
The following config options can be set to enable more custom types:
```php
$config['customers_descr'][] = 'cust';
$config['transit_descr'][] = "transit";
@ -53,7 +59,7 @@ $config['core_descr'][] = "core";
$config['custom_descr'][] = "something_made_up";
```
## Custom interface parser
# Custom interface parser
It's also possible to write your own parser, the existing one is: includes/port-descr-parser.inc.php
@ -65,15 +71,17 @@ $config['port_descr_parser'] = "includes/custom/my-port-descr-parser.inc.php";
## Setup
For Unix / Linux based systems, you need to run an additional script to support the parsing of interface infor.
For Unix / Linux based systems, you need to run an additional script
to support the parsing of interface infor.
- Add `ifAlias` from `/opt/librenms/scripts/` or download it from [here](https://github.com/librenms/librenms/blob/master/scripts/ifAlias) to the Server and make
it executable `chmod +x /path/to/ifAlias`
- Add to `snmpd.conf` something like:
- Add `ifAlias` from `/opt/librenms/scripts/` or download it from
[here](https://github.com/librenms/librenms/blob/master/scripts/ifAlias)
to the Server and make it executable `chmod +x /path/to/ifAlias`
- Add to `snmpd.conf` something like:
``pass .1.3.6.1.2.1.31.1.1.1.18 /path/to/ifAlias``
- Restart `snmpd` - `service snmpd restart`
Restart `snmpd` - `service snmpd restart`
There are no changes to be made or additions to install for the polling librenms.
Now you can set up your [keywords](#keywords) in your `/etc/network/interfaces`
``//Add more distributions than just Debian based``
``//Add more distributions than just Debian based``

View File

@ -1,8 +1,10 @@
source: Extensions/MIB-based-polling.md
path: blob/master/doc/
## WARNING ##
MIB-based polling is unmaintained and may be removed in the future. It might overload your LibreNMS server,
# WARNING
MIB-based polling is unmaintained and may be removed in the future.
It might overload your LibreNMS server,
destroy your data, set your routers on fire, and kick your cat. It has been
tested against a very limited set of devices (namely Ruckus ZD1000 wireless
controllers, and `net-snmp` on Linux). It may fail badly on other hardware.
@ -16,7 +18,7 @@ offer corrections/suggestions via pull requests or email.
Paul Gear <paul@librenms.org>
## Overview ##
# Overview
This is the 2nd experimental release of MIB polling. If you used the 1st
release, you MUST perform a data conversion of the MIB-based polling files
@ -27,7 +29,7 @@ MIB-based polling is disabled by default; you must set
`$config['poller_modules']['mib'] = true;`
in `config.php` to enable it.
## Preparation ##
# Preparation
MIB-based polling results in the creation of a separate RRD file for each
device-MIB-OID-index combination encountered by LibreNMS. Thus it can cause
@ -44,119 +46,125 @@ Unless you are running LibreNMS on a powerful system with pure SSD for RRD
storage, it is strongly recommended that you enable rrdcached and ensure it is
working *before* enabling MIB-based polling.
## Components ##
# Components
The components involved in MIB-based polling are:
### Discovery ###
## Discovery
- OS discovery determines whether there are MIBs which should be polled. If
- OS discovery determines whether there are MIBs which should be polled. If
so, they are registered in the `device_mibs` association table as relevant
to that device. MIB associations for each device can be viewed at:
http://your.librenms.server/device/device=XXXX/tab=mib/
<http://your.librenms.server/device/device=XXXX/tab=mib/>
All MIBs used by MIB-based polling may be viewed at:
http://your.librenms.server/mibs/
<http://your.librenms.server/mibs/>
All device associations created by MIB-based polling may be viewed at:
http://your.librenms.server/mib_assoc/ (Devices -> MIB associations)
<http://your.librenms.server/mib_assoc/> (Devices -> MIB associations)
- In addition, all devices are checked for a MIB matching their sysObjectID.
- In addition, all devices are checked for a MIB matching their sysObjectID.
If there is a matching MIB available, it is automatically included.
The sysObjectID for each device is now displayed on the overview page:
http://your.librenms.server/device/device=XXXX/
<http://your.librenms.server/device/device=XXXX/>
- Note that the above means that no MIB-based polling will occur until the
- Note that the above means that no MIB-based polling will occur until the
devices in question are rediscovered. If you want to begin MIB-based
polling immediately, you must force rediscovery from the web UI, or run it
from the CLI using `./discovery.php -h HOSTNAME`
- During discovery, relevant MIBs are parsed using `snmptranslate`, and the
- During discovery, relevant MIBs are parsed using `snmptranslate`, and the
data returned is used to populate a database which guides the poller in
what to store. At the moment, only OIDs of INTEGER, Integer32, Gauge32,
Unsigned32, Counter32, and Counter64 data types are parsed, and negative
values are untested.
- Devices may be excluded from MIB polling by changing the setting in the
- Devices may be excluded from MIB polling by changing the setting in the
device edit screen:
http://your.librenms.server/device/device=XXXX/tab=edit/section=modules/
<http://your.librenms.server/device/device=XXXX/tab=edit/section=modules/>
### Polling ###
## Polling
- During polling the MIB associations for the device are looked up, and the
- During polling the MIB associations for the device are looked up, and the
MIB is polled for current values. You can see the values which LibreNMS
has retrieved from the MIB poller in the "Device MIB values" section of
http://your.librenms.server/device/device=XXXX/tab=mib/
<http://your.librenms.server/device/device=XXXX/tab=mib/>
- Data from the latest poll is saved in the table `device_oids`, and RRD
- Data from the latest poll is saved in the table `device_oids`, and RRD
files are saved in the relevant device directory as
mibName-oidName-index.rrd
### Graphing ###
## Graphing
- For each graph type defined in the database, a graph will appear in:
http://your.librenms.server/device/device=XXXX/tab=graphs/group=mib/
- MIB graphs are generated generically by
`html/includes/graphs/device/mib.inc.php`
There is presently no customisation of graphs available.
- If there is only one index under a given OID, it is displayed as a normal
- For each graph type defined in the database, a graph will appear in:
<http://your.librenms.server/device/device=XXXX/tab=graphs/group=mib/>
- MIB graphs are generated generically by
`html/includes/graphs/device/mib.inc.php` There is presently no
customisation of graphs available.
- If there is only one index under a given OID, it is displayed as a normal
line graph; if there multiple OIDs, they are displayed as a stacked graph.
At the moment, all indices are placed in the same graph. This is
non-optimal for, e.g., wifi controllers with hundreds of APs attached.
### Alerting ###
## Alerting
There is no specific support for alerting in the MIB-based polling engine, but
the data it collects may be used in alerts. Here's an example of an alert
which detects when a Ruckus wireless controller reports meshing disabled on an
access point:
http://libertysys.com.au/imagebin/3btw98DR.png
<http://libertysys.com.au/imagebin/3btw98DR.png>
## Adding/testing other device types ##
# Adding/testing other device types
One of the goals of this work is to help take out the heavy lifting of adding
new device types. Even if you want fully-customised graphs or tables, you can
still use the MIB-based poller to make it easy to gather the data you want to
graph.
### How to add a new device MIB ###
## How to add a new device MIB
1. Ensure the manufacturer's MIB is present in the mibs directory. If you
1. Ensure the manufacturer's MIB is present in the mibs directory. If you
plan to submit your work to LibreNMS, make sure you attribute the source
of the MIB, including the exact download URL if possible, or explicit
instructions about how to obtain it.
2. Check that `snmptranslate -Ts -M mibs -m MODULE | grep mibName` produces
1. Check that `snmptranslate -Ts -M mibs -m MODULE | grep mibName` produces
a named list of OIDs. See the comments on `snmp_mib_walk()` in
`includes/snmp.inc.php` for an example.
3. Check that `snmptranslate -Td -On -M mibs -m MODULE MODULE::mibName`
1. Check that `snmptranslate -Td -On -M mibs -m MODULE MODULE::mibName`
produces a parsed description of the OID values. An example can be
found in the comments for `snmp_mib_parse()` in `includes/snmp.inc.php`.
4. Get the `sysObjectID` from a device, for example:
```snmpget -v2c -c public -OUsb -m SNMPv2-MIB -M /opt/librenms/mibs -t 30 hostname sysObjectID.0```
5. Ensure `snmptranslate -m all -M /opt/librenms/mibs OID 2>/dev/null`
1. Get the `sysObjectID` from a device, for example:
`snmpget -v2c -c public -OUsb -m SNMPv2-MIB -M /opt/librenms/mibs
-t 30 hostname sysObjectID.0`
1. Ensure `snmptranslate -m all -M /opt/librenms/mibs OID 2>/dev/null`
(where OID is the value returned for sysObjectID above) results in a
valid name for the MIB. See the comments for `snmp_translate()` in
`includes/snmp.inc.php` for an example. If this step fails, it means
there is something wrong with the MIB and `net-snmp` cannot parse it.
6. Add any additional MIBs you wish to poll for specific device types to
1. Add any additional MIBs you wish to poll for specific device types to
`includes/discovery/os/OSNAME.inc.php` by calling `poll_mibs()` with the
MIB module and name. See `includes/discovery/os/ruckuswireless.inc.php`
for an example.
7. That should be all you need to see MIB graphs!
8. If you want to develop more customised support for a particular OS, you
1. That should be all you need to see MIB graphs!
1. If you want to develop more customised support for a particular OS, you
can follow the above process, then use the resultant data collected by
LibreNMS in the RRD files or the database tables `device_oids`
## Configuration
### Main Configuration
In `/opt/librenms/config.php` add `$config['poller_modules']['mib'] = true;` to enable MIB polling globally.
Alternatively you can enable MIB polling per device by enabling it within the modules section for the specific device.
# Configuration
### Discovery
## Main Configuration
You need to add your desired MIBs to `/opt/librenms/mibs` folder.
You will then need to create a list of the OIDs you wish to use in the OS definition.
In `/opt/librenms/config.php` add `$config['poller_modules']['mib'] =
true;` to enable MIB polling globally. Alternatively you can enable
MIB polling per device by enabling it within the modules section for
the specific device.
## Discovery
You need to add your desired MIBs to `/opt/librenms/mibs` folder. You
will then need to create a list of the OIDs you wish to use in the OS
definition.
### Example
#### Example
`/opt/librenms/includes/definitions/ruckuswireless.yaml`
```yaml
@ -167,18 +175,19 @@ register_mibs:
ruckusZDWLANAPRadioStatsTable: RUCKUS-ZD-WLAN-MIB
```
These OIDs and MIBs will then be registered as part of the OS discovery ready for mib polling to work.
These OIDs and MIBs will then be registered as part of the OS
discovery ready for mib polling to work.
## TODO ##
# TODO
What's not included in MIB-based polling at present? These may be present in
future versions. Pull requests gratefully accepted!
- Parse and save integer and timetick data types.
- Filter MIBs/OIDs from being polled and/or saved.
- Move graphs from the MIB section to elsewhere. e.g. If a device uses a
- Parse and save integer and timetick data types.
- Filter MIBs/OIDs from being polled and/or saved.
- Move graphs from the MIB section to elsewhere. e.g. If a device uses a
unique MIB for CPU utilisation, we should display it under the relevant
health tab.
- Combine multiple MIB values into graphs automatically on a predefined or
- Combine multiple MIB values into graphs automatically on a predefined or
user-defined basis.
- Include MIB types in stats submissions.
- Include MIB types in stats submissions.

View File

@ -2,15 +2,18 @@ source: Extensions/Metric-Storage.md
path: blob/master/doc/
hide_toc: true
### Metric storage
By default we ship all metrics to RRD files, either directly or via [RRDCached](RRDCached.md). On top of this
you can ship metrics to Graphite, InfluxDB, OpenTSDB or Prometheus. At present you can't use these
backends to display graphs within LibreNMS and will need to use something like [Grafana](https://grafana.com/).
# Metric storage
For further information on configuring LibreNMS to ship data to one of the other backends then please see
the documentation below.
By default we ship all metrics to RRD files, either directly or via
[RRDCached](RRDCached.md). On top of this you can ship metrics to
Graphite, InfluxDB, OpenTSDB or Prometheus. At present you can't use
these backends to display graphs within LibreNMS and will need to use
something like [Grafana](https://grafana.com/).
> - [Graphite](metrics/Graphite.md)
> - [InfluxDB](metrics/InfluxDB.md)
> - [OpenTSDB](metrics/OpenTSDB.md)
> - [Prometheus](metrics/Prometheus.md)
For further information on configuring LibreNMS to ship data to one of
the other backends then please see the documentation below.
- [Graphite](metrics/Graphite.md)
- [InfluxDB](metrics/InfluxDB.md)
- [OpenTSDB](metrics/OpenTSDB.md)
- [Prometheus](metrics/Prometheus.md)

View File

@ -8,7 +8,8 @@ LibreNMS has the ability to show you a network map based on:
- xDP Discovery
- MAC addresses
By default, both are are included but you can enable / disable either one using the following config option:
By default, both are are included but you can enable / disable either
one using the following config option:
```php
$config['network_map_items'] = array('mac','xdp');
@ -17,26 +18,43 @@ $config['network_map_items'] = array('mac','xdp');
Either remove mac or xdp depending on which you want.
XDP is based on FDP, CDP and LLDP support based on the device type.
A global map will be drawn from the information in the database, it is worth noting that this could lead to a large network map.
Network maps for individual devices are available showing the relationship with other devices.
Also you can Build Device Groups and those Device Groups can be drawn with Network Map.
A global map will be drawn from the information in the database, it is
worth noting that this could lead to a large network map. Network maps
for individual devices are available showing the relationship with
other devices. Also you can Build Device Groups and those Device
Groups can be drawn with Network Map.
# Network Map Configurator
This link will show you all the options and explain what they
do. [Link](https://visjs.github.io/vis-network/docs/network/)
You may also access the dyanamic configuration interface [example
here](https://visjs.github.io/vis-network/examples/network/other/configuration.html)
from within LibreNMS by adding the following to config.php
### Network Map Configurator.
This link will show you all the options and explain what they do. [Link](https://visjs.github.io/vis-network/docs/network/)
You may also access the dyanamic configuration interface [example here](https://visjs.github.io/vis-network/examples/network/other/configuration.html) from within LibreNMS by adding the following to config.php
```php
$config['network_map_vis_options'] = '{
"configure": { "enabled": true},
}';
```
### Note
You may want to disable the automatic page refresh while you're tweaking your configuration, as the refresh will reset the dynamic configuration UI to the values currently saved in config.php
This can be done by going clicking on the Settings Icon then Refresh Pause.
### Configurator Output
Once you've achieved your desired map appearance, click the generate options button at the bottom to be given the necessary parameters to add to your config.php file.
You will need to paste the genrated config into config.php the format will need to look something like this.
Note that the configuartor will output the config with `var options` you will need strip that out and at the end of the config you need to add in `}';` see the example below.
## Note
You may want to disable the automatic page refresh while you're
tweaking your configuration, as the refresh will reset the dynamic
configuration UI to the values currently saved in config.php This can
be done by going clicking on the Settings Icon then Refresh Pause.
## Configurator Output
Once you've achieved your desired map appearance, click the generate
options button at the bottom to be given the necessary parameters to
add to your config.php file. You will need to paste the genrated
config into config.php the format will need to look something like
this. Note that the configuartor will output the config with `var options`
you will need strip that out and at the end of the config you need to
add in `}';` see the example below.
```php
$config['network_map_vis_options'] = '{
"nodes": {

View File

@ -2,39 +2,55 @@ source: Extensions/Oxidized.md
path: blob/master/doc/
# Oxidized intro
---
Integrating LibreNMS with [Oxidized](https://github.com/ytti/oxidized-web) brings the following benefits:
- Config viewing: Current, History, and Diffs all under the Configs tab of each device
- Automatic addition of devices to Oxidized: Including filtering and grouping to ease credential management
- Configuration searching (Requires oxidized-web 0.8.0 or newer)
Integrating LibreNMS with
[Oxidized](https://github.com/ytti/oxidized-web) brings the following
benefits:
- Config viewing: Current, History, and Diffs all under the Configs tab of each device
- Automatic addition of devices to Oxidized: Including filtering and
grouping to ease credential management
- Configuration searching (Requires oxidized-web 0.8.0 or newer)
First you will need to [install Oxidized following their documentation](https://github.com/ytti/oxidized#installation).
Then you can procede to the LibreNMS Web UI and go to Oxidized Settings in the External Settings section of Global Settings. Enable it and enter the url to your oxidized instance.
Then you can procede to the LibreNMS Web UI and go to Oxidized
Settings in the External Settings section of Global Settings. Enable
it and enter the url to your oxidized instance.
To have devices automatically added, you will need to configure oxidized to pull them from LibreNMS [Feeding Oxidized](#feeding-oxidized)
To have devices automatically added, you will need to configure
oxidized to pull them from LibreNMS [Feeding
Oxidized](#feeding-oxidized)
LibreNMS will automatically map the OS to the Oxidized model name if they don't match. this means you shouldn't need to use the model_map config option within Oxidized.
LibreNMS will automatically map the OS to the Oxidized model name if
they don't match. this means you shouldn't need to use the model_map
config option within Oxidized.
## Detailed integration information
---
# Detailed integration information
This is a straight forward use of Oxidized, it relies on you having a working Oxidized setup which is already taking config snapshots for your devices.
When you have that, you only need the following config to enable the display of device configs within the device page itself:
This is a straight forward use of Oxidized, it relies on you having a
working Oxidized setup which is already taking config snapshots for
your devices. When you have that, you only need the following config
to enable the display of device configs within the device page itself:
```php
$config['oxidized']['enabled'] = TRUE;
$config['oxidized']['url'] = 'http://127.0.0.1:8888';
```
LibreNMS supports config versioning if Oxidized does. This is known to work with the git output module.
LibreNMS supports config versioning if Oxidized does. This is known
to work with the git output module.
```php
$config['oxidized']['features']['versioning'] = true;
```
Oxidized supports various ways to utilise credentials to login to devices, you can specify global username/password within Oxidized, Group level username/password or per device.
LibreNMS currently supports sending groups back to Oxidized so that you can then define group credentials within Oxidized. To enable this support please switch on 'Enable the return of groups to Oxidized':
Oxidized supports various ways to utilise credentials to login to
devices, you can specify global username/password within Oxidized,
Group level username/password or per device. LibreNMS currently
supports sending groups back to Oxidized so that you can then define
group credentials within Oxidized. To enable this support please
switch on 'Enable the return of groups to Oxidized':
```php
$config['oxidized']['group_support'] = true;
@ -46,19 +62,27 @@ You can set a default group that devices will fall back to with:
$config['oxidized']['default_group'] = 'default';
```
#### SELinux
If you're runnng SELinux, you'll need to allow httpd to connect outbound to the network, otherwise Oxidized integration in the web UI will silently fail:
# SELinux
If you're runnng SELinux, you'll need to allow httpd to connect
outbound to the network, otherwise Oxidized integration in the web UI
will silently fail:
```
setsebool -P httpd_can_network_connect 1
```
### Feeding Oxidized
# Feeding Oxidized
----
Oxidized has support for feeding devices into it via an API call, support for Oxidized has been added to the LibreNMS API. A sample config for Oxidized is provided below.
Oxidized has support for feeding devices into it via an API call,
support for Oxidized has been added to the LibreNMS API. A sample
config for Oxidized is provided below.
You will need to configure default credentials for your devices in the Oxidized config, LibreNMS doesn't provide login credentials at this time.
You will need to configure default credentials for your devices in the
Oxidized config, LibreNMS doesn't provide login credentials at this
time.
```bash
source:
@ -74,27 +98,39 @@ You will need to configure default credentials for your devices in the Oxidized
X-Auth-Token: '01582bf94c03104ecb7953dsadsadwed'
```
LibreNMS is able to reload the Oxidized list of nodes, each time a device is added to LibreNMS.
To do so, edit the option in Global Settings>External Settings>Oxidized Integration or add the following to your config.php.
LibreNMS is able to reload the Oxidized list of nodes, each time a
device is added to LibreNMS. To do so, edit the option in Global
Settings>External Settings>Oxidized Integration or add the following
to your config.php.
```php
$config['oxidized']['reload_nodes'] = true;
```
### Creating overrides
To return an override to Oxidized you can do this by providing the override key, followed by matching a lookup for a host (or hosts), and finally by defining the overriding value itself. LibreNMS does not check for the validity of these attributes but will deliver them to Oxidized as defined.
# Creating overrides
Matching of hosts can be done using `hostname`, `sysname`, `os`, `location`, `sysDescr` or `hardware` and including either a 'match' key and value, or a 'regex' key and value. The order of matching is:
* `hostname`
* `sysname`
* `sysDescr`
* `hardware`
* `os`
* `location`
* `ip`
To return an override to Oxidized you can do this by providing the
override key, followed by matching a lookup for a host (or hosts), and
finally by defining the overriding value itself. LibreNMS does not
check for the validity of these attributes but will deliver them to
Oxidized as defined.
To match on the device hostnames or sysnames that contain 'lon-sw' or if the location contains 'London' then you would place the following within config.php:
Matching of hosts can be done using `hostname`, `sysname`, `os`,
`location`, `sysDescr` or `hardware` and including either a 'match'
key and value, or a 'regex' key and value. The order of matching is:
- `hostname`
- `sysname`
- `sysDescr`
- `hardware`
- `os`
- `location`
- `ip`
To match on the device hostnames or sysnames that contain 'lon-sw' or
if the location contains 'London' then you would place the following
within config.php:
```php
$config['oxidized']['maps']['group']['hostname'][] = array('regex' => '/^lon-sw/', 'group' => 'london-switches');
@ -108,22 +144,29 @@ To match on a device os of edgeos then please use the following:
$config['oxidized']['maps']['group']['os'][] = array('match' => 'edgeos', 'group' => 'wireless');
```
Matching on OS requires system name of the OS. For example, 'match' => 'RouterOS' will not work, while 'match' => 'routeros' will.
Matching on OS requires system name of the OS. For example, 'match' =>
'RouterOS' will not work, while 'match' => 'routeros' will.
To override the IP Oxidized uses to poll the device, you can add the following within config.php:
To override the IP Oxidized uses to poll the device, you can add the
following within config.php:
```php
$config['oxidized']['maps']['ip']['sysname'][] = array('regex' => '/^my.node/', 'ip' => '192.168.1.10');
$config['oxidized']['maps']['ip']['sysname'][] = array('match' => 'my-other.node', 'ip' => '192.168.1.20');
```
This allows extending the configuration further by providing a completely flexible model for custom flags and settings, for example, below shows the ability to add an ssh_proxy host within Oxidized simply by adding the below to your configuration:
This allows extending the configuration further by providing a
completely flexible model for custom flags and settings, for example,
below shows the ability to add an ssh_proxy host within Oxidized
simply by adding the below to your configuration:
```php
$config['oxidized']['maps']['ssh_proxy']['sysname'][] = array('regex' => '/^my.node/', 'ssh_proxy' => 'my-ssh-gateway.node');
```
Or of course, any custom value that could be needed or wanted can be applied, for example, setting a "myAttribute" to "Super cool value" for any configured and enabled "routeros" device.
Or of course, any custom value that could be needed or wanted can be
applied, for example, setting a "myAttribute" to "Super cool value"
for any configured and enabled "routeros" device.
```php
$config['oxidized']['maps']['myAttribute']['os'][] = array('match' => 'routeros', 'myAttribute' => 'Super cool value');
@ -132,10 +175,11 @@ $config['oxidized']['maps']['myAttribute']['os'][] = array('match' => 'routeros'
Verify the return of groups by querying the API:
```
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized
```
If you need to, you can specify credentials for groups by using the following in your Oxidized config:
If you need to, you can specify credentials for groups by using the
following in your Oxidized config:
```bash
groups:
@ -144,52 +188,67 @@ groups:
password: <password>
```
### Miscellaneous
# Miscellaneous
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?"
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:
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','power');
$config['oxidized']['ignore_os'] = array('linux','windows');
```
### Trigger configuration backups
# Trigger configuration backups
Using the Oxidized REST API and [Syslog Hooks](/Extensions/Syslog/#external-hooks), Oxidized can trigger configuration downloads whenever a configuration change event has been logged. An example script to do this is included in `./scripts/syslog-notify-oxidized.php`. Oxidized can spawn a new worker thread and perform the download immediately with the following configuration
Using the Oxidized REST API and [Syslog
Hooks](/Extensions/Syslog/#external-hooks), Oxidized can trigger
configuration downloads whenever a configuration change event has been
logged. An example script to do this is included in
`./scripts/syslog-notify-oxidized.php`. Oxidized can spawn a new
worker thread and perform the download immediately with the following
configuration
```bash
next_adds_job: true
```
### Validate Oxidized config
# Validate Oxidized config
You can perform basic validation of the Oxidized configuration by going to the Overview -> Tools -> Oxidized link and in the Oxidized config validation page, paste your
yaml file into the input box and click 'Validate YAML'.
You can perform basic validation of the Oxidized configuration by
going to the Overview -> Tools -> Oxidized link and in the Oxidized
config validation page, paste your yaml file into the input box and
click 'Validate YAML'.
We check for yaml syntax errors and also actual config values to ensure they are used in the correct location.
We check for yaml syntax errors and also actual config values to
ensure they are used in the correct location.
## Accessing configuration of a disabled/removed device
# Accessing configuration of a disabled/removed device
When you're disabling or removing a device from LibreNMS, Oxidized will no longer shows it in the web interface the configuration. You can access directly to this information in the Git repository of Oxidized (if using Git to store versions).
When you're disabling or removing a device from LibreNMS, Oxidized
will no longer shows it in the web interface the configuration. You
can access directly to this information in the Git repository of
Oxidized (if using Git to store versions).
1. Check in your Oxidized where are stored your Git repositories:
1: Check in your Oxidized where are stored your Git repositories:
- ```
/home/oxidized/.config/oxidized/config
```
```
/home/oxidized/.config/oxidized/config
```
2. Go the correct Git repository for the needed device (the .git one) and get the list of devices using this command:
2: Go the correct Git repository for the needed device (the .git one)
and get the list of devices using this command:
- ```
git ls-files -s
```
```
git ls-files -s
```
3. Save the object ID of the device, and run the command to get the file content:
3: Save the object ID of the device, and run the command to get the
file content:
1. ```
git cat-file -p <object id>
```
```
git cat-file -p <object id>
```

View File

@ -1,12 +1,17 @@
source: Extensions/PeeringDB.md
path: blob/master/doc/
# PeeringDB Support
LibreNMS has integration with PeeringDB to match up your BGP sessions with the peering exchanges you are connected to.
LibreNMS has integration with PeeringDB to match up your BGP sessions
with the peering exchanges you are connected to.
To enable the integration please do so within the WebUI -> Global Settings -> External Settings -> PeeringDB Integration.
To enable the integration please do so within the WebUI -> Global
Settings -> External Settings -> PeeringDB Integration.
Data will be collated the next time daily.sh is run or you can manually force this by running `php daily.php -f peeringdb`,
the initial collection is delayed for a random amount of time to avoid overloading the PeeringDB API.
Data will be collated the next time daily.sh is run or you can
manually force this by running `php daily.php -f peeringdb`, the
initial collection is delayed for a random amount of time to avoid
overloading the PeeringDB API.
Once enabled you will have an additional menu item under Routing -> PeeringDB

View File

@ -1,13 +1,15 @@
source: Extensions/Plugin-System.md
path: blob/master/doc/
# Developing for the Plugin System
> This will most likely be deprecated in favour of adding the possible extensions to the core code base.
This will most likely be deprecated in favour of adding the possible
extensions to the core code base.
This documentation will hopefully give you a basis for how to write a plugin for LibreNMS.
A test plugin is included in LibreNMS distribution.
This documentation will hopefully give you a basis for how to write a
plugin for LibreNMS. A test plugin is included in LibreNMS distribution.
### Generic structure ###
# Generic structure
Plugins need to be installed into html/plugins
@ -24,12 +26,16 @@ The above structure is checked before a plugin can be installed.
All files / folder names are case sensitive and must match.
PluginName - This is a directory and needs to be named as per the plugin you are creating.
PluginName - This is a directory and needs to be named as per the
plugin you are creating.
- PluginName.php :: This file is used to process calls into the plugin
from the main LibreNMS install. Here only functions within the class
for your plugin that LibreNMS calls will be executed. For a list of
currently enabled system hooks, please see further down. The minimum
code required in this file is (replace Test with the name of your
plugin):
PluginName.php - This file is used to process calls into the plugin from the main LibreNMS install.
Here only functions within the class for your plugin that LibreNMS calls will be executed.
For a list of currently enabled system hooks, please see further down.
The minimum code required in this file is (replace Test with the name of your plugin):
```
<?php
@ -39,30 +45,34 @@ class Test {
?>
```
PluginName.inc.php - This file is the main included file when browsing to the plugin itself.
You can use this to display / edit / remove whatever you like.
The minimum code required in this file is:
- PluginName.inc.php :: This file is the main included file when
browsing to the plugin itself. You can use this
to display / edit / remove whatever you like. The
minimum code required in this file is:
```
<?php
?>
```
### System Hooks ###
# System Hooks
System hooks are called as functions within your plugin class.
The following system hooks are currently available:
System hooks are called as functions within your plugin class. The
following system hooks are currently available:
- menu() :: This is called to build the plugin menu system and you
can use this to link to your plugin (you don't have to).
* menu()
* This is called to build the plugin menu system and you can use this to link to your plugin (you don't have to).
```
public static function menu() {
echo('<li><a href="plugin/p='.get_class().'">'.get_class().'</a></li>');
}
```
* device_overview_container($device)
* This is called in the Device Overview page. You receive the $device as a parameter, can do your work here and display your results in a frame.
- device_overview_container($device) :: This is called in the Device
Overview page. You receive the $device as a parameter, can do your
work here and display your results in a frame.
```
public function device_overview_container($device) {
@ -72,8 +82,10 @@ The following system hooks are currently available:
}
```
* port_container($device, $port)
* This is called in the Port page, in the "Plugins" menu_option that will appear when your plugin gets enabled. In this function, you can do your work and display your results in a frame.
- port_container($device, $port) :: This is called in the Port page,
in the "Plugins" menu_option that will appear when your plugin gets
enabled. In this function, you can do your work and display your
results in a frame.
```
public function port_container($device, $port) {
@ -82,4 +94,3 @@ The following system hooks are currently available:
echo('</div></div></div></div>');
}
```

View File

@ -1,20 +1,29 @@
source: Extensions/Proxmox.md
path: blob/master/doc/
# Proxmox graphing
It is possible to create graphs of the Proxmox **VMs** that run on your monitored machines. Currently, only traffic graphs are created. One for each interface on each VM. Possibly, IO graphs 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.
It is possible to create graphs of the Proxmox **VMs** that run on
your monitored machines. Currently, only traffic graphs are
created. One for each interface on each VM. Possibly, IO graphs will
be added later on.
### Enabling Proxmox graphs
The ultimate goal is to be able to create traffic bills for VMs, no
matter on which physical machine that VM runs.
# Enabling Proxmox graphs
To enable Proxmox graphs, do the following:
In config.php, enable Proxmox:
```php
$config['enable_proxmox'] = 1;
```
Then, install git and [librenms-agent](http://docs.librenms.org/Extensions/Applications/) on the machines running Proxmox and enable the Proxmox-script using:
Then, install git and
[librenms-agent](http://docs.librenms.org/Extensions/Applications/) on
the machines running Proxmox and enable the Proxmox-script using:
```bash
cp /opt/librenms-agent/agent-local/proxmox /usr/lib/check_mk_agent/local/proxmox
@ -22,18 +31,24 @@ chmod +x /usr/lib/check_mk_agent/local/proxmox
```
Then, enable and start the check_mk service using systemd
```bash
cp /opt/librenms-agent/check_mk@.service /opt/librenms-agent/check_mk.socket /etc/systemd/system
systemctl daemon-reload
systemctl enable check_mk.socket && systemctl start check_mk.socket
```
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.
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.
### Note, if you want to use use xinetd instead of systemd
Its possible to use the librenms-agent started by xinetd instead of systemd. One use case is if you are forced to use a old Proxmox installation.
After installing the librenms-agent (see above) please copy enable the xinetd config, then restart the xinetd service:
# Note, if you want to use use xinetd instead of systemd
Its possible to use the librenms-agent started by xinetd instead of
systemd. One use case is if you are forced to use a old Proxmox
installation. After installing the librenms-agent (see above) please
copy enable the xinetd config, then restart the xinetd service:
```bash
cp check_mk_xinetd /etc/xinetd.d/check_mk

View File

@ -1,14 +1,24 @@
### Securing with nginx
path: blob/master/doc/
According to the [man page](https://linux.die.net/man/1/rrdcached), under "SECURITY CONSIDERATIONS", rrdcached has no authentication or security except for running under a unix socket. If you choose to use a network socket instead of a unix socket, you will need to secure your rrdcached installation. To do so you can proxy rrdcached using nginx to allow only specific IPs to connect.
# Securing with nginx
using the same setup above, using nginx version 1.9.0 or later, you can follow this setup to proxy the default rrdcached port to the local unix socket.
path: blob/master/doc/
According to the [man page](https://linux.die.net/man/1/rrdcached),
under "SECURITY CONSIDERATIONS", rrdcached has no authentication or
security except for running under a unix socket. If you choose to use
a network socket instead of a unix socket, you will need to secure
your rrdcached installation. To do so you can proxy rrdcached using
nginx to allow only specific IPs to connect.
Using the same setup above, using nginx version 1.9.0 or later, you
can follow this setup to proxy the default rrdcached port to the local
unix socket.
(You can use `./conf.d` for your configuration as well)
`mkdir /etc/nginx/streams-{available,enabled}`
add the following to your nginx.conf file:
```nginx
#/etc/nginx/nginx.conf
...
@ -17,7 +27,8 @@ stream {
}
```
add this to `/etc/nginx/streams-available/rrd`
Add this to `/etc/nginx/streams-available/rrd`
```nginx
server {
listen 42217;
@ -29,9 +40,13 @@ server {
proxy_pass unix:/var/run/rrdcached/rrdcached.sock;
}
```
replace `$LibreNMS_IP` with the ip of the server that will be using rrdcached. You can specify more than one `allow` statement.
This will bind nginx to TCP 42217 (the default rrdcached port), allow the specified IPs to connect, and deny all others.
Replace `$LibreNMS_IP` with the ip of the server that will be using
rrdcached. You can specify more than one `allow` statement. This will
bind nginx to TCP 42217 (the default rrdcached port), allow the
specified IPs to connect, and deny all others.
next, we'll symlink the config to streams-enabled:
`ln -s /etc/nginx/streams-{available,enabled}/rrd`

View File

@ -1,32 +1,33 @@
source: Extensions/RRDCached.md
path: blob/master/doc/
# Setting up RRDCached
This document will explain how to setup RRDCached for LibreNMS.
> Since version 1.5, rrdtool / rrdcached now supports creating rrd files over rrdcached.
If you have rrdcached 1.5.5 or above, you can also tune over rrdcached.
To enable this set the following config:
Since version 1.5, rrdtool / rrdcached now supports creating rrd files
over rrdcached. If you have rrdcached 1.5.5 or above, you can also
tune over rrdcached. To enable this set the following config:
```php
$config['rrdtool_version'] = '1.5.5';
```
NOTE: This feature requires your client version of rrdtool to be 1.5.5 or over, in addition to your rrdcached version.
NOTE: This feature requires your client version of rrdtool to be 1.5.5
or over, in addition to your rrdcached version.
### Distributed Poller Support Matrix
# Distributed Poller Support Matrix
Shared FS: Is a shared filesystem required?
Features: Supported features in the version indicated.
```
G = Graphs.
C = Create RRD files.
U = Update RRD files.
T = Tune RRD files.
```
| Version | Shared FS | Features |
| ------- | :-------: | -------- |
@ -35,10 +36,13 @@ Features: Supported features in the version indicated.
| >=1.5.5 | No | G,C,U |
| >=1.6.x | No | G,C,U |
It is recommended that you monitor your LibreNMS server with LibreNMS so you can view the disk I/O usage delta.
It is recommended that you monitor your LibreNMS server with LibreNMS
so you can view the disk I/O usage delta.
## RRDCached installation CentOS 7
1: Create `/etc/systemd/system/rrdcached.service` with this content:
### RRDCached installation CentOS 7
1. Create `/etc/systemd/system/rrdcached.service` with this content:
```
[Unit]
Description=Data caching daemon for rrdtool
@ -53,23 +57,28 @@ ExecStart=/usr/bin/rrdcached -w 1800 -z 1800 -f 3600 -s librenms -U librenms -G
WantedBy=default.target
```
2. Start rrdcached
2: Start rrdcached
```bash
systemctl enable --now rrdcached.service
```
3. Edit `/opt/librenms/config.php` to include:
3: Edit `/opt/librenms/config.php` to include:
```php
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
### RRDCached installation Ubuntu 16
1. Install rrdcached
## RRDCached installation Ubuntu 16
1: Install rrdcached
```bash
sudo apt-get install rrdcached
```
2. Edit `/etc/default/rrdcached` to include:
2: Edit `/etc/default/rrdcached` to include:
```
DAEMON=/usr/bin/rrdcached
DAEMON_USER=librenms
@ -85,29 +94,34 @@ SOCKGROUP=librenms
BASE_OPTIONS="-B -F -R"
```
2. Fix permissions
2: Fix permissions
```bash
chown librenms:librenms /var/lib/rrdcached/journal/
```
3. Restart the rrdcached service
3: Restart the rrdcached service
```bash
systemctl restart rrdcached.service
```
5. Edit `/opt/librenms/config.php` to include:
5: Edit `/opt/librenms/config.php` to include:
```php
$config['rrdcached'] = "unix:/var/run/rrdcached.sock";
```
### RRDCached installation Debian Jessie (rrdcached 1.4.8)
## RRDCached installation Debian Jessie (rrdcached 1.4.8)
1: Install rrdcached
1. Install rrdcached
```bash
sudo apt-get install rrdcached
```
2. Edit /etc/default/rrdcached to include:
2: Edit /etc/default/rrdcached to include:
```bash
OPTS="-s librenms"
OPTS="$OPTS -l unix:/var/run/rrdcached.sock"
@ -116,23 +130,28 @@ OPTS="$OPTS -b /opt/librenms/rrd/ -B"
OPTS="$OPTS -w 1800 -z 1800 -f 3600 -t 4"
```
3. Restart the rrdcached service
3: Restart the rrdcached service
```bash
systemctl restart rrdcached.service
```
4. Edit /opt/librenms/config.php to include:
4: Edit /opt/librenms/config.php to include:
```php
$config['rrdcached'] = "unix:/var/run/rrdcached.sock";
```
### RRDCached installation Debian Stretch (rrdcached 1.6.0)
1. Install rrdcached
## RRDCached installation Debian Stretch (rrdcached 1.6.0)
1: Install rrdcached
```bash
sudo apt-get install rrdcached
```
2. Edit /etc/default/rrdcached to include:
2; Edit /etc/default/rrdcached to include:
```bash
DAEMON=/usr/bin/rrdcached
WRITE_TIMEOUT=1800
@ -148,33 +167,40 @@ DAEMON_USER=librenms
BASE_OPTIONS="-B -F -R"
```
3. Fix permissions
3: Fix permissions
```bash
chown librenms:librenms /var/lib/rrdcached/journal/
```
4. Restart the rrdcached service
4: Restart the rrdcached service
```bash
systemctl restart rrdcached.service
```
5. Edit /opt/librenms/config.php to include:
5: Edit /opt/librenms/config.php to include:
For local RRDCached server
```php
$config['rrdcached'] = "unix:/var/run/rrdcached.sock";
```
For remote RRDCached server
Make sure you have network option in /var/default/rrdcached
For remote RRDCached server make sure you have network option in /var/default/rrdcached
```bash
NETWORK_OPTIONS="-L"
NETWORK_OPTIONS="-L"
```
```php
$config['rrdcached'] = "IPADDRESS:42217";
```
NOTE: change IPADDRESS to the ip the rrdcached server is listening on.
### RRDCached installation CentOS 6
NOTE: change IPADDRESS to the ip the rrdcached server is listening on.
## RRDCached installation CentOS 6
This example is based on a fresh LibreNMS install, on a minimal CentOS 6 installation.
In this example, we'll use the Repoforge repository.
@ -182,12 +208,14 @@ In this example, we'll use the Repoforge repository.
rpm -ivh http://pkgs.repoforge.org/rpmforge-release/rpmforge-release-0.5.3-1.el6.rf.x86_64.rpm
vi /etc/yum.repos.d/rpmforge.repo
```
- Enable the Extra repo
```ssh
yum update rrdtool
vi /etc/yum.repos.d/rpmforge.repo
```
- Disable the [rpmforge] and [rpmforge-extras] repos again
```ssh
@ -206,19 +234,22 @@ service rrdcached start
```
- Edit /opt/librenms/config.php to include:
```php
$config['rrdcached'] = "unix:/var/run/rrdcached/rrdcached.sock";
```
## Verify
# Verify
Check to see if the graphs are being drawn in LibreNMS. This might take a few minutes.
After at least one poll cycle (5 mins), check the LibreNMS disk I/O performance delta.
Disk I/O can be found under the menu Devices>All Devices>[localhost hostname]>Health>Disk I/O.
Disk I/O can be found under the menu Devices>All Devices>[localhost
hostname]>Health>Disk I/O.
Depending on many factors, you should see the Ops/sec drop by ~30-40%.
#### Securing RRCached
# Securing RRCached
Please see [RRDCached Security](RRDCached-Security.md)
[1]: http://librenms.readthedocs.org/Installation/Installation-CentOS-7-Apache/

View File

@ -1,18 +1,25 @@
source: Extensions/RRDTune.md
path: blob/master/doc/
# 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).
# 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
- 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 misreported) the max value is set. If you don't want to wait until
a port speed changes then you can run the included script:
Now when a port interface speed changes (this can happen because of a
physical change or just because the device has misreported) the max
value is set. If you don't want to wait until a port speed changes
then you can run the included script:
`./scripts/tune_port.php -h <hostname> -p <ifName>`
@ -20,6 +27,7 @@ Wildcards are supported using *, i.e:
`./scripts/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.
This script will then perform the rrdtool tune on each port found
using the provided ifSpeed for that port.
Run `./scripts/tune_port.php` to see help page.

View File

@ -1,13 +1,17 @@
source: Extensions/Rancid.md
path: blob/master/doc/
# Rancid integration
Librenms can generate a list of hosts that can be monitored by RANCID.
We assume you have currently a running Rancid, and you just need to create and update the file 'router.db'
Librenms can generate a list of hosts that can be monitored by
RANCID. We assume you have currently a running Rancid, and you just
need to create and update the file 'router.db'
### Included Rancid script
# Included Rancid script
To generate the config file (maybe even add a cron to schedule this). We've assumed a few locations for Rancid, the config file you want to call it and where LibreNMS is:
To generate the config file (maybe even add a cron to schedule
this). We've assumed a few locations for Rancid, the config file you
want to call it and where LibreNMS is:
```bash
cd /opt/librenms/scripts/
@ -29,7 +33,7 @@ $config['rancid_ignorecomments'] = 0;
After that, you should see some "config" tab on routers that have a rancid update.
#### Ubuntu Rancid Install
# Ubuntu Rancid Install
The options shown below also contains the default values.
@ -37,42 +41,52 @@ The options shown below also contains the default values.
`sudo apt-get install rancid subversion`
Edit Rancid config file to use subversion or git instead of default cvs, and adds a group:
Edit Rancid config file to use subversion or git instead of default
cvs, and adds a group:
`sudo vi /etc/rancid/rancid.conf`
`LIST_OF_GROUPS="librenms"`
Now change these two lines:
```
CVSROOT=$BASEDIR/CVS; export CVSROOT
RCSSYS=cvs; export RCSSYS
```
to:
```
CVSROOT=$BASEDIR/SVN; export CVSROOT
RCSSYS=svn; export RCSSYS
```
> NOTE - This only creates 1 group! You can of course make more when you get the hang of it, this is just a basic 'Need it to work" deal.
NOTE - This only creates 1 group! You can of course make more when you
get the hang of it, this is just a basic 'Need it to work" deal.
`sudo su -c /var/lib/rancid/bin/rancid-cvs -s /bin/bash -l rancid`
> NOTE - do NOT change cvs to svn here! Leave command as is!
Get a list of devices from Librenms you can pull configs from:
```
cd /opt/librenms/scripts
sudo ./gen_rancid.php
```
Copy the output. Replace all ":" with ";" example:
```
alphcr1:cisco:up will change to:
alphcr1;cisco;up
```
copy and past results into the below file:
copy and past results into the below file:
`sudo vi /var/lib/rancid/librenms/router.db`
> NOTE - This ONLY applies to newer RANCID versions and Linux distros. Older versions will need to retain the : and not the ;
NOTE - This ONLY applies to newer RANCID versions and Linux
distros. Older versions will need to retain the : and not the ;
Create/edit rancids login file:
@ -97,9 +111,11 @@ sudo chmod 600 /var/lib/rancid/.cloginrc
Test config:
`sudo /usr/lib/rancid/bin/clogin -f /var/lib/rancid/.cloginrc <device hostname>`
> NOTE: IF you run into a 'diffie-hellmen' kind of error, then it is because your Linux distro is using newer encyryprtion methods etc.
This is basically just letting you know that the device you tested on is running an outdated encryption type. I recommend updating downstream device if able.
If not, the following should fix:
NOTE: IF you run into a 'diffie-hellmen' kind of error, then it is
because your Linux distro is using newer encyryprtion methods
etc. This is basically just letting you know that the device you
tested on is running an outdated encryption type. I recommend updating
downstream device if able. If not, the following should fix:
`sudo vi /etc/ssh/ssh_config`
@ -128,6 +144,7 @@ cd /opt/librenms/
```
Add Rancid into LibreNMS config.php:
```php
### Rancid
$config['rancid_configs'][] = '/var/lib/rancid/librenms/configs/';

View File

@ -1,13 +1,21 @@
source: Extensions/SNMP-Proxy.md
path: blob/master/doc/
# SNMP Proxy
If you have machines that you want to monitor but are not reachable directly, you can use [SNMPD Proxy](http://www.net-snmp.org/wiki/index.php/Snmpd_proxy). This will use the reachable SNMPD to proxy requests to the unreachable SNMPD.
If you have machines that you want to monitor but are not reachable
directly, you can use [SNMPD
Proxy](http://www.net-snmp.org/wiki/index.php/Snmpd_proxy). This will
use the reachable SNMPD to proxy requests to the unreachable SNMPD.
## Example configuration
We want to poll ```unreachable.example.com``` via ```hereweare.example.com```. Use the following config:
On ```hereweare.example.com```:
We want to poll 'unreachable.example.com' via
'hereweare.example.com'. Use the following config:
On 'hereweare.example.com':
```
view all included .1
com2sec -Cn ctx_unreachable readonly <poller-ip> unreachable
@ -15,7 +23,8 @@ On ```hereweare.example.com```:
proxy -Cn ctx_unreachable -v 2c -c private unreachable.example.com .1.3
```
On ```unreachable.example.com```:
On 'unreachable.example.com':
```
view all included .1 80
com2sec readonly <hereweare.example.com ip address> private
@ -25,5 +34,8 @@ On ```unreachable.example.com```:
access MyROGroup "" any noauth exact all none none
```
You can now poll community ```private``` on ```unreachable.example.com``` via community ```unreachable``` on host ```hereweare.example.com```. Please note that requests on ```unreachable.example.com``` will be coming from ```hereweare.example.com```, not your poller.
You can now poll community 'private' on
'unreachable.example.com' via community 'unreachable' on host
'hereweare.example.com'. Please note that requests on
'unreachable.example.com' will be coming from
'hereweare.example.com', not your poller.

View File

@ -1,9 +1,11 @@
source: Extensions/SNMP-Trap-Handler.md
path: blob/master/doc/
# SNMP trap handling
Currently, librenms only supports linkUp/linkDown (port up/down), bgpEstablished/bgpBackwardTransition (BGP Sessions Up/Down) and authenticationFailure SNMP traps.
To add more see [Adding new SNMP Trap handlers](../Developing/SNMP-Traps.md)
Currently, librenms only supports linkUp/linkDown (port up/down),
bgpEstablished/bgpBackwardTransition (BGP Sessions Up/Down) and
authenticationFailure SNMP traps. To add more see [Adding new SNMP Trap handlers](../Developing/SNMP-Traps.md)
Traps are handled via snmptrapd.
@ -13,7 +15,10 @@ Install snmptrapd via your package manager.
To enable snmptrapd to properly parse traps, we will need to add MIBs.
Make the folder `/etc/systemd/system/snmptrapd.service.d/` and edit the file `/etc/systemd/system/snmptrapd.service.d/mibs.conf` and add the following content. You may want to tweak to add vendor directories for devices you care about (in addition to or instead of cisco).
Make the folder `/etc/systemd/system/snmptrapd.service.d/` and edit
the file `/etc/systemd/system/snmptrapd.service.d/mibs.conf` and add
the following content. You may want to tweak to add vendor directories
for devices you care about (in addition to or instead of cisco).
```ini
[Service]
@ -31,7 +36,8 @@ In `/etc/snmp/snmptrapd.conf`, add something like the following:
traphandle default /opt/librenms/snmptrap.php
```
Along with any necessary configuration to receive the traps from your devices (community, etc.)
Along with any necessary configuration to receive the traps from your
devices (community, etc.)
Reload service files, enable, and start the snmptrapd service:
@ -43,15 +49,17 @@ sudo systemctl restart snmptrapd
### Event logging
You can configure generic event logging for snmp traps. This will log an event of the type trap for received traps.
These events can be utilized for alerting.
You can configure generic event logging for snmp traps. This will log
an event of the type trap for received traps. These events can be utilized for alerting.
In config.php
```php
$config['snmptraps']['eventlog'] = 'unhandled';
```
Valid options are:
- `unhandled` only unhandled traps will be logged
- `all` log all traps
- `none` no traps will create a generic event log (handled traps may still log events)
- `unhandled` only unhandled traps will be logged
- `all` log all traps
- `none` no traps will create a generic event log (handled traps may still log events)

View File

@ -4,64 +4,93 @@ path: blob/master/doc/
# Setting up services
Services within LibreNMS provides the ability to use Nagios plugins to perform additional monitoring outside of SNMP.
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 to be able to add it
to LibreNMS - localhost is a good one. This is needed in order for alerting to work properly.**
**These services are tied into an existing device so you need at least
one device to be able to add it to LibreNMS - localhost is a good
one. This is needed in order for alerting to work properly.**
## Pre installed plugins
Note: Plugins will only load if they are prefixed with "check_" and they have that prefix stripped out when displaying in the "Add Serice" GUI "Type" dropdown list.
Note: Plugins will only load if they are prefixed with "check_" and
they have that prefix stripped out when displaying in the "Add Serice"
GUI "Type" dropdown list.
Plugins come from two main places [pkg-nagios-plugins-contrib](https://github.com/bzed/pkg-nagios-plugins-contrib) and [monitoring-plugins](https://www.monitoring-plugins.org). This is where you can find the documentation for most, if not all of the plugins.
Plugins come from two main places
[pkg-nagios-plugins-contrib](https://github.com/bzed/pkg-nagios-plugins-contrib)
and [monitoring-plugins](https://www.monitoring-plugins.org). This is
where you can find the documentation for most, if not all of the plugins.
The plugins are bundled with the pre build VM images via the package `monitoring-plugins` in Ubuntu and `nagios-plugins-all` in CentOS.
The plugins are bundled with the pre build VM images via the package
`monitoring-plugins` in Ubuntu and `nagios-plugins-all` in CentOS.
## Setup
> Service checks is now distributed aware. If you run a distributed setup then you can now run
`services-wrapper.py` in cron instead of `check-services.php` across all polling nodes.
Service checks is now distributed aware. If you run a distributed
setup then you can now run `services-wrapper.py` in cron instead of
`check-services.php` across all polling nodes.
If you need to debug the output of services-wrapper.py then you can add `-d` to the end of the command - it is NOT recommended to do this in cron.
If you need to debug the output of services-wrapper.py then you can
add `-d` to the end of the command - it is NOT recommended to do this
in cron.
Firstly, install Nagios plugins however you would like, this could be via yum, apt-get or direct from source.
Firstly, install Nagios plugins however you would like, this could be
via yum, apt-get or direct from source.
Next, you need to enable the services within config.php with the following:
```php
$config['show_services'] = 1;
```
This will enable a new service menu within your navbar.
```php
$config['nagios_plugins'] = "/usr/lib/nagios/plugins";
```
This will point LibreNMS at the location of the nagios plugins - please ensure that any plugins you use are set to executable.
For example:
This will point LibreNMS at the location of the nagios plugins -
please ensure that any plugins you use are set to executable. For example:
```
chmod +x /usr/lib/nagios/plugins/*
```
Finally, you now need to add services-wrapper.py to the current cron file (/etc/cron.d/librenms typically) like:
Finally, you now need to add services-wrapper.py to the current cron
file (/etc/cron.d/librenms typically) like:
```bash
*/5 * * * * librenms /opt/librenms/services-wrapper.py 1
```
Now you can add services via the main Services link in the navbar, or via the 'Add Service' link within the device, services page.
Now you can add services via the main Services link in the navbar, or
via the 'Add Service' link within the device, services page.
Note that some services (procs, inodes, load and similar) will always poll the local LibreNMS server it's running on, regardless of which device you add it to.
Note that some services (procs, inodes, load and similar) will always
poll the local LibreNMS server it's running on, regardless of which
device you add it to.
## Performance data
By default, the check-services script will collect all performance data that the Nagios script returns and display each datasource on a separate graph. LibreNMS expects scripts to return using Nagios convention for the response message structure: [AEN200](https://nagios-plugins.org/doc/guidelines.html#AEN200)
By default, the check-services script will collect all performance
data that the Nagios script returns and display each datasource on a
separate graph. LibreNMS expects scripts to return using Nagios
convention for the response message structure:
[AEN200](https://nagios-plugins.org/doc/guidelines.html#AEN200)
However for some modules it would be better if some of this information was consolidated on a single graph.
An example is the ICMP check. This check returns: Round Trip Average (rta), Round Trip Min (rtmin) and Round Trip Max (rtmax).
However for some modules it would be better if some of this
information was consolidated on a single graph.
An example is the ICMP check. This check returns: Round Trip Average
(rta), Round Trip Min (rtmin) and Round Trip Max (rtmax).
These have been combined onto a single graph.
If you find a check script that would benefit from having some datasources graphed together, please log an issue on GitHub with the debug information from the script, and let us know which DS's should go together. Example below:
If you find a check script that would benefit from having some
datasources graphed together, please log an issue on GitHub with the
debug information from the script, and let us know which DS's should
go together. Example below:
```
./check-services.php -d
-- snip --
Nagios Service - 26
@ -80,34 +109,48 @@ If you find a check script that would benefit from having some datasources graph
OK u:0.00 s:0.00 r:40.67
RRD[update /opt/librenms/rrd/localhost/services-26.rrd N:0.016:0:0.044:0.009]
-- snip --
```
## Alerting
Services uses the Nagios Alerting scheme where:
0 = Ok,
1 = Warning,
2 = Critical,
```
0 = Ok,
1 = Warning,
2 = Critical,
```
To create an alerting rule to alert on service=critical, your alerting rule would look like:
To create an alerting rule to alert on service=critical, your alerting
rule would look like:
```
%services.service_status = "2"
```
## Debug
Change user to librenms for example
Change user to librenms for example
```
su - librenms
```
then you can run the following command to help troubleshoot services.
then you can run the following command to help troubleshoot services.
```
./check-services.php -d
```
## Service checks polling logic
Service check is skipped when the associated device is not pingable, and an appropriate entry is populated in the event log.
Service check is polled if it's `IP address` parameter is not equal to associated device's IP address, even when the associated device is not pingable.
Service check is skipped when the associated device is not pingable,
and an appropriate entry is populated in the event log. Service check
is polled if it's `IP address` parameter is not equal to associated
device's IP address, even when the associated device is not pingable.
To override the default logic and always poll service checks, you can disable ICMP testing for any device by switching `Disable ICMP Test` setting (Edit -> Misc) to ON.
To override the default logic and always poll service checks, you can
disable ICMP testing for any device by switching `Disable ICMP Test`
setting (Edit -> Misc) to ON.
Service checks will never be polled on disabled devices.

View File

@ -1,20 +1,24 @@
source: Extensions/Smokeping.md
path: blob/master/doc/
# Smokeping integration
[SmokePing](https://oss.oetiker.ch/smokeping/) is a tool which lets us keep track of network latency, and visualise this through RRD graphs.
[SmokePing](https://oss.oetiker.ch/smokeping/) is a tool which lets us
keep track of network latency, and visualise this through RRD graphs.
LibreNMS has support for both new and pre-existing SmokePing installations.
LibreNMS has support for both new and pre-existing SmokePing installations.
For new installations, we can use the included `scripts/gen_smokeping.php` script to generate a Smokeping config file.
For new installations, we can use the included
`scripts/gen_smokeping.php` script to generate a Smokeping config file.
## New Smokeping installation
## New Smokeping installation
### Install and integrate Smokeping - Debian/Ubuntu
### Install and integrate Smokeping - Debian/Ubuntu ###
This guide assumes you have already [installed librenms](http://docs.librenms.org/Installation/Installing-LibreNMS/), and is working with either **Apache** or **nginx**.
This guide assumes you have already [installed
librenms](http://docs.librenms.org/Installation/Installing-LibreNMS/),
and is working with either **Apache** or
**nginx**.
Note: You may need to install `fcgiwrap` as well (at least with `nginx`).
@ -26,9 +30,11 @@ sudo apt update && sudo apt install smokeping
## Configure SmokePing
Smokeping has several configuration files. By default, these are located in `/etc/smokeping/config.d/`
Smokeping has several configuration files. By default, these are
located in `/etc/smokeping/config.d/`
Edit the `General` configuration file's **Owner** and **contact**, and **cgiurl hostname** details:
Edit the `General` configuration file's **Owner** and **contact**, and
**cgiurl hostname** details:
```bash
nano /etc/smokeping/config.d/General
@ -45,19 +51,23 @@ Add the following line to `/etc/smokeping/config` config file:
@include /etc/smokeping/config.d/librenms.conf
```
We will generate the conf file in the next step.
We will generate the conf file in the next step.
### Generate LibreNMS list of Smokeping Nodes
LibreNMS comes equipped with a script which exports our list of nodes from LibreNMS into a configuration file in the format required by Smokeping.
LibreNMS comes equipped with a script which exports our list of nodes
from LibreNMS into a configuration file in the format required by
Smokeping.
To generate the config file once:
To generate the config file once:
```bash
(echo "+ LibreNMS"; php -f /opt/librenms/scripts/gen_smokeping.php) | sudo tee /etc/smokeping/config.d/librenms.conf
```
**However**, it is more desirable to set up a cron job which regenerates our list of nodes and adds these into Smokeping. You can add the following to the end of your librenms cron job, e.g. `nano /etc/cron.d/librenms`
**However**, it is more desirable to set up a cron job which
regenerates our list of nodes and adds these into Smokeping. You can
add the following to the end of your librenms cron job, e.g. `nano /etc/cron.d/librenms`
**Ubuntu 16.04** Sample cron (will run daily at 00:05) :
@ -80,8 +90,10 @@ menu = Top
title = Network Latency Grapher
```
Which can cause Smokeping to not start. `echo "+ LibreNMS"` prepends this in our smokeping config file. We could remove the above from the gen_smokeping script, however this may cause issues with LibreNMS failing to update with `daily.sh` due config files being modified.
Which can cause Smokeping to not start. `echo "+ LibreNMS"` prepends
this in our smokeping config file. We could remove the above from the
gen_smokeping script, however this may cause issues with LibreNMS
failing to update with `daily.sh` due config files being modified.
## Configure LibreNMS
@ -92,21 +104,22 @@ Edit `/opt/librenms/config.php` and add the following:
```php
$config['smokeping']['dir'] = '/var/lib/smokeping'; // Ubuntu 16.04 and newer Location
#$config['smokeping']['dir'] = '/opt/smokeping/data';
$config['smokeping']['pings'] = 20; // should be equal to "pings" in your smokeping config
$config['smokeping']['pings'] = 20; // should be equal to "pings" in your smokeping config
$config['smokeping']['integration'] = true;
```
## Configure web server
This section covers the required configuration for your web server of choice. This covers the required configuration for either Apache or Nginx.
This section covers the required configuration for your web server of
choice. This covers the required configuration for either Apache or Nginx.
### Apache Configuration
Smokeping should automatically install an Apache config file in `/etc/apache2/conf-available/`. Verify this using :
Smokeping should automatically install an Apache config file in
`/etc/apache2/conf-available/`. Verify this using :
```bash
librenms@librenms:~/scripts$ ls /etc/apache2/conf-available/ | grep smokeping
librenms@librenms:~/scripts$ ls /etc/apache2/conf-available/ | grep smokeping
smokeping.conf
```
@ -120,15 +133,15 @@ After creating the symlink, restart Apache with `sudo systemctl apache2 restart`
You should be able to load the Smokeping web interface at `http://yourhost/cgi-bin/smokeping.cgi`
### Nginx Configuration
### Nginx Configuration
This section assumes you have configured LibreNMS with Nginx as specified in [Configure Nginx](https://docs.librenms.org/Installation/Installation-Ubuntu-1804-Nginx/).
This section assumes you have configured LibreNMS with Nginx as
specified in [Configure Nginx](https://docs.librenms.org/Installation/Installation-Ubuntu-1804-Nginx/).
Add the following configuration to your `/etc/nginx/conf.d/librenms` config file.
Add the following configuration to your `/etc/nginx/conf.d/librenms` config file.
The following will configure Nginx to respond to `http://yourlibrenms/smokeping`:
```
#Browsing to `http://librenms.xxx/smokeping/` should bring up the smokeping web interface
@ -163,13 +176,16 @@ The following will configure Nginx to respond to `http://yourlibrenms/smokeping`
}
```
After saving the config file, verify your Nginx config file syntax is OK with `sudo nginx -t`, then restart Nginx with `sudo systemctl restart nginx`
After saving the config file, verify your Nginx config file syntax is
OK with `sudo nginx -t`, then restart Nginx with `sudo systemctl restart nginx`
You should be able to load the Smokeping web interface at `http://yourhost/smokeping`
#### Nginx Password Authentification
You can use the purpose-made htpasswd utility included in the apache2-utils package (Nginx password files use the same format as Apache). You can install it on Ubuntu with
You can use the purpose-made htpasswd utility included in the
apache2-utils package (Nginx password files use the same format as
Apache). You can install it on Ubuntu with
```
apt install apache2-utils
@ -181,7 +197,7 @@ After that you need to create password for your user
htpasswd -c /etc/nginx/.htpasswd USER
```
You can verify your user and password with
You can verify your user and password with
```
cat /etc/nginx/.htpasswd
@ -199,9 +215,9 @@ Then you just need to add to your config `auth_basic` parameters
}
```
### Start SmokePing
### Start SmokePing
Use the below commands to start and verify smokeping is running.
Use the below commands to start and verify smokeping is running.
**Ubuntu 14.04:** `sudo service smokeping start`
@ -211,27 +227,29 @@ Verify: `sudo service smokeping status`
Verify: `sudo systemctl status smokeping`
## Verify in LibreNMS
Within LibreNMS, you should now have a new device sub-tab called Ping.
Within LibreNMS, you should now have a new device sub-tab called Ping
--------------
# Pre-Existing Smokeping Installation
The following section covers the requirements for an existing SmokePing installation. The primary difference is this section does not cover using the LibreNMS Smokeping config script, and assumes an existing Smokeping server is set up and working correctly.
The following section covers the requirements for an existing
SmokePing installation. The primary difference is this section does
not cover using the LibreNMS Smokeping config script, and assumes an
existing Smokeping server is set up and working correctly.
In terms of configuration, simply add the location of where smokeping
data such as RRD files are stored. If this is on a separate server,
ensure there is a mount point reachable, along with the server's hostname.
In terms of configuration, simply add the location of where smokeping data such as RRD files are stored. If this is on a separate server, ensure there is a mount point reachable, along with the server's hostname.
**Note:** The location should be the RRD root folder, NOT the sub-directory such as network.
**Note:** The location should be the RRD root folder, NOT the
sub-directory such as network.
```php
$config['smokeping']['dir'] = '/var/lib/smokeping'; // Ubuntu 16.04 and newer Location
#$config['smokeping']['dir'] = '/opt/smokeping/data';
$config['smokeping']['pings'] = 20; // should be equal to "pings" in your smokeping config
$config['smokeping']['pings'] = 20; // should be equal to "pings" in your smokeping config
$config['smokeping']['integration'] = true;
```
@ -239,9 +257,10 @@ You should now see a new tab in your device page called ping.
# Issues
### `ERROR: /etc/smokeping/config.d/pathnames, line 1: File '/usr/sbin/sendmail' does not exist`
## `ERROR: /etc/smokeping/config.d/pathnames, line 1: File '/usr/sbin/sendmail' does not exist`
If you got this error at the end of the installation, simply edit smokeping's config file like so:
If you got this error at the end of the installation, simply edit
smokeping's config file like so:
```diff
nano /etc/smokeping/config.d/pathnames
@ -250,30 +269,38 @@ nano /etc/smokeping/config.d/pathnames
+#sendmail = /usr/sbin/sendmail
```
### Smokeping and RRDCached ###
## Smokeping and RRDCached
If you are using the standard smokeping data dir (`/etc/smokeping/data`) then you may need to alter the rrdcached config slightly.
If you are using the standard smokeping data dir
(`/etc/smokeping/data`) then you may need to alter the rrdcached
config slightly.
In the standard configuration the -B argument may have been used to restrict rrdcached to read only from a single base dir.
In the standard configuration the -B argument may have been used to
restrict rrdcached to read only from a single base dir.
If this is true, when you try an open one of the smokeping graphs from within LibreNMS you will see something like this error at the end of the rrdcached command:
If this is true, when you try an open one of the smokeping graphs from
within LibreNMS you will see something like this error at the end of
the rrdcached command:
```bash
ERROR: rrdcached: /var/lib/smokeping/<device name>.rrd: Permission denied
```
You will need to either change the dir in which smokeping saves its rrd files to be the same as the main librenms dir or you can remove the -B argument from the rrdcached config to allow it to read from more than one dir.
You will need to either change the dir in which smokeping saves its
rrd files to be the same as the main librenms dir or you can remove
the -B argument from the rrdcached config to allow it to read from
more than one dir.
To remove the -B switch:
```bash
sudo nano /etc/default/rrdcached
```
then find:
```bash
BASE_OPTIONS=
```
If -B is in the list of arguments delete it.

View File

@ -1,8 +1,14 @@
source: Extensions/Sub-Directory.md
path: blob/master/doc/
To run LibreNMS under a subdirectory on your Apache server, the directives for the LibreNMS directory are placed in the base server configuration, or in a virtual host
container of your choosing. If using a virtual host, place the directives in the file where the virtual host is configured. If using the base server on RHEL distributions
(CentOS, Scientific Linux, etc.) the directives can be placed in `/etc/httpd/conf.d/librenms.conf`. For Debian distributions (Ubuntu, etc.) place the directives in
To run LibreNMS under a subdirectory on your Apache server, the
directives for the LibreNMS directory are placed in the base server
configuration, or in a virtual host container of your choosing. If
using a virtual host, place the directives in the file where the
virtual host is configured. If using the base server on RHEL
distributions (CentOS, Scientific Linux, etc.) the directives can be
placed in `/etc/httpd/conf.d/librenms.conf`. For Debian distributions
(Ubuntu, etc.) place the directives in
`/etc/apache2/sites-available/default`.
```apache
@ -16,9 +22,10 @@ Alias /librenms /opt/librenms/html
</Directory>
```
The `RewriteBase` directive in `html/.htaccess` must be rewritten to reference the subdirectory name. Assuming LibreNMS is running at http://example.com/librenms/,
you will need to change `RewriteBase /` to `RewriteBase /librenms`.
The `RewriteBase` directive in `html/.htaccess` must be rewritten to
reference the subdirectory name. Assuming LibreNMS is running at
http://example.com/librenms/, you will need to change `RewriteBase /`
to `RewriteBase /librenms`.
Finally, set
`APP_URL=/librenms/` in .env and
`$config["base_url"] = '/librenms/';` in config.php.
Finally, set `APP_URL=/librenms/` in .env and `$config["base_url"] =
'/librenms/';` in config.php.

View File

@ -328,7 +328,7 @@ By Default windows has no native way to send logs to a remote syslog server.
Using this how to you can download Datagram-Syslog Agent to send logs
to a remote syslog server (LibreNMS).
#### Note
### Note
Keep in mind you can use any agent or program to send the logs. We are
just using this Datagram-Syslog Agent for this example.

View File

@ -3,42 +3,55 @@ path: blob/master/doc/
# About
Over the last couple of years, the primary attack vector for internet accounts has been static passwords.
Therefore static passwords are no longer sufficient to protect unauthorized access to accounts.
Two Factor Authentication adds a variable part in authentication procedures.
A user is now required to supply a changing 6-digit passcode in addition to it's password to obtain access to the account.
Over the last couple of years, the primary attack vector for internet
accounts has been static passwords. Therefore static passwords are no
longer sufficient to protect unauthorized access to accounts. Two
Factor Authentication adds a variable part in authentication
procedures. A user is now required to supply a changing 6-digit
passcode in addition to it's password to obtain access to the account.
LibreNMS has a RFC4226 conform implementation of both Time and Counter based One-Time-Passwords.
It also allows the administrator to configure a throttle time to enforce after 3 failures exceeded. Unlike RFC4226 suggestions, this throttle time will not stack on the amount of failures.
LibreNMS has a RFC4226 conform implementation of both Time and Counter
based One-Time-Passwords. It also allows the administrator to
configure a throttle time to enforce after 3 failures exceeded. Unlike
RFC4226 suggestions, this throttle time will not stack on the amount of failures.
# Types
In general, these two types do not differ in algorithmic terms.
The types only differ in the variable being used to derive the passcodes from.
The underlying HMAC-SHA1 remains the same for both types, security advantages or disadvantages of each are discussed further down.
The underlying HMAC-SHA1 remains the same for both types, security
advantages or disadvantages of each are discussed further down.
## Timebased One-Time-Password (TOTP)
Like the name suggests, this type uses the current Time or a subset of it to generate the passcodes.
These passcodes solely rely on the secrecy of their Secretkey in order to provide passcodes.
An attacker only needs to guess that Secretkey and the other variable part is any given time, presumably the time upon login.
RFC4226 suggests a resynchronization attempt in case the passcode mismatches, providing the attacker a range of up to +/- 3 Minutes to create passcodes.
Like the name suggests, this type uses the current Time or a subset of
it to generate the passcodes. These passcodes solely rely on the
secrecy of their Secretkey in order to provide passcodes. An attacker
only needs to guess that Secretkey and the other variable part is any
given time, presumably the time upon login. RFC4226 suggests a
resynchronization attempt in case the passcode mismatches, providing
the attacker a range of up to +/- 3 Minutes to create passcodes.
## Counterbased One-Time-Password (TOTP)
This type uses an internal counter that needs to be in sync with the server's counter to successfully authenticate the passcodes.
The main advantage over timebased OTP is the attacker doesn't only need to know the Secretkey but also the server's Counter in order to create valid passcodes.
RFC4226 suggests a resynchronization attempt in case the passcode mismatches, providing the attacker a range of up to +4 increments from the actual counter to create passcodes.
This type uses an internal counter that needs to be in sync with the
server's counter to successfully authenticate the passcodes. The main
advantage over timebased OTP is the attacker doesn't only need to know
the Secretkey but also the server's Counter in order to create valid
passcodes. RFC4226 suggests a resynchronization attempt in case the
passcode mismatches, providing the attacker a range of up to +4
increments from the actual counter to create passcodes.
# Configuration
Enable Two-Factor:
```php
$config['twofactor'] = true;
```
Set throttle-time (in seconds):
```php
$config['twofactor_lock'] = 300;
```
@ -48,6 +61,7 @@ $config['twofactor_lock'] = 300;
These steps imply that TwoFactor has been enabled in your `config.php`
Create a Two-Factor key:
- Go to 'My Settings' (/preferences/)
- Choose TwoFactor type
- Click on 'Generate TwoFactor Secret Key'
@ -59,6 +73,7 @@ Create a Two-Factor key:
Installation guides for Google Authenticator can be found [here](https://support.google.com/accounts/answer/1066447?hl=en).
Usage:
- Create a key like described above
- Scan provided QR or click on 'Manual' and type down the Secret
- On next login, enter the passcode that the App provides

View File

@ -1,24 +1,28 @@
source: Extensions/Varnish.md
path: blob/master/doc/
# Varnish Installation Guide #
# Varnish Installation Guide
This document explains how to install Varnish Reverse Proxy for LibreNMS.
Varnish is caching software that sits logically between an HTTP client
and an HTTP server. Varnish caches HTTP responses from the HTTP
server. If an HTTP request can not be responded to by the Varnish
cache it directs the request to the HTTP Server. This type of HTTP
caching is called a reverse proxy server. Caching your HTTP server can
decrease page load times significantly.
Varnish is caching software that sits logically between an HTTP client and an HTTP server. Varnish caches HTTP responses from the HTTP server. If an HTTP request can not be responded to by the Varnish cache it directs the request to the HTTP Server. This type of HTTP caching is called a reverse proxy server. Caching your HTTP server can decrease page load times significantly.
<br><br>
##### <center>Simplified block diagram of an Apache HTTP server with Varnish 4.0 Reverse Proxy.</center> #####
# Simplified block diagram of an Apache HTTP server with Varnish 4.0 Reverse Proxy
![Block Diagram 1](http://docs.librenms.org/img/varnish_block.png)
### CentOS 7 Varnish Installation ###
# CentOS 7 Varnish Installation
In this example we will assume your Apache 2.4.X HTTP server is working and
configured to process HTTP requests on port 80. If not, please see
[Installing LibreNMS](http://librenms.readthedocs.org/Installation/Installing-CentOS-7-Apache)
#### Install Varnish 4.0 RPM ####
# Install Varnish 4.0 RPM
- Enable the Varnish CentOS 7 repo and install
@ -35,7 +39,7 @@ By default Varnish listens for HTTP requests on port 6081.
firewall-cmd --zone=public --add-port=6081/tcp
```
#### Test Varnish ####
# Test Varnish
- Start Varnish
@ -43,7 +47,9 @@ firewall-cmd --zone=public --add-port=6081/tcp
systemctl start varnish
```
Using a web browser navigate to <server ip addr>:6081 or 127.0.0.1:6081. You should see a Varnish error message, this shows that Varnish is working. Example error message:
Using a web browser navigate to <server ip addr>:6081 or
127.0.0.1:6081. You should see a Varnish error message, this shows
that Varnish is working. Example error message:
```ssh
Error 503 Backend fetch failed
@ -58,26 +64,32 @@ Varnish cache server
```
#### Edit Varnish Parameters ####
# Edit Varnish Parameters
Now we need to configure Varnish to listen to HTTP requests on port 80 and
relay those requests to the Apache HTTP server on port 8080 (see block diagram).
- Stop Varnish.
```bash
systemctl stop varnish
```
- Create a back-up of varnish.params just in case you make a mistake.
```bash
cp /etc/varnish/varnish.params /etc/varnish/varnish.params.bak
```
- Edit the varnish.params config.
```bash
vim /etc/varnish/varnish.params
```
Set the VCL location, IP address, port, and cache location and size. `malloc` sets the cache location to RAM, and `512M` sets the cache size to 512MB.
Set the VCL location, IP address, port, and cache location and
size. `malloc` sets the cache location to RAM, and `512M` sets the
cache size to 512MB.
```vcl
VARNISH_LISTEN_ADDRESS=192.168.1.10
@ -123,11 +135,12 @@ VARNISH_GROUP=varnish
DAEMON_OPTS="-p thread_pool_min=5 -p thread_pool_max=500 -p thread_pool_timeout=300"
```
#### Configure Apache for Varnish ####
# Configure Apache for Varnish
Edit librenms.conf and modify the Apache Virtual Host listening port.
- Modify:`<VirtualHost *:80>` to: `<VirtualHost *:8080>`
```bash
vim /etc/httpd/conf.d/librenms.conf
```
@ -135,15 +148,18 @@ vim /etc/httpd/conf.d/librenms.conf
Varnish can not share a port with Apache. Change the Apache listening port to 8080.
- Modify:`Listen 80` to:`Listen 8080`
```bash
vim /etc/httpd/conf/httpd.conf
```
- Create the librenms.vcl
```bash
cd /etc/varnish
touch librenms.vcl
```
- Set ownership and permissions for Varnish files.
```bash
@ -156,6 +172,7 @@ Edit the librenms.vcl.
```bash
vim librenms.vcl
```
Paste example VCL config, read config comments for more information.
```vcl
@ -238,13 +255,17 @@ sub vcl_deliver {
```
- Reload rules to remove the temporary port rule we added earlier.
```bash
firewall-cmd --reload
```
Varnish caching does not take effect immediately. You will need to browse the LibreNMS website to build up the cache.
Varnish caching does not take effect immediately. You will need to
browse the LibreNMS website to build up the cache.
Use the command `varnishstat` to monitor Varnish caching. Over time you should see 'MAIN.cache_hit' and 'MAIN.client_req' increase. With the above VCL the hit to request ratio is approximately 84%.
Use the command `varnishstat` to monitor Varnish caching. Over time
you should see 'MAIN.cache_hit' and 'MAIN.client_req' increase. With
the above VCL the hit to request ratio is approximately 84%.
- Session based VCL (coming soon)

View File

@ -2,70 +2,101 @@ source: Extensions/Weathermap.md
path: blob/master/doc/
# Network-WeatherMap with LibreNMS
Integrating LibreNMS with Network-Weathermap, allows you to build network maps to help visulaize network traffic flow rates.
[Link](https://network-weathermap.com/) to Network-Wearthermap Offical Website
### Prerequisites
Integrating LibreNMS with Network-Weathermap, allows you to build network
maps to help visulaize network traffic flow rates.
[Link](https://network-weathermap.com/) to Network-Wearthermap Offical
Website
## Prerequisites
Network-WeatherMap requires php pear to work.
### Installing Network-WeatherMap
## Installing Network-WeatherMap
### Step 1.
Extract to your LibreNMS plugins directory `/opt/librenms/html/plugins` so you should see something like `/opt/librenms/html/plugins/Weathermap/`
The best way to do this is via git. Go to your install directory and then `/opt/librenms/html/plugins`
## Step 1
Extract to your LibreNMS plugins directory `/opt/librenms/html/plugins`
so you should see something like `/opt/librenms/html/plugins/Weathermap/`
The best way to do this is via git. Go to your install directory and
then `/opt/librenms/html/plugins`
Enter:
`git clone https://github.com/librenms-plugins/Weathermap.git`
### Step 2.
Inside the html/plugins directory, change the ownership of the Weathermap directory by typing `chown -R librenms:librenms Weathermap/`
## Step 2
Inside the html/plugins directory, change the ownership of the
Weathermap directory by typing `chown -R librenms:librenms Weathermap/`
Make the configs directory writeable `chmod 775 /opt/librenms/html/plugins/Weathermap/configs`
Note if you are using SELinux you need to input the following command `chcon -R -t httpd_cache_t Weathermap/`
### Step 3.
Enable the cron process by editing your current LibreNMS cron file (typically /etc/cron.d/librenms) and add the following:
LibreNMS: `*/5 * * * * librenms /opt/librenms/html/plugins/Weathermap/map-poller.php >> /dev/null 2>&1`
### Step 4.
Note if you are using SELinux you need to input the following
command `chcon -R -t httpd_cache_t Weathermap/`
## Step 3
Enable the cron process by editing your current LibreNMS cron file
(typically /etc/cron.d/librenms) and add the following:
```
*/5 * * * * librenms /opt/librenms/html/plugins/Weathermap/map-poller.php >> /dev/null 2>&1
```
## Step 4
Enable the plugin from LibreNMS Web UI in OverView ->Plugins -> Plugin Admin menu.
### Step 5.
## Step 5
Now you should see Weathermap Overview -> Plugins -> Weathermap
Create your maps, please note when you create a MAP, please click Map Style, ensure Overlib is selected for HTML Style and click submit.
Create your maps, please note when you create a MAP, please click Map
Style, ensure Overlib is selected for HTML Style and click submit.
Also, ensure you set an output image filename and output HTML filename in Map Properties.
I'd recommend you use the output folder as this is excluded from git updates (i.e enter output/mymap.png and output/mymap.html).
I'd recommend you use the output folder as this is excluded from git
updates (i.e enter output/mymap.png and output/mymap.html).
Optional: If your install is in another directory than standard, set `$basehref` within `map-poller.php`.
Optional: If your install is in another directory than standard, set
`$basehref` within `map-poller.php`.
# WeatherMapper
### WeatherMapper
Automatically generate weathermaps from a LibreNMS database using WeatherMapper [Link](https://github.com/pblasquez/weathermapper)
![Example Network Weather Map](/img/network-weather-map.PNG)
### Adding your Network Weathermaps to the Dashboards
# Adding your Network Weathermaps to the Dashboards
Once you have created your Network Weather Map you can add it to a dashboard page by doing the following.
Once you have created your Network Weather Map you can add it to a
dashboard page by doing the following.
### Step 1
When you create the Weathermap make sure to export as HTML and PNG you will need this for the out to the dashboard.
## Step 1
In the Weathermap Plugin page, you will see the output maps. `Right click` on one of the maps and click on `copy image address`.
When you create the Weathermap make sure to export as HTML and PNG you
will need this for the out to the dashboard.
In the Weathermap Plugin page, you will see the output maps. `Right
click` on one of the maps and click on `copy image address`.
Example URL: `http://yourlibrenms.org/plugins/Weathermap/output/yourmap.html`
## Step 2
### Step 2
Then go back to your Dashboard, create a new dashboard and give it a name. select the widget as *External Images*.
Then go back to your Dashboard, create a new dashboard and give it a
name. select the widget as *External Images*.
Give the Widget a Title.
The *Image URL* will need to be the address you copied but at the end remove the `.html` and replace it with `.png`
The *Image URL* will need to be the address you copied but at the end
remove the `.html` and replace it with `.png`
Example *Image URL* `http://yourlibrenms.org/plugins/Weathermap/output/yourmap.png`
The *Target URL* will be the URL you copied but with the `.html` at the end of the URL.
The *Target URL* will be the URL you copied but with the `.html` at
the end of the URL.
Example *Target URL* `http://yourlibrenms.org/plugins/Weathermap/output/yourmap.html`
Then Click on Set
You should now be able to see the Weathermap you have created in your list of dashboards. You could also add this to existing dashboards.
You should now be able to see the Weathermap you have created in your
list of dashboards. You could also add this to existing dashboards.
![Example Network Weathermap Dashboard](/img/network-weathermap-dashboard.png)

View File

@ -14,13 +14,13 @@ these addresses will be Geocoded by Google and stored in the database.
Location resolution happens as follows
1. If `device['location']` contains `[lat, lng]` (note the square
brackets), that is used
1. If there is a location overide for the device in the WebUI and it
contains `[lat, lng]` (note the square brackets), that is used.
1. Attempt to resolve lat, lng using `$config['geoloc']['engine']`
1. Properly formatted addresses in sysLocation or sysLocation
override, under device settings.
1. If `device['location']` contains `[lat, lng]` (note the square
brackets), that is used
1. If there is a location overide for the device in the WebUI and it
contains `[lat, lng]` (note the square brackets), that is used.
1. Attempt to resolve lat, lng using `$config['geoloc']['engine']`
1. Properly formatted addresses in sysLocation or sysLocation
override, under device settings.
Example:
@ -65,8 +65,9 @@ $config['leaflet']['tile_url'] = 'localhost.com';
$config['map']['engine'] = "leaflet";
$config['leaflet']['default_lat'] = "51.981074";
$config['leaflet']['default_lng'] = "5.350342";
$config['leaflet']['default_zoom'] = 8;
$config['leaflet']['group_radius'] = 1; // Device grouping radius in KM default 80KM
$config['leaflet']['default_zoom'] = 8;
// Device grouping radius in KM default 80KM
$config['leaflet']['group_radius'] = 1;
```
# Geocode engine config
@ -88,7 +89,6 @@ Bing:
Pros: free, no credit card required, accurate
Cons: Microsoft(debatable)
# Jquery-Mapael config
Further custom options are available to load different maps of the

View File

@ -15,7 +15,7 @@ like Grafana for graphing.
Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
RRD will continue to function normally so LibreNMS itself should
continue to function normally.

View File

@ -320,7 +320,7 @@ cd /opt/librenms
```
There are various options for getting help listed on the LibreNMS web
site: https://www.librenms.org/#support
site: <https://www.librenms.org/#support>
# What next?

View File

@ -103,7 +103,7 @@ snmpd restart` will activate this config.
In `/etc/php5/apache2/php.ini` and `/etc/php5/cli/php.ini`, ensure
date.timezone is set to your preferred time zone. See
< http://php.net/manual/en/timezones.php> for a list of
<http://php.net/manual/en/timezones.php> for a list of
supported timezones. Valid examples are: "America/New York",
"Australia/Brisbane", "Etc/UTC".

View File

@ -87,7 +87,7 @@ systemctl restart mysql
## Configure and Start PHP-FPM
Ensure date.timezone is set in php.ini to your preferred time zone.
See http://php.net/manual/en/timezones.php for a list of supported
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".