diff --git a/doc/Extensions/Agent-Setup.md b/doc/Extensions/Agent-Setup.md index 843f768c0e..ddf84b02ff 100644 --- a/doc/Extensions/Agent-Setup.md +++ b/doc/Extensions/Agent-Setup.md @@ -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. + diff --git a/doc/Extensions/Applications.md b/doc/Extensions/Applications.md index 987d0534bb..1e73fbca2b 100644 --- a/doc/Extensions/Applications.md +++ b/doc/Extensions/Applications.md @@ -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 diff --git a/doc/Extensions/Authentication.md b/doc/Extensions/Authentication.md index 1f1b52d05f..ca9feffe2e 100644 --- a/doc/Extensions/Authentication.md +++ b/doc/Extensions/Authentication.md @@ -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'; diff --git a/doc/Extensions/Auto-Discovery.md b/doc/Extensions/Auto-Discovery.md index 4a1e5b057e..30d6edfd99 100644 --- a/doc/Extensions/Auto-Discovery.md +++ b/doc/Extensions/Auto-Discovery.md @@ -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] diff --git a/doc/Extensions/Billing-Module.md b/doc/Extensions/Billing-Module.md index ef7b8c135c..c458824e97 100644 --- a/doc/Extensions/Billing-Module.md +++ b/doc/Extensions/Billing-Module.md @@ -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. diff --git a/doc/Extensions/Component.md b/doc/Extensions/Component.md index d80682080c..28352e6c02 100644 --- a/doc/Extensions/Component.md +++ b/doc/Extensions/Component.md @@ -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 = ""` - 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 = ""` - 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` diff --git a/doc/Extensions/Customizing-the-Web-UI.md b/doc/Extensions/Customizing-the-Web-UI.md index ca05d16fdc..2661e10b66 100644 --- a/doc/Extensions/Customizing-the-Web-UI.md +++ b/doc/Extensions/Customizing-the-Web-UI.md @@ -8,6 +8,7 @@ path: blob/master/doc/ Create the file `resources/views/menu/custom.blade.php` Example contents: + ```blade
  • @@ -28,15 +29,16 @@ Example contents:
    • ``` - - + ## 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:` diff --git a/doc/Extensions/Dashboards.md b/doc/Extensions/Dashboards.md index f634f8dcc6..8c7d246d9d 100644 --- a/doc/Extensions/Dashboards.md +++ b/doc/Extensions/Dashboards.md @@ -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 ``` + 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: + +- +- diff --git a/doc/Extensions/Dell-OpenManage.md b/doc/Extensions/Dell-OpenManage.md index 349db8ded1..ee31661755 100644 --- a/doc/Extensions/Dell-OpenManage.md +++ b/doc/Extensions/Dell-OpenManage.md @@ -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. diff --git a/doc/Extensions/Device-Groups.md b/doc/Extensions/Device-Groups.md index e58b6d551b..4d6965524e 100644 --- a/doc/Extensions/Device-Groups.md +++ b/doc/Extensions/Device-Groups.md @@ -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 `. +If you already know the entity you want, you can browse around inside +MySQL using `show tables` and `desc `. -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`. diff --git a/doc/Extensions/Dispatcher-Service.md b/doc/Extensions/Dispatcher-Service.md index 5ef73af09b..c5e09eb534 100644 --- a/doc/Extensions/Dispatcher-Service.md +++ b/doc/Extensions/Dispatcher-Service.md @@ -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 -#### 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 + 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 + (the +package may be updated and have a new version number). ``` apt install python3 python-mysqldb diff --git a/doc/Extensions/Distributed-Poller.md b/doc/Extensions/Distributed-Poller.md index 6f30ab5755..57c851821f 100644 --- a/doc/Extensions/Distributed-Poller.md +++ b/doc/Extensions/Distributed-Poller.md @@ -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 - ``` diff --git a/doc/Extensions/Fast-Ping-Check.md b/doc/Extensions/Fast-Ping-Check.md index 7e73738b00..d91a3283a0 100644 --- a/doc/Extensions/Fast-Ping-Check.md +++ b/doc/Extensions/Fast-Ping-Check.md @@ -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; diff --git a/doc/Extensions/Gateone.md b/doc/Extensions/Gateone.md index ee34857d72..39e170fc08 100644 --- a/doc/Extensions/Gateone.md +++ b/doc/Extensions/Gateone.md @@ -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:// Timezone must be PHP supported timezones, available at: http://php.net/manual/en/timezones.php -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: + -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 ``` diff --git a/doc/Extensions/IRC-Bot-Extensions.md b/doc/Extensions/IRC-Bot-Extensions.md index c1943d1fe0..802d6ff4ae 100644 --- a/doc/Extensions/IRC-Bot-Extensions.md +++ b/doc/Extensions/IRC-Bot-Extensions.md @@ -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 -### Functions +## 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. -### Attributes +## 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`. -# Example! +# 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"; diff --git a/doc/Extensions/IRC-Bot.md b/doc/Extensions/IRC-Bot.md index 5ba5c6c207..7ff960750c 100644 --- a/doc/Extensions/IRC-Bot.md +++ b/doc/Extensions/IRC-Bot.md @@ -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 + diff --git a/doc/Extensions/Interface-Description-Parsing.md b/doc/Extensions/Interface-Description-Parsing.md index e836df19db..454d6678bf 100644 --- a/doc/Extensions/Interface-Description-Parsing.md +++ b/doc/Extensions/Interface-Description-Parsing.md @@ -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`` \ No newline at end of file +``//Add more distributions than just Debian based`` diff --git a/doc/Extensions/MIB-based-polling.md b/doc/Extensions/MIB-based-polling.md index ee72d46693..eb393eb570 100644 --- a/doc/Extensions/MIB-based-polling.md +++ b/doc/Extensions/MIB-based-polling.md @@ -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 -## 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/ + All MIBs used by MIB-based polling may be viewed at: - 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) + (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/ + - - 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/ + -### 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/ + - - 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: + +- 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 + - -## 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. diff --git a/doc/Extensions/Metric-Storage.md b/doc/Extensions/Metric-Storage.md index 0e37834765..c4b9cf7991 100644 --- a/doc/Extensions/Metric-Storage.md +++ b/doc/Extensions/Metric-Storage.md @@ -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) diff --git a/doc/Extensions/Network-Map.md b/doc/Extensions/Network-Map.md index 07faeed7cd..cd0ec2bf93 100644 --- a/doc/Extensions/Network-Map.md +++ b/doc/Extensions/Network-Map.md @@ -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": { diff --git a/doc/Extensions/Oxidized.md b/doc/Extensions/Oxidized.md index 20d53d9463..eb37695c19 100644 --- a/doc/Extensions/Oxidized.md +++ b/doc/Extensions/Oxidized.md @@ -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: ``` -### 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 - ``` - - \ No newline at end of file +``` +git cat-file -p +``` diff --git a/doc/Extensions/PeeringDB.md b/doc/Extensions/PeeringDB.md index f17007abd8..c84ea5b21b 100644 --- a/doc/Extensions/PeeringDB.md +++ b/doc/Extensions/PeeringDB.md @@ -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 diff --git a/doc/Extensions/Plugin-System.md b/doc/Extensions/Plugin-System.md index 0ee812648c..ff6270e64e 100644 --- a/doc/Extensions/Plugin-System.md +++ b/doc/Extensions/Plugin-System.md @@ -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): ``` ``` -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: + ``` ``` -### 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('
  • '.get_class().'
    • '); } ``` -* 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(''); } ``` - diff --git a/doc/Extensions/Proxmox.md b/doc/Extensions/Proxmox.md index dee901c50b..ebaa72b51b 100644 --- a/doc/Extensions/Proxmox.md +++ b/doc/Extensions/Proxmox.md @@ -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 diff --git a/doc/Extensions/RRDCached-Security.md b/doc/Extensions/RRDCached-Security.md index 99ec76b8c5..8b9159a09f 100644 --- a/doc/Extensions/RRDCached-Security.md +++ b/doc/Extensions/RRDCached-Security.md @@ -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` diff --git a/doc/Extensions/RRDCached.md b/doc/Extensions/RRDCached.md index 989a2b590b..a7f9c1f7fa 100644 --- a/doc/Extensions/RRDCached.md +++ b/doc/Extensions/RRDCached.md @@ -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/ diff --git a/doc/Extensions/RRDTune.md b/doc/Extensions/RRDTune.md index 70147a0db9..3578878f25 100644 --- a/doc/Extensions/RRDTune.md +++ b/doc/Extensions/RRDTune.md @@ -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 -p ` @@ -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. diff --git a/doc/Extensions/Rancid.md b/doc/Extensions/Rancid.md index c12715c9f3..60931b5f75 100644 --- a/doc/Extensions/Rancid.md +++ b/doc/Extensions/Rancid.md @@ -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 ` -> 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/'; diff --git a/doc/Extensions/SNMP-Proxy.md b/doc/Extensions/SNMP-Proxy.md index f7d6ceccfc..ab3f5dcc53 100644 --- a/doc/Extensions/SNMP-Proxy.md +++ b/doc/Extensions/SNMP-Proxy.md @@ -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 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 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. diff --git a/doc/Extensions/SNMP-Trap-Handler.md b/doc/Extensions/SNMP-Trap-Handler.md index 1c846cc047..a3a2195faa 100644 --- a/doc/Extensions/SNMP-Trap-Handler.md +++ b/doc/Extensions/SNMP-Trap-Handler.md @@ -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) diff --git a/doc/Extensions/Services.md b/doc/Extensions/Services.md index 83f4244462..5a4eaae3d8 100644 --- a/doc/Extensions/Services.md +++ b/doc/Extensions/Services.md @@ -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. diff --git a/doc/Extensions/Smokeping.md b/doc/Extensions/Smokeping.md index 605253e206..e302a24c14 100644 --- a/doc/Extensions/Smokeping.md +++ b/doc/Extensions/Smokeping.md @@ -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/.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. diff --git a/doc/Extensions/Sub-Directory.md b/doc/Extensions/Sub-Directory.md index 028ad2c47e..092fef3680 100644 --- a/doc/Extensions/Sub-Directory.md +++ b/doc/Extensions/Sub-Directory.md @@ -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 ``` -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. diff --git a/doc/Extensions/Syslog.md b/doc/Extensions/Syslog.md index d32cfc1123..c4917dac07 100644 --- a/doc/Extensions/Syslog.md +++ b/doc/Extensions/Syslog.md @@ -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. diff --git a/doc/Extensions/Two-Factor-Auth.md b/doc/Extensions/Two-Factor-Auth.md index 8cc6475f8c..05d58a889e 100644 --- a/doc/Extensions/Two-Factor-Auth.md +++ b/doc/Extensions/Two-Factor-Auth.md @@ -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 diff --git a/doc/Extensions/Varnish.md b/doc/Extensions/Varnish.md index b70a97f944..54e3532efb 100644 --- a/doc/Extensions/Varnish.md +++ b/doc/Extensions/Varnish.md @@ -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. -

    -#####
    Simplified block diagram of an Apache HTTP server with Varnish 4.0 Reverse Proxy.
    ##### +# 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 :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 :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:`` to: `` + ```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) diff --git a/doc/Extensions/Weathermap.md b/doc/Extensions/Weathermap.md index 914a427b6b..ccd2c1879b 100644 --- a/doc/Extensions/Weathermap.md +++ b/doc/Extensions/Weathermap.md @@ -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) diff --git a/doc/Extensions/World-Map.md b/doc/Extensions/World-Map.md index e8067ad516..ef467c34a0 100644 --- a/doc/Extensions/World-Map.md +++ b/doc/Extensions/World-Map.md @@ -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 diff --git a/doc/Extensions/metrics/OpenTSDB.md b/doc/Extensions/metrics/OpenTSDB.md index 1441b7792a..dce11e1215 100644 --- a/doc/Extensions/metrics/OpenTSDB.md +++ b/doc/Extensions/metrics/OpenTSDB.md @@ -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. diff --git a/doc/Installation/Installation-CentOS-7-Nginx.md b/doc/Installation/Installation-CentOS-7-Nginx.md index fb3f70c774..3a5a4ec4cb 100644 --- a/doc/Installation/Installation-CentOS-7-Nginx.md +++ b/doc/Installation/Installation-CentOS-7-Nginx.md @@ -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: # What next? diff --git a/doc/Installation/Installation-Ubuntu-1404-Apache.md b/doc/Installation/Installation-Ubuntu-1404-Apache.md index 000b4d7c9e..20fb84d84e 100644 --- a/doc/Installation/Installation-Ubuntu-1404-Apache.md +++ b/doc/Installation/Installation-Ubuntu-1404-Apache.md @@ -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 + for a list of supported timezones. Valid examples are: "America/New York", "Australia/Brisbane", "Etc/UTC". diff --git a/doc/Installation/Installation-Ubuntu-1804-Nginx.md b/doc/Installation/Installation-Ubuntu-1804-Nginx.md index df38e3dd46..cee3afd790 100644 --- a/doc/Installation/Installation-Ubuntu-1804-Nginx.md +++ b/doc/Installation/Installation-Ubuntu-1804-Nginx.md @@ -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 for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".