mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated WebUI config options in docs to support direct linking to installs (#15009)

Browse Source 
* Updated WebUI config options in docs to support direct linking to installs

* Reverted distributed polling config for hostname
This commit is contained in:
Neil Lathwood
2023-05-11 01:05:12 +01:00
committed by GitHub
parent 2f6904fb59
commit 778c83797d
25 changed files with 737 additions and 614 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
doc/Extensions/Authentication.md
View File

@@ -31,9 +31,10 @@ in config.php. Please note that only ONE module can be
enabled. LibreNMS doesn't support multiple authentication mechanisms at
the same time.
```php
$config['auth_mechanism'] = "mysql";
```
!!! setting "auth/general"
```bash
lnms config:set auth_mechanism mysql
```
## User levels and User account type
@@ -73,10 +74,13 @@ Enable debug output to troubleshoot issues
## MySQL Authentication
Config option: `mysql`
!!! setting "auth/general"
```bash
lnms config:set auth_mechanism mysql
```
This is default option with LibreNMS so you should have already have the configuration setup in your
environment file (.env).
This is default option with LibreNMS so you should have already have the following configuration setup
in your environment file (.env).
```dotenv
DB_HOST=HOSTNAME
@@ -87,21 +91,32 @@ DB_PASSWORD="DBPASS"
## Active Directory Authentication
Config option: `active_directory`
!!! setting "auth/general"
```bash
lnms config:set auth_mechanism active_directory
```
Install __php-ldap__ or __php8.1-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.
!!! setting "auth/ad"
```bash
lnms config:set auth_ad_check_certificates 0
```
this will ignore certificate errors.
### Require actual membership of the configured groups
If you set `$config['auth_ad_require_groupmembership']` to 1, the
!!! setting "auth/ad"
```bash
lnms config:set auth_ad_require_groupmembership 1
```
If you set `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
you may set `auth_ad_global_read` to 1 and all users will
have read only access unless otherwise specified.
### Old account cleanup
@@ -110,28 +125,28 @@ 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['active_directory']['users_purge']` otherwise old
Please ensure that you set the `authlog_purge` value to be
greater than `active_directory.users_purge` otherwise old
users won't be removed.
### Sample configuration
```php
$config['auth_mechanism'] = 'active_directory';
$config['auth_ad_url'] = 'ldaps://server.example.com'; // Set server(s), space separated. Prefix with ldaps:// for ssl
$config['auth_ad_domain'] = 'example.com';
$config['auth_ad_base_dn'] = 'dc=example,dc=com'; // groups and users must be under this dn
$config['auth_ad_check_certificates'] = true; // require a valid ssl certificate
$config['auth_ad_binduser'] = 'examplebinduser'; // bind user (non-admin)
$config['auth_ad_bindpassword'] = 'examplepassword'; // bind password
$config['auth_ad_timeout'] = 5; // time to wait before giving up (or trying the next server)
$config['auth_ad_debug'] = false; // enable for verbose debug messages
$config['active_directory']['users_purge'] = 30; // purge users who haven't logged in for 30 days.
$config['auth_ad_require_groupmembership'] = true; // false: allow all users to auth level 0
$config['auth_ad_groups']['ad-admingroup']['level'] = 10; // set the "AD AdminGroup" group to admin level
$config['auth_ad_groups']['ad-usergroup']['level'] = 5; // set the "AD UserGroup" group to global read only level
```
!!! setting "auth/general"
```bash
lnms config:set auth_mechanism active_directory
lnms config:set auth_ad_url ldaps://server.example.com
lnms config:set auth_ad_domain
lnms config:set auth_ad_base_dn dc=example,dc=com
lnms config:set auth_ad_check_certificates true
lnms config:set auth_ad_binduser examplebinduser
lnms config:set auth_ad_bindpassword examplepassword
lnms config:set auth_ad_timeout 5
lnms config:set auth_ad_debug false
lnms config:set active_directory.users_purge 30
lnms config:set auth_ad_require_groupmembership true
lnms config:set auth_ad_groups.ad-admingroup.level 10
lnms config:set auth_ad_groups.ad-usergroup.level 5
```
Replace `ad-admingroup` with your Active Directory admin-user group
and `ad-usergroup` with your standard user group. It is __highly
@@ -141,11 +156,12 @@ users, and the API will not work.
### Active Directory redundancy
You can set two Active Directory servers by editing the
`$config['auth_ad_url']` like this example:
`auth_ad_url` setting like this example:
```
$config['auth_ad_url'] = "ldaps://dc1.example.com ldaps://dc2.example.com";
```
!!! setting "auth/ad"
```bash
lnms config:set auth_ad_url "ldaps://dc1.example.com ldaps://dc2.example.com"
```
### Active Directory LDAP filters
@@ -153,10 +169,11 @@ You can add an LDAP filter to be ANDed with the builtin user filter (`(sAMAccoun
The defaults are:
```
$config['auth_ad_user_filter'] = "(objectclass=user)";
$config['auth_ad_group_filter'] = "(objectclass=group)";
```
!!! setting "auth/ad"
```
lnms config:set auth_ad_user_filter "(objectclass=user)"
lnms config:set auth_ad_group_filter "(objectclass=group)"
```
This yields `(&(objectclass=user)(sAMAccountName=$username))` for the
user filter and `(&(objectclass=group)(sAMAccountName=$group))` for
@@ -171,42 +188,46 @@ setsebool -P httpd_can_connect_ldap 1
## LDAP Authentication
Config option: `ldap`
!!! setting "auth/general"
```bash
lnms config:set auth_mechanism ldap
```
Install __php_ldap__ or __php7.0-ldap__, making sure to install the
same version as PHP.
### Standard config
```php
$config['auth_mechanism'] = 'ldap';
$config['auth_ldap_server'] = 'ldap.example.com'; // Set server(s), space separated. Prefix with ldaps:// for ssl
$config['auth_ldap_suffix'] = ',ou=People,dc=example,dc=com'; // appended to usernames
$config['auth_ldap_groupbase'] = 'ou=groups,dc=example,dc=com'; // all groups must be inside this
$config['auth_ldap_groups']['admin']['level'] = 10; // set admin group to admin level
$config['auth_ldap_groups']['pfy']['level'] = 5; // set pfy group to global read only level
$config['auth_ldap_groups']['support']['level'] = 1; // set support group as a normal user
```
!!! setting "auth/ldap"
```bash
lnms config:set auth_ldap_server ldap.example.com
lnms config:set auth_ldap_suffix ',ou=People,dc=example,dc=com'
lnms config:set auth_ldap_groupbase 'ou=groups,dc=example,dc=com'
lnms config:set auth_ldap_groups.admin.level 10
lnms config:set auth_ldap_groups.pfy.level 5
lnms config:set auth_ldap_groups.support.level 1
```
### Additional options (usually not needed)
```php
$config['auth_ldap_version'] = 3; # v2 or v3
$config['auth_ldap_port'] = 389; // 389 or 636 for ssl
$config['auth_ldap_starttls'] = True; // Enable TLS on port 389
$config['auth_ldap_prefix'] = 'uid='; // prepended to usernames
$config['auth_ldap_group'] = 'cn=groupname,ou=groups,dc=example,dc=com'; // generic group with level 0
$config['auth_ldap_groupmemberattr'] = 'memberUid'; // attribute to use to see if a user is a member of a group
$config['auth_ldap_groupmembertype'] = 'username'; // username type to find group members by, either username (default), fulldn or puredn
$config['auth_ldap_uid_attribute'] = 'uidnumber'; // attribute for unique id
$config['auth_ldap_timeout'] = 5; // time to wait before giving up (or trying the next server)
$config['auth_ldap_emailattr'] = 'mail'; // attribute for email address
$config['auth_ldap_attr.uid'] = 'uid'; // attribute to check username against
$config['auth_ldap_debug'] = false; // enable for verbose debug messages
$config['auth_ldap_userdn'] = true; // Uses a users full DN as the value of the member attribute in a group instead of member: username. (it’s member: uid=username,ou=groups,dc=domain,dc=com)
$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
$config['auth_ldap_wildcard_ou'] = false; // Search for user matching user name independently of OU set in auth_ldap_suffix. Useful if your users are in different OU. Bind username, if set, still user auth_ldap_suffix
```
!!! setting "auth/ldap"
```bash
lnms config:set auth_ldap_version 3
lnms config:set auth_ldap_port 389
lnms config:set auth_ldap_starttls true
lnms config:set auth_ldap_prefix 'uid='
lnms config:set auth_ldap_group 'cn=groupname,ou=groups,dc=example,dc=com'
lnms config:set auth_ldap_groupmemberattr memberUid
lnms config:set auth_ldap_groupmembertype username
lnms config:set auth_ldap_uid_attribute uidnumber
lnms config:set auth_ldap_timeout 5
lnms config:set auth_ldap_emailattr mail
lnms config:set auth_ldap_attr.uid uid
lnms config:set auth_ldap_debug false
lnms config:set auth_ldap_userdn true
lnms config:set auth_ldap_userlist_filter service=informatique
lnms config:set auth_ldap_wildcard_ou false
```
### LDAP bind user (optional)
@@ -214,50 +235,51 @@ 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';
```
!!! setting "auth/ldap"
```bash
lnms config:set auth_ldap_binduser ldapbind
lnms config:set auth_ldap_binddn 'CN=John.Smith,CN=Users,DC=MyDomain,DC=com'
lnms config:set auth_ldap_bindpassword password
```
### LDAP server redundancy
You can set two LDAP servers by editing the
`$config['auth_ldap_server']` like this example:
`auth_ldap_server` like this example:
```
$config['auth_ldap_server'] = "ldaps://dir1.example.com ldaps://dir2.example.com";
```
!!! setting "auth/ldap"
```bash
lnms config:set auth_ldap_server ldaps://dir1.example.com ldaps://dir2.example.com
```
An example config setup for use with Jumpcloud LDAP as a service is:
```php
$config['auth_mechanism'] = "ldap";
$config['auth_ldap_version'] = 3;
$config['auth_ldap_server'] = "ldap.jumpcloud.com"; #Set to ldaps://ldap.jumpcloud.com to enable LDAPS
$config['auth_ldap_port'] = 389; #Set to 636 if using LDAPS
$config['auth_ldap_prefix'] = "uid=";
$config['auth_ldap_suffix'] = ",ou=Users,o={id},dc=jumpcloud,dc=com";
$config['auth_ldap_groupbase'] = "ou=Users,o={id},dc=jumpcloud,dc=com";
$config['auth_ldap_groupmemberattr'] = "member";
$config['auth_ldap_groups'] = ['{group}' => ['level' => 10],];
$config['auth_ldap_userdn'] = true;
```
!!! setting "auth/ldap"
```bash
lnms config:set auth_mechanism ldap
lnms config:set auth_ldap_version 3
lnms config:set auth_ldap_server ldap.jumpcloud.com
lnms config:set auth_ldap_port 389
lnms config:set auth_ldap_prefix 'uid=';
lnms config:set auth_ldap_suffix ',ou=Users,o={id},dc=jumpcloud,dc=com'
lnms config:set auth_ldap_groupbase 'ou=Users,o={id},dc=jumpcloud,dc=com'
lnms config:set auth_ldap_groupmemberattr member
lnms config:set auth_ldap_groups.{group}.level 10
lnms config:set 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:
levels replace the `auth_ldap_groups` line with the following:
```php
$config['auth_ldap_groups'] = [
'{admin_group}' => ['level' => 10],
'{global_readonly_group}' => ['level' => 5],
];
```
!!! setting "auth/ldap"
```bash
lnms config:set auth_ldap_groups.{admin_group}.level 10]
lnms config:set auth_ldap_groups.global_readonly_group.level 5
```
### SELinux configuration
@@ -273,7 +295,7 @@ successfully. User level 1 is assigned by default to those accounts
unless radius sends a reply attribute with the correct userlevel.
You can change the default userlevel by setting
`$config['radius']['userlevel']` to something other than 1.
`radius.userlevel` to something other than 1.
The attribute `Filter-ID` is a standard Radius-Reply-Attribute (string) that
can be assigned a value which translates into a userlevel in LibreNMS.
@@ -284,8 +306,8 @@ The strings to send in `Filter-ID` reply attribute is *one* of the following:
- `librenms_role_admin` - Sets the value `5`, which is the administrator level.
- `librenms_role_global-read` - Sets the value `10`, which is the global read level.
LibreNMS will ignore any other strings sent in `Filter-ID` and revert to default userlevel that is set in `config.php`.
LibreNMS will ignore any other strings sent in `Filter-ID` and revert to default
userlevel that is set in your config.
```php
$config['radius']['hostname'] = 'localhost';
@@ -421,9 +443,10 @@ $config['auth_ldap_bindpassword'] = 'password';
## 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;
!!! setting "webui/graph"
```bash
lnms config:set allow_unauth_graphs_cidr ['127.0.0.1/32']
lnms config:set allow_unauth_graphs true
```
## Single Sign-on

38
doc/Extensions/Auto-Discovery.md
View File

@@ -43,19 +43,21 @@ any mixture of these.
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';
```
!!! setting "discovery/networks"
```bash
lnms config:set nets.+ '192.168.0.0/24'
lnms config:set nets.+ '172.2.4.0/22'
```
### 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:
```php
$config['autodiscovery']['nets-exclude'][] = '192.168.0.1/32';
```
!!! setting "discovery/networks"
```bash
lnms config:set autodiscovery.nets-exclude.+ '192.168.0.1/32'
```
## Additional Options
@@ -70,14 +72,23 @@ 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
set `$config['mydomain'] = 'example.com';`
set
!!! setting "discovery/general"
```bash
lnms config:set mydomain example.com
```
### 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;`.
!!! setting "discovery/discovery_modules"
```bash
lnms config:set allow_duplicate_sysName true
```
## Discovery Methods
@@ -93,9 +104,14 @@ 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
`discovery_modules.discovery-arp` or per device
within the Modules section.
!!! setting "discovery/discovery_modules"
```bash
lnms config:set discovery_modules.discovery-arp true
```
### XDP
Enabled by default.
@@ -153,7 +169,7 @@ 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']`.
SNMP Scan will scan `nets` by default and respects `autodiscovery.nets-exclude`.
To run the SNMP-Scanner you need to execute the `snmp-scan.py` from
within your LibreNMS installation directory.

35
doc/Extensions/Dispatcher-Service.md
View File

@@ -112,28 +112,31 @@ Note that if you use Sentinel, you may still need `REDIS_PASSWORD`, `REDIS_USERN
### Basic Configuration
Additional configuration settings can be set in `config.php` or
directly into the database.
Additional configuration settings can be set in your config.
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
$config['service_services_workers'] = 8; # Processes spawned for service polling
$config['service_discovery_workers'] = 16; # Processes spawned for discovery
!!! setting "poller/distributed"
```bash
lnms config:set service_poller_workers 24
lnms config:set service_services_workers 8
lnms config:set service_discovery_workers 16
```
Optional Settings
//Optional Settings
$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_billing_frequency'] = 300; # Seconds between billing calculations
$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
```
!!! setting "poller/distributed"
```bash
lnms config:set service_poller_frequency 300
lnms config:set service_services_frequency 300
lnms config:set service_discovery_frequency 21600
lnms config:set service_billing_frequency 300
lnms config:set service_billing_calculate_frequency 60
lnms config:set service_poller_down_retry 60
lnms config:set service_loglevel INFO
lnms config:set service_update_frequency 86400
```
There are also some SQL options, but these should be inherited from
your LibreNMS web UI configuration.

88
doc/Extensions/Distributed-Poller.md
View File

@@ -41,23 +41,28 @@ These requirements are above the normal requirements for a full LibreNMS 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
`distributed_poller_group`. One can also specify a comma
separated string of poller groups in
$config['distributed_poller_group']. The poller will then poll
`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.
The following is a standard config, combined with a locking mechanism below:
```php
// Distributed Poller-Settings
$config['distributed_poller'] = true;
// optional: defaults to hostname
#$config['distributed_poller_name'] = 'custom';
$config['distributed_poller_group'] = 0;
!!! setting "poller/distributed"
```bash
lnms config:set distributed_poller true
lnms config:set distributed_poller_group 0
```
If you want to customise the hostname for the poller then you will need
to set this in `config.php`:
```php
$config['distributed_poller_name'] = php_uname('n');
```
## Locking mechanisms
Pick one of the following setups, do not use all of them at the same
time.
@@ -199,12 +204,15 @@ Web Server:
Running Apache and an install of LibreNMS in /opt/librenms
- config.php
!!! setting "poller/distributed"
```bash
lnms config:set distributed_poller true
```
```php
$config['distributed_poller'] = true;
$config['rrdcached'] = "example.com:42217";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "example.com:42217"
```
Database Server:
Running Memcache and MariaDB
@@ -251,13 +259,21 @@ Running an install of LibreNMS in /opt/librenms
```php
$config['distributed_poller_name'] = php_uname('n');
$config['distributed_poller_group'] = '0';
$config['distributed_poller_memcached_host'] = "example.com";
$config['distributed_poller_memcached_port'] = 11211;
$config['distributed_poller'] = true;
$config['rrdcached'] = "example.com:42217";
```
!!! setting "poller/distributed"
```bash
lnms config:set distributed_poller_group 0
lnms config:set distributed_poller_memcached_host "example.com"
lnms config:set distributed_poller_memcached_port 11211
lnms config:set distributed_poller true
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "example.com:42217"
```
`/etc/cron.d/librenms`
Runs discovery and polling for group 0, daily.sh to deal with
@@ -278,13 +294,21 @@ Running an install of LibreNMS in /opt/librenms
```php
$config['distributed_poller_name'] = php_uname('n');
$config['distributed_poller_group'] = '0';
$config['distributed_poller_memcached_host'] = "example.com";
$config['distributed_poller_memcached_port'] = 11211;
$config['distributed_poller'] = true;
$config['rrdcached'] = "example.com:42217";
```
!!! setting "poller/distributed"
```bash
lnms config:set distributed_poller_group 0
lnms config:set distributed_poller_memcached_host "example.com"
lnms config:set distributed_poller_memcached_port 11211
lnms config:set distributed_poller true
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "example.com:42217"
```
`/etc/cron.d/librenms`
Runs billing as well as polling for group 0.
@@ -303,13 +327,21 @@ Running an install of LibreNMS in /opt/librenms
```php
$config['distributed_poller_name'] = php_uname('n');
$config['distributed_poller_group'] = '2,3';
$config['distributed_poller_memcached_host'] = "example.com";
$config['distributed_poller_memcached_port'] = 11211;
$config['distributed_poller'] = true;
$config['rrdcached'] = "example.com:42217";
```
!!! setting "poller/distributed"
```bash
lnms config:set distributed_poller_group '2,3'
lnms config:set distributed_poller_memcached_host "example.com"
lnms config:set distributed_poller_memcached_port 11211
lnms config:set distributed_poller true
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "example.com:42217"
```
`/etc/cron.d/librenms`
Runs discovery and polling for groups 2 and 3.

25
doc/Extensions/Fast-Ping-Check.md
View File

@@ -23,9 +23,10 @@ Collection](../Alerting/Rules.md#alert-rules-collection).
2: Change the ping_rrd_step setting in config.php
```
$config['ping_rrd_step'] = 60;
```
!!! setting "poller/rrdtool"
```bash
lnms config:set ping_rrd_step 60
```
3: Update the rrd files to change the step (step is hardcoded at file
creation in rrd files)
@@ -58,9 +59,10 @@ proceeding!
1: Set ping_rrd_step
```
$config['ping_rrd_step'] = 30;
```
!!! setting "poller/rrdtool"
```bash
lnms config:set ping_rrd_step 30
```
2: Update the rrd files
@@ -91,8 +93,9 @@ 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;
$config['fping_options']['timeout'] = 500;
$config['fping_options']['interval'] = 500;
```
!!! setting "poller/ping"
```bash
lnms config:set fping_options.retries 2
lnms config:set fping_options.timeout 500
lnms config:set fping_options.interval 500
```

78
doc/Extensions/Graylog.md
View File

@@ -24,40 +24,47 @@ or as a totally standalone appliance.
Config is simple, here's an example based on Graylog 2.4:
```php
$config['graylog']['server'] = 'http://127.0.0.1';
$config['graylog']['port'] = 9000;
$config['graylog']['username'] = 'admin';
$config['graylog']['password'] = 'admin';
$config['graylog']['version'] = '2.4';
!!! setting "external/graylog"
```bash
lnms config:set graylog.server 'http://127.0.0.1'
lnms config:set graylog.port 9000
lnms config:set graylog.username admin
lnms config:set graylog.password 'admin'
lnms config:set graylog.version 2.4
```
## Timezone
Graylog messages are stored using GMT timezone. You can display
graylog messages in LibreNMS webui using your desired timezone by
setting the following option in config.php:
setting the following option using `lnms config:set`:
```php
$config['graylog']['timezone'] = 'Europe/Bucharest';
```
!!! setting "external/graylog"
```bash
lnms config:set graylog.timezone 'Europe/Bucharest'
```
Timezone must be PHP supported timezones, available at:
<https://php.net/manual/en/timezones.php>
## Graylog Version
If you are running a version earlier than Graylog then please set
```php
$config['graylog']['version']
```
!!! setting "external/graylog"
```bash
lnms config:set graylog.version 2.1
```
to the version number of your Graylog
install. Earlier versions than 2.1 use the default port `12900`
## URI
If you have altered the default uri for your Graylog setup then you
can override the default of `/api/` using
```php
$config['graylog']['base_uri'] = '/somepath/';
```
!!! setting "external/graylog"
```bash
lnms config:set graylog.base_uri '/somepath/'
```
## User Credentials
If you choose to use another user besides the admin user, please note
@@ -70,8 +77,10 @@ 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
```php
$config['graylog']['server']
!!! setting "external/graylog"
```bash
lnms config:set graylog.server example.com
```
## Match Any Address
@@ -80,8 +89,8 @@ 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
```php
$config['graylog']['match-any-address'] = 'true';
```bash
lnms config:set graylog.match-any-address true
```
## Recent Devices
@@ -89,31 +98,32 @@ There are 2 configuration parameters to influence the behaviour of the
"Recent Graylog" table on the overview page of the
devices.
```php
$config['graylog']['device-page']['rowCount']
```
!!! setting "external/graylog"
```bash
lnms config:set graylog.device-page.rowCount 10
```
Sets the maximum number of rows to be displayed (default: 10)
```php
$config['graylog']['device-page']['loglevel']
```
!!! setting "external/graylog"
```bash
lnms config:set graylog.device-page.loglevel 7
```
You can set which loglevels that should be displayed on the overview page. (default: 7, min:
0, max: 7)
```php
$config['graylog']['device-page']['loglevel'] = 4
```
!!! setting "external/graylog"
```bash
lnms config:set graylog.device-page.loglevel 4
```
Shows only entries with a log level less than or equal to 4 (Emergency,
Alert, Critical, Error, Warning).
You can set a default Log Level Filter with
```php
$config['graylog']['loglevel']
```bash
lnms config:set graylog.loglevel 7
```
(applies to /graylog and /device/device=/tab=logs/section=graylog/ (min: 0, max: 7)

15
doc/Extensions/Interface-Description-Parsing.md
View File

@@ -48,13 +48,14 @@ This requires an additional script to be [setup](#setup)
The following config options can be set to enable more custom types:
```php
$config['customers_descr'][] = 'cust';
$config['transit_descr'][] = "transit";
$config['peering_descr'][] = "peering";
$config['core_descr'][] = "core";
$config['custom_descr'][] = "something_made_up";
```
!!! setting "webui/port-descr"
```bash
lnms config:set customers_descr.+ 'cust'
lnms config:set transit_descr.+ 'transit'
lnms config:set peering_descr.+ 'peering'";'
lnms config:set core_descr.+ 'core'
lnms config:set custom_descr.+ 'something_made_up'
```
## Custom interface parser

162
doc/Extensions/NFSen.md
View File

@@ -6,40 +6,44 @@
The following is the configuration that can be used:
```php
$config['nfsen_enable'] = 1;
$config['nfsen_split_char'] = '_';
$config['nfsen_rrds'][] = '/var/nfsen/profiles-stat/live/';
$config['nfsen_rrds'][] = '/var/nfsen/profiles-stat';
$config['nfsen_base'][] = '/var/nfsen/';
$config['nfsen_suffix'] = "_yourdomain_com";
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_enable true
lnms config:set nfsen_split_char '_'
lnms config:set nfsen_rrds.+ '/var/nfsen/profiles-stat/live/'
lnms config:set nfsen_rrds.+ '/var/nfsen/profiles-stat'
lnms config:set nfsen_base.+ '/var/nfsen/'
lnms config:set nfsen_suffix '_yourdomain_com'
```
Set `$config['nfsen_enable'] = 1;` to enable NFSen support.
Set `lnms config:set nfsen_enable true` to enable NFSen support.
`$config['nfsen_rrds']` This value tells us where your NFSen rrd files
`nfsen_rrds` This value tells us where your NFSen rrd files
live. This can also be an array to specify more directories like:
```php
$config['nfsen_rrds'][] = '/var/nfsen/profiles-stat/sitea/';
$config['nfsen_rrds'][] = '/var/nfsen/profiles-stat/siteb/';
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_rrds.+ '/var/nfsen/profiles-stat/sitea/'
lnms config:set nfsen_rrds.+ '/var/nfsen/profiles-stat/siteb/'
```
Although for most setups, it will look like below, with the
profiles-stat/live directory being where it stores the general RRDs
for data sources.
```php
$config['nfsen_rrds'][] = '/var/nfsen/profiles-stat/live';
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_rrds.+ '/var/nfsen/profiles-stat/live'
```
If you wish to render info for configure channels for a device, you
need add the various profile-stat directories your system uses, which
for most systems will be as below.
```php
$config['nfsen_rrds'][] = '/var/nfsen/profiles-stat';
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_rrds.+ '/var/nfsen/profiles-stat'
```
When adding sources to nfsen.conf, it is important to use the hostname
that matches what is configured in LibreNMS, because the rrd files
@@ -53,16 +57,18 @@ cd /var/nfsen/profiles-stat/sitea/
ln -s mychannel.rrd librenmsdeviceIP.rrd
```
```php
$config['nfsen_split_char'] = '_';
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_split_char '_'
```
This value tells us what to replace the full stops `.` in the devices
hostname with.
```php
$config['nfsen_suffix'] = "_yourdomain_com";
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_suffix '_yourdomain_com'
```
The above is a very important bit as device names in NfSen are limited
to 21 characters. This means full domain names for devices can be very
@@ -78,64 +84,62 @@ Below are the default settings used with nfdump for stats.
For more defaulted information on that, please see nfdump(1).
The default location for nfdump is `/usr/bin/nfdump`. If nfdump
is located elsewhere, set it with
`$config['nfdump'] = '/usr/local/bin/nfdump';` for example.
```php
$config['nfsen_last_max'] = 153600;
$config['nfsen_top_max'] = 500;
$config['nfsen_top_N']=array( 10, 20, 50, 100, 200, 500 );
$config['nfsen_top_default']=20;
$config['nfsen_stat_default']='srcip';
$config['nfsen_order_default']='packets';
$config['nfsen_last_default']=900;
$config['nfsen_lasts']=array(
'300'=>'5 minutes',
'600'=>'10 minutes',
'900'=>'15 minutes',
'1800'=>'30 minutes',
'3600'=>'1 hour',
'9600'=>'3 hours',
'38400'=>'12 hours',
'76800'=>'24 hours',
'115200'=>'36 hours',
'153600'=>'48 hours',
);
!!! setting "external/binaries"
```bash
lnms config:set nfdump /usr/local/bin/nfdump
```
```
$config['nfsen_last_max'] = 153600;
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_last_max 153600
lnms config:set nfsen_top_max 500
lnms config:set nfsen_top_N '[10, 20, 50, 100, 200, 500]'
lnms config:set nfsen_top_default 20
lnms config:set nfsen_stat_default srcip
lnms config:set nfsen_order_default packets
lnms config:set nfsen_last_default 900
lnms config:set nfsen_lasts "{'300':'5 minutes', '600':'10 minutes', '900':'15 minutes', '1800':'30 minutes', '3600':'1 hour', '9600':'3 hours', '38400':'12 hours', '76800':'24 hours', '115200':'36 hours', '153600':'48 hours'}"
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_last_max 153600
```
The above is the max value in seconds one may pull stats for. The
higher this is, the more CPU and disk intensive the search will be.
Numbers larger than this will be set to this.
```
$config['nfsen_top_max'] = 500;
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_top_max 500
```
The above is max number of items to be displayed.
Numbers larger than this will be set to this.
```
$config['nfsen_top_N']=array( 10, 20, 50, 100, 200, 500 );
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_top_N '[10, 20, 50, 100, 200, 500]'
```
The above is a array containing a list for the drop down menu how many
top items should be returned.
```php
$config['nfsen_top_default']=20;
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_top_default 20
```
The above sets default top number to use from the drop down.
```php
$config['nfsen_stat_default']='srcip';
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_stat_default srcip
```
The above sets default stat type to use from the drop down.
@@ -155,9 +159,10 @@ srcas SRC AS
dstas DST AS
```
```php
$config['nfsen_order_default']='packets';
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_order_default packets
```
The above sets default order type to use from the drop down. Any of
the following below are currently supported.
@@ -171,26 +176,17 @@ bps Bytes Per Second
bpp Bytes Per Packet
```
```
$config['nfsen_last_default']=900;
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_last_default 900
```
The above is the last default to use from the drop down.
```
$config['nfsen_lasts']=array(
'300'=>'5 minutes',
'600'=>'10 minutes',
'900'=>'15 minutes',
'1800'=>'30 minutes',
'3600'=>'1 hour',
'9600'=>'3 hours',
'38400'=>'12 hours',
'76800'=>'24 hours',
'115200'=>'36 hours',
'153600'=>'48 hours',
);
```
!!! setting "external/nfsen"
```bash
lnms config:set nfsen_lasts "{'300':'5 minutes', '600':'10 minutes', '900':'15 minutes', '1800':'30 minutes', '3600':'1 hour', '9600':'3 hours', '38400':'12 hours', '76800':'24 hours', '115200':'36 hours', '153600':'48 hours'}"
```
The above associative array contains time intervals for how
far back to go. The keys are the length in seconds and the

8
doc/Extensions/PeeringDB.md
View File

@@ -3,8 +3,12 @@
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
!!! setting "external/peeringdb"
```bash
lnms config:set peeringdb.enabled true
```
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

67
doc/Extensions/RRDCached.md
View File

@@ -6,9 +6,11 @@ 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';
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdtool_version '1.5.5'
```
This setting has to be the exact version of rrdtool you are running.
NOTE: This feature requires your client version of rrdtool to be 1.5.5
@@ -85,11 +87,12 @@ chown librenms:librenms /var/lib/rrdcached/journal/
systemctl restart rrdcached.service
```
5: Edit `/opt/librenms/config.php` to include:
5: Edit your config to include:
```php
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "unix:/run/rrdcached.sock"
```
### RRDCached installation Debian Buster
(rrdcached 1.7.1)
@@ -129,13 +132,14 @@ chown librenms:librenms /var/lib/rrdcached/journal/
systemctl restart rrdcached.service
```
5: Edit /opt/librenms/config.php to include:
5: Edit your config to include:
For local RRDCached server
```php
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "unix:/run/rrdcached.sock"
```
For remote RRDCached server make sure you have network option in /var/default/rrdcached
@@ -143,9 +147,10 @@ For remote RRDCached server make sure you have network option in /var/default/rr
NETWORK_OPTIONS="-L"
```
```php
$config['rrdcached'] = "IPADDRESS:42217";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "IPADDRESS:42217"
```
NOTE: change IPADDRESS to the ip the rrdcached server is listening on.
@@ -187,13 +192,14 @@ chown librenms:librenms /var/lib/rrdcached/journal/
systemctl restart rrdcached.service
```
5: Edit /opt/librenms/config.php to include:
5: Edit your config to include:
For local RRDCached server
```php
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "unix:/run/rrdcached.sock"
```
For remote RRDCached server make sure you have network option in /var/default/rrdcached
@@ -201,9 +207,10 @@ For remote RRDCached server make sure you have network option in /var/default/rr
NETWORK_OPTIONS="-L"
```
```php
$config['rrdcached'] = "IPADDRESS:42217";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "IPADDRESS:42217"
```
NOTE: change IPADDRESS to the ip the rrdcached server is listening on.
@@ -262,11 +269,12 @@ semodule -i rrdcached_librenms.pp
systemctl enable --now rrdcached.service
```
4: Edit `/opt/librenms/config.php` to include:
4: Edit your config to include:
```php
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "unix:/run/rrdcached.sock"
```
### RRDCached installation CentOS 6
@@ -302,11 +310,12 @@ chkconfig rrdcached on
service rrdcached start
```
- Edit /opt/librenms/config.php to include:
- Edit your config to include:
```php
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
!!! setting "poller/rrdtool"
```bash
lnms config:set rrdcached "unix:/run/rrdcached.sock"
```
## Verify

11
doc/Extensions/SNMP-Trap-Handler.md
View File

@@ -185,12 +185,13 @@ and all the data received with the trap will be logged.
The parameter can be found in General Settings / External / SNMP Traps Integration.
It can also be configured in ```config.php```
It can also be configured in your config.
```php
$config['snmptraps']['eventlog'] = 'unhandled'; //default value
$config['snmptraps']['eventlog_detailed'] = 'false'; //default value
```
!!! setting "external/snmptrapd"
```bash
lnms config:set snmptraps.eventlog 'unhandled'
lnms config:set snmptraps.eventlog_detailed false
```
Valid options are:

18
doc/Extensions/Smokeping.md
View File

@@ -124,15 +124,15 @@ file sequence.
## Configure LibreNMS - All Operating Systems
Edit `/opt/librenms/config.php` and add the following:
!!! setting "external/smokeping"
```bash
lnms config:set smokeping.dir '/var/lib/smokeping'
lnms config:set smokeping.pings 20
lnms config:set smokeping.probes 2
lnms config:set smokeping.integration true
lnms config:set smokeping.url 'smokeping/'
```
```php
$config['smokeping']['dir'] = '/var/lib/smokeping';
$config['smokeping']['pings'] = 20;
$config['smokeping']['probes'] = 2;
$config['smokeping']['integration'] = true;
$config['smokeping']['url'] = 'smokeping/'; // If you have a specific URL or path for smokeping
```
`dir` should match the location that smokeping writes RRD's to
`pings` should match the default smokeping value, default 20
`probes` should be the number of processes to spread pings over, default 2
@@ -307,7 +307,7 @@ Finally restart the smokeping service:
sudo systemctl start smokeping
```
Remember to update *config.php* with the new locations.
Remember to update your config with the new locations.
#### Configure SELinux to allow smokeping to write in LibreNMS directory on Centos / RHEL
If you are using RRDCached with the -B switch and smokeping RRD's inside the LibreNMS RRD base directory, you can install this SELinux profile:

3
doc/Extensions/Sub-Directory.md
View File

@@ -24,5 +24,4 @@ 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 `lnms config:set base_url '/librenms/'`.

11
doc/Extensions/World-Map.md
View File

@@ -15,7 +15,7 @@ Location resolution happens as follows
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. Attempt to resolve lat, lng using `lnms config:set geoloc.engine`
1. Properly formatted addresses in sysLocation or sysLocation
override, under device settings.
@@ -74,10 +74,11 @@ $config['leaflet']['group_radius'] = 1;
## Geocode engine config
```php
$config['geoloc']['engine'] = "google"; // Valid options are google, mapquest or bing
$config['geoloc']['api_key'] = "abcdefghijklmnopqrstuvwxyz";
```
!!! setting "external/location"
```bash
lnms config:set geoloc.engine google
lnms config:set geoloc.api_key 'abcdefghijklmnopqrstuvwxyz'
```
Google:
Pros: fast, accurate

13
doc/Extensions/metrics/Graphite.md
View File

@@ -13,12 +13,13 @@ continue to function as normal.
## Configuration
```php
$config['graphite']['enable'] = true;
$config['graphite']['host'] = 'your.graphite.server';
$config['graphite']['port'] = 2003; // this defaults to 2003 and is usually not needed
$config['graphite']['prefix'] = 'your.metric.prefix';
```
!!! setting "poller/graphite"
```bash
lnms config:set graphite.enable true
lnms config:set graphite.host 'your.graphite.server'
lnms config:set graphite.port 2003
lnms config:set graphite.prefix 'your.metric.prefix'
```
Your metric path can be prefixed if required, otherwise the metric
path for Graphite will be in the form of

23
doc/Extensions/metrics/InfluxDB.md
View File

@@ -27,17 +27,18 @@ continue to function as normal.
## Configuration
```php
$config['influxdb']['enable'] = true;
$config['influxdb']['transport'] = 'http'; # Default, other options: https, udp
$config['influxdb']['host'] = '127.0.0.1';
$config['influxdb']['port'] = '8086';
$config['influxdb']['db'] = 'librenms';
$config['influxdb']['username'] = 'admin';
$config['influxdb']['password'] = 'admin';
$config['influxdb']['timeout'] = 0; # Optional
$config['influxdb']['verifySSL'] = false; # Optional
```
!!! setting "poller/influxdb"
```bash
lnms config:set influxdb.enable true
lnms config:set influxdb.transport http
lnms config:set influxdb.host '127.0.0.1'
lnms config:set influxdb.port 8086
lnms config:set influxdb.db 'librenms'
lnms config:set influxdb.username 'admin'
lnms config:set influxdb.password 'admin'
lnms config:set influxdb.timeout 0
lnms config:set influxdb.verifySSL false
```
No credentials are needed if you don't use InfluxDB authentication.

14
doc/Extensions/metrics/OpenTSDB.md
View File

@@ -16,16 +16,16 @@ like Grafana for graphing.
RRD will continue to function normally so LibreNMS itself should
continue to function normally.
You can add the following to `config.php`.
You can add the following to your config:
## Configuration
```php
// OpenTSDB default configuration
$config['opentsdb']['enable'] = true;
$config['opentsdb']['host'] = '127.0.0.1'; // your OpenTSDB server
$config['opentsdb']['port'] = 4242;
```
!!! setting "poller/opentsdb"
```bash
lnms config:set opentsdb.enable true
lnms config:set opentsdb.host '127.0.0.1'
lnms config:set opentsdb.port 4242
```
The same data than the one stored within rrd will be sent to OpenTSDB
and recorded. You can then create graphs within Grafana to display the

13
doc/Extensions/metrics/Prometheus.md
View File

@@ -27,12 +27,13 @@ continue to function as normal.
## Configuration
```php
$config['prometheus']['enable'] = true;
$config['prometheus']['url'] = 'http://127.0.0.1:9091';
$config['prometheus']['job'] = 'librenms'; # Optional
$config['prometheus']['prefix'] = 'librenms'; # Optional
```
!!! setting "poller/prometheus"
```bash
lnms config:set prometheus.enable true
lnms config:set prometheus.url 'http://127.0.0.1:9091'
lnms config:set prometheus.job 'librenms'
lnms config:set prometheus.prefix 'librenms'
```
## Prefix

6
doc/General/Releases.md
View File

@@ -19,8 +19,8 @@ secondary testers to the automation and manually testing that is done
during the merge stages.
You can configure your install (this is the default) to use this
branch by setting `$config['update_channel'] = 'master';` in
`config.php` and ensuring you switch to the master branch with:
branch by setting `lnms config:set update_channel master`
and ensuring you switch to the master branch with:
`cd /opt/librenms && git checkout master`
@@ -35,7 +35,7 @@ The changelog is also updated and will reference the release number
and date so you can see what changes have been made since the last release.
To switch to using stable branches you can set
`$config['update_channel'] = 'release';` in config.php and then switch
`lnms config:set update_channel release` and then switch
to the latest release branch with:
`cd /opt/librenms && git fetch --tags && git checkout $(git describe

16
doc/Installation/Installation-CentOS-6-Apache-Nginx.md
View File

@@ -451,18 +451,12 @@ cp misc/librenms.logrotate /etc/logrotate.d/librenms
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
override this default:
```
#$config['update'] = 0;
```
so that it looks like this:
```
$config['update'] = 0;
```
!!! setting "system/updates"
```bash
lnms config:set update false
```
# Install complete

31
doc/Support/Cleanup-options.md
View File

@@ -8,27 +8,24 @@ entries. With Cleanup Options, you can stay in control.
These options rely on ```daily.sh``` running from cron as per the installation instructions.
You can adjust the config in Global Setting -> System -> Cleanup.
Cleanup Options can also be set in ```config.php```
```php
$config['eventlog_purge'] = 30;
$config['syslog_purge'] = 30;
$config['route_purge'] = 10;
$config['alert_log_purge'] = 365;
$config['authlog_purge'] = 30;
$config['ports_fdb_purge'] = 10;
$config['device_perf_purge'] = 7;
$config['rrd_purge'] = 0;
$config['ports_purge'] = true;
```
!!! setting "system/cleanup"
```bash
lnms config:set eventlog_purge 30
lnms config:set syslog_purge 30
lnms config:set route_purge 10
lnms config:set alert_log_purge 365
lnms config:set authlog_purge 30
lnms config:set ports_fdb_purge 10
lnms config:set device_perf_purge 7
lnms config:set rrd_purge 0
lnms config:set ports_purge true
```
These options will ensure data within LibreNMS over X days old is
automatically purged. You can alter these individually, values are in
days.
**NOTE**: Please be aware that ```$config['rrd_purge']``` is NOT set
**NOTE**: Please be aware that `rrd_purge` is NOT set
by default. This option will remove any RRD files that have not been
updated for the set amount of days automatically - only enable this if
you are comfortable with that happening. (All active RRD files are
@@ -40,7 +37,7 @@ Over time as you add devices some interfaces will need to be purged as
they are set to be ignored or bad interfaces or marked as deleted.
You can purge all deleted ports from the WebUI (see below) or by
setting `$config['ports_purge'] = true;` in `config.php`
setting `lnms config:set ports_purge true`.
In the Web UI Under the Ports Tab in the Nav Bar, Click on "Deleted"
then click on "Purge all deleted". This will purge all the ports.

223
doc/Support/Configuration.md
View File

@@ -181,23 +181,29 @@ be linked to rather than having the config provided.
>
> Settings -> External Settings -> RRDTool Setup
```bash
lnms config:set rrdtool /usr/bin/rrdtool
```
!!! setting "external/binaries"
```bash
lnms config:set rrdtool /usr/bin/rrdtool
```
Please see [1 Minute polling](1-Minute-Polling.md) for information on
configuring your install to record data more frequently.
#### fping
```bash
!!! setting "external/binaries"
```bash
lnms config:set fping /usr/bin/fping
lnms config:set fping6 fping6
lnms config:set fping_options.timeout 500
lnms config:set fping_options.count 3
lnms config:set fping_options.interval 500
lnms config:set fping_options.tos 184
```
```
!!! setting "poller/ping"
```bash
lnms config:set fping_options.timeout 500
lnms config:set fping_options.count 3
lnms config:set fping_options.interval 500
lnms config:set fping_options.tos 184
```
`fping` configuration options:
@@ -246,20 +252,26 @@ LibreNMS uses traceroute to record debug information
when a device is down due to icmp AND you have
`lnms config:set debug.run_trace true` set.
```bash
lnms config:set traceroute /usr/bin/traceroute
```
!!! setting "external/binaries"
```bash
lnms config:set traceroute /usr/bin/traceroute
```
#### SNMP
```bash
lnms config:set snmpwalk /usr/bin/snmpwalk
lnms config:set snmpget /usr/bin/snmpget
lnms config:set snmpbulkwalk /usr/bin/snmpbulkwalk
```
SNMP program locations.
!!! setting "external/binaries"
```bash
lnms config:set snmpwalk /usr/bin/snmpwalk
lnms config:set snmpget /usr/bin/snmpget
lnms config:set snmpbulkwalk /usr/bin/snmpbulkwalk
lnms config:set snmpgetnext /usr/bin/snmpgetnext
lnms config:set snmptranslate /usr/bin/snmptranslate
```
#### Misc binaries
!!! setting "external/binaries"
```bash
lnms config:set whois /usr/bin/whois
lnms config:set ping /bin/ping
@@ -287,10 +299,11 @@ lnms config:set password.min_length 8
For alerting and the callback functionality, we support the use of a
http proxy setting. These can be any one of the following:
```bash
lnms config:set callback_proxy proxy.domain.com
lnms config:set http_proxy proxy.domain.com
```
!!! setting "system/proxy"
```bash
lnms config:set callback_proxy proxy.domain.com
lnms config:set http_proxy proxy.domain.com
```
We can also make use of one of these environment variables which can be set in `/etc/environment`:
@@ -311,9 +324,10 @@ lnms config:set base_url http://demo.librenms.org
LibreNMS will attempt to detect the URL you are using but you can override that here.
```bash
lnms config:set site_style light
```
!!! setting "webui/style"
```bash
lnms config:set site_style light
```
Currently we have a number of styles which can be set which will alter
the navigation bar look. dark, light and mono with light being the default.
@@ -328,9 +342,10 @@ into `html/css/custom` so they will be ignored by auto updates. You
can specify as many css files as you like, the order they are within
your config will be the order they are loaded in the browser.
```bash
lnms config:set title_image images/custom/yourlogo.png
```
!!! setting "webui/style"
```bash
lnms config:set title_image images/custom/yourlogo.png
```
You can override the default logo with yours, place any custom images
files into `html/images/custom` so they will be ignored by auto updates.
@@ -350,10 +365,10 @@ You can create your own front page by adding a blade file in `resources/views/ov
and setting `front_page` to it's name.
For example, if you create `resources/views/overview/custom/foobar.blade.php`, set `front_page` to `foobar`.
```bash
// This option exists in the web UI, edit it under Global Settings -> webui
lnms config:set webui.default_dashboard_id 0
```
!!! setting "webui/dashboard"
```bash
lnms config:set webui.default_dashboard_id 0
```
Allows the specification of a global default dashboard page for any user who
has not set one in their user preferences. Should be set to dashboard_id of an
@@ -452,9 +467,10 @@ lnms config:set overview_show_sysDescr true
Enable or disable the sysDescr output for a device.
```bash
lnms config:set device_display_default '{{ $hostname }}'
```
!!! setting "webui/device"
```bash
lnms config:set device_display_default '{{ $hostname }}'
```
This is a simple template to control the display of device names by default.
You can override this setting per-device.
@@ -503,9 +519,10 @@ lnms config:set percentile_value 90
Show the `X`th percentile in the graph instead of the default 95th percentile.
```bash
lnms config:set shorthost_target_length 15
```
!!! setting "webui/graph"
```bash
lnms config:set shorthost_target_length 15
```
The target maximum hostname length when applying the shorthost() function.
You can increase this if you want to try and fit more of the hostname in graph titles.
@@ -541,6 +558,7 @@ lnms config:set addhost_alwayscheckip false # true - check for duplicate ips eve
By default we allow hosts to be added with duplicate sysName's, you
can disable this with the following config:
!!! setting "discovery/general"
```bash
lnms config:set allow_duplicate_sysName false
```
@@ -576,14 +594,15 @@ lnms config:set os.ios.poller_modules.entity-state true
Default SNMP options including retry and timeout settings and also
default version and port.
```bash
lnms config:set snmp.timeout 1 # timeout in seconds
lnms config:set snmp.retries 5 # how many times to retry the query
lnms config:set snmp.transports '["udp", "udp6", "tcp", "tcp6"]' # Transports to use
lnms config:set snmp.version '["v2c", "v3", "v1"]' # Default versions to use
lnms config:set snmp.port 161 # Default port
lnms config:set snmp.exec_timeout 1200 # execution time limit in seconds
```
!!! setting "poller/snmp"
```bash
lnms config:set snmp.timeout 1 # timeout in seconds
lnms config:set snmp.retries 5 # how many times to retry the query
lnms config:set snmp.transports '["udp", "udp6", "tcp", "tcp6"]' # Transports to use
lnms config:set snmp.version '["v2c", "v3", "v1"]' # Default versions to use
lnms config:set snmp.port 161 # Default port
lnms config:set snmp.exec_timeout 1200 # execution time limit in seconds
```
> NOTE: `timeout` is the time to wait for an answer and `exec_timeout`
> is the max time to run a query.
@@ -591,24 +610,27 @@ lnms config:set snmp.exec_timeout 1200 # execution time limit in
The default v1/v2c snmp community to use, you can expand this array
with `[1]`, `[2]`, `[3]`, etc.
```bash
lnms config:set snmp.community.0 public
```
!!! setting "poller/snmp"
```bash
lnms config:set snmp.community.0 public
```
>NOTE: This list of SNMP communities is used for auto discovery, and as a default set for any manually added device.
The default v3 snmp details to use, you can expand this array with
`[1]`, `[2]`, `[3]`, etc.
```bash
lnms config:set snmp.v3.0 '{
authlevel: "noAuthNoPriv",
authname: "root",
authpass: "",
authalgo: "MD5",
cryptopass: "",
cryptoalgo: "AES"
}'
```
!!! setting "poller/snmp"
```bash
lnms config:set snmp.v3.0 '{
authlevel: "noAuthNoPriv",
authname: "root",
authpass: "",
authalgo: "MD5",
cryptopass: "",
cryptoalgo: "AES"
}'
```
```
authlevel noAuthNoPriv | authNoPriv | authPriv
@@ -628,19 +650,20 @@ Please refer to [Auto-Discovery](../Extensions/Auto-Discovery.md)
> You can configure these options within the WebUI now, please avoid
> setting these options within config.php
```bash
lnms config:set email_backend mail
lnms config:set email_from librenms@yourdomain.local
lnms config:set email_user `lnms config:get project_id`
lnms config:set email_sendmail_path /usr/sbin/sendmail
lnms config:set email_smtp_host localhost
lnms config:set email_smtp_port 25
lnms config:set email_smtp_timeout 10
lnms config:set email_smtp_secure tls
lnms config:set email_smtp_auth false
lnms config:set email_smtp_username NULL
lnms config:set email_smtp_password NULL
```
!!! setting "alerting/email"
```bash
lnms config:set email_backend mail
lnms config:set email_from librenms@yourdomain.local
lnms config:set email_user `lnms config:get project_id`
lnms config:set email_sendmail_path /usr/sbin/sendmail
lnms config:set email_smtp_host localhost
lnms config:set email_smtp_port 25
lnms config:set email_smtp_timeout 10
lnms config:set email_smtp_secure tls
lnms config:set email_smtp_auth false
lnms config:set email_smtp_username NULL
lnms config:set email_smtp_password NULL
```
What type of mail transport to use for delivering emails. Valid
options for `email_backend` are mail, sendmail or smtp. The varying
@@ -680,9 +703,10 @@ Enable / disable additional port statistics.
Assign a new discovered Port automatically to Port Group with this Port Group ID
(0 means no Port Group assignment)
```php
lnms config:set default_port_group 0
```
!!! setting "discovery/networks"
```bash
lnms config:set default_port_group 0
```
## External integration
@@ -940,33 +964,34 @@ lnms config:set os.iosxe.disabled_sensors_regex '/PEM Iout/'
Mounted storage / mount points to ignore in discovery and polling.
```bash
lnms config:set ignore_mount_removable true
lnms config:set ignore_mount_network true
lnms config:set ignore_mount_optical true
!!! setting "discovery/storage"
```bash
lnms config:set ignore_mount_removable true
lnms config:set ignore_mount_network true
lnms config:set ignore_mount_optical true
lnms config:set ignore_mount.+ /kern
lnms config:set ignore_mount.+ /mnt/cdrom
lnms config:set ignore_mount.+ /proc
lnms config:set ignore_mount.+ /dev
lnms config:set ignore_mount.+ /kern
lnms config:set ignore_mount.+ /mnt/cdrom
lnms config:set ignore_mount.+ /proc
lnms config:set ignore_mount.+ /dev
lnms config:set ignore_mount_string.+ packages
lnms config:set ignore_mount_string.+ devfs
lnms config:set ignore_mount_string.+ procfs
lnms config:set ignore_mount_string.+ UMA
lnms config:set ignore_mount_string.+ MALLOC
lnms config:set ignore_mount_string.+ packages
lnms config:set ignore_mount_string.+ devfs
lnms config:set ignore_mount_string.+ procfs
lnms config:set ignore_mount_string.+ UMA
lnms config:set ignore_mount_string.+ MALLOC
lnms config:set ignore_mount_regexp.+ '/on: \/packages/'
lnms config:set ignore_mount_regexp.+ '/on: \/dev/'
lnms config:set ignore_mount_regexp.+ '/on: \/proc/'
lnms config:set ignore_mount_regexp.+ '/on: \/junos^/'
lnms config:set ignore_mount_regexp.+ '/on: \/junos\/dev/'
lnms config:set ignore_mount_regexp.+ '/on: \/jail\/dev/'
lnms config:set ignore_mount_regexp.+ '/^(dev|proc)fs/'
lnms config:set ignore_mount_regexp.+ '/^\/dev\/md0/'
lnms config:set ignore_mount_regexp.+ '/^\/var\/dhcpd\/dev,/'
lnms config:set ignore_mount_regexp.+ '/UMA/'
```
lnms config:set ignore_mount_regexp.+ '/on: \/packages/'
lnms config:set ignore_mount_regexp.+ '/on: \/dev/'
lnms config:set ignore_mount_regexp.+ '/on: \/proc/'
lnms config:set ignore_mount_regexp.+ '/on: \/junos^/'
lnms config:set ignore_mount_regexp.+ '/on: \/junos\/dev/'
lnms config:set ignore_mount_regexp.+ '/on: \/jail\/dev/'
lnms config:set ignore_mount_regexp.+ '/^(dev|proc)fs/'
lnms config:set ignore_mount_regexp.+ '/^\/dev\/md0/'
lnms config:set ignore_mount_regexp.+ '/^\/var\/dhcpd\/dev,/'
lnms config:set ignore_mount_regexp.+ '/UMA/'
```
Custom storage warning percentage

101
doc/Support/Discovery Support.md
View File

@@ -63,53 +63,54 @@ a module by setting it to 0. If you just want to disable it for one
device then you can do this within the WebUI -> Device -> Settings ->
Modules.
```php
$config['discovery_modules']['os'] = true;
$config['discovery_modules']['ports'] = true;
$config['discovery_modules']['ports-stack'] = true;
$config['discovery_modules']['entity-physical'] = true;
$config['discovery_modules']['entity-state'] = false;
$config['discovery_modules']['processors'] = true;
$config['discovery_modules']['mempools'] = true;
$config['discovery_modules']['cisco-vrf-lite'] = true;
$config['discovery_modules']['cisco-mac-accounting'] = false;
$config['discovery_modules']['cisco-pw'] = false;
$config['discovery_modules']['vrf'] = false;
$config['discovery_modules']['cisco-cef'] = false;
$config['discovery_modules']['slas'] = false;
$config['discovery_modules']['cisco-cbqos'] = false;
$config['discovery_modules']['cisco-otv'] = false;
$config['discovery_modules']['ipv4-addresses'] = true;
$config['discovery_modules']['ipv6-addresses'] = true;
$config['discovery_modules']['route'] = false;
$config['discovery_modules']['sensors'] = true;
$config['discovery_modules']['storage'] = true;
$config['discovery_modules']['hr-device'] = true;
$config['discovery_modules']['discovery-protocols'] = true;
$config['discovery_modules']['arp-table'] = true;
$config['discovery_modules']['discovery-arp'] = false;
$config['discovery_modules']['junose-atm-vp'] = false;
$config['discovery_modules']['bgp-peers'] = true;
$config['discovery_modules']['vlans'] = true;
$config['discovery_modules']['vmware-vminfo'] = false;
$config['discovery_modules']['libvirt-vminfo'] = false;
$config['discovery_modules']['printer-supplies'] = false;
$config['discovery_modules']['ucd-diskio'] = true;
$config['discovery_modules']['applications'] = false;
$config['discovery_modules']['services'] = true;
$config['discovery_modules']['stp'] = true;
$config['discovery_modules']['ntp'] = true;
$config['discovery_modules']['loadbalancers'] = false;
$config['discovery_modules']['mef'] = false;
$config['discovery_modules']['wireless'] = true;
$config['discovery_modules']['fdb-table'] = true;
$config['discovery_modules']['xdsl'] = false;
```
!!! setting "discovery/discovery_modules"
```bash
lnms config:set discovery_modules.os true
lnms config:set discovery_modules.ports true
lnms config:set discovery_modules.ports-stack true
lnms config:set discovery_modules.entity-physical true
lnms config:set discovery_modules.entity-state false
lnms config:set discovery_modules.processors true
lnms config:set discovery_modules.mempools true
lnms config:set discovery_modules.cisco-vrf-lite true
lnms config:set discovery_modules.cisco-mac-accounting false
lnms config:set discovery_modules.cisco-pw false
lnms config:set discovery_modules.vrf false
lnms config:set discovery_modules.cisco-cef false
lnms config:set discovery_modules.slas false
lnms config:set discovery_modules.cisco-cbqos false
lnms config:set discovery_modules.cisco-otv false
lnms config:set discovery_modules.ipv4-addresses true
lnms config:set discovery_modules.ipv6-addresses true
lnms config:set discovery_modules.route false
lnms config:set discovery_modules.sensors true
lnms config:set discovery_modules.storage true
lnms config:set discovery_modules.hr-device true
lnms config:set discovery_modules.discovery-protocols true
lnms config:set discovery_modules.arp-table true
lnms config:set discovery_modules.discovery-arp false
lnms config:set discovery_modules.junose-atm-vp false
lnms config:set discovery_modules.bgp-peers true
lnms config:set discovery_modules.vlans true
lnms config:set discovery_modules.vmware-vminfo false
lnms config:set discovery_modules.libvirt-vminfo false
lnms config:set discovery_modules.printer-supplies false
lnms config:set discovery_modules.ucd-diskio true
lnms config:set discovery_modules.applications false
lnms config:set discovery_modules.services true
lnms config:set discovery_modules.stp true
lnms config:set discovery_modules.ntp true
lnms config:set discovery_modules.loadbalancers false
lnms config:set discovery_modules.mef false
lnms config:set discovery_modules.wireless true
lnms config:set discovery_modules.fdb-table true
lnms config:set discovery_modules.xdsl false
```
## OS based Discovery config
You can enable or disable modules for a specific OS by add
corresponding line in `config.php` OS based settings have preference
You can enable or disable modules for a specific OS by using
`lnms config:set` OS based settings have preference
over global. Device based settings have preference over all others
Discover performance improvement can be achieved by deactivating all
@@ -117,10 +118,11 @@ modules that are not supported by specific OS.
E.g. to deactivate spanning tree but activate discovery-arp module for linux OS
```php
$config['os']['linux']['discovery_modules']['stp'] = false;
$config['os']['linux']['discovery_modules']['discovery-arp'] = true;
```
!!! setting "discovery/discovery_modules"
```bash
lnms config:set os.linux.discovery_modules.stp false
lnms config:set os.linux.discovery_modules.discovery-arp true
```
## Discovery modules
@@ -146,8 +148,7 @@ configured to be ignored by config options.
`ipv6-addresses`: IPv6 Address detection
`route`: This module will load the routing table of the device. The default route
limit is 1000 (configurable in config.php with
```$config['routes']['max_number'] = 1000;```), with history data.
limit is 1000 (configurable with `lnms config:set routes.max_number 1000`), with history data.
`sensors`: Sensor detection such as Temperature, Humidity, Voltages + More

29
doc/Support/Performance.md
View File

@@ -36,9 +36,10 @@ do this globally in `config.php` like:
Disable OSPF polling
```php
$config['poller_modules']['ospf'] = false;
```
!!! setting "poller/poller_modules"
```bash
lnms config:set poller_modules.ospf false
```
You can disable modules globally then re-enable the module per device
or the opposite way. For a list of modules please see [Poller
@@ -83,22 +84,24 @@ You can also set this globally with the config option
You can change some of the default fping options used globally or per
device. The defaults are:
```php
$config['fping_options']['timeout'] = 500;
$config['fping_options']['count'] = 3;
$config['fping_options']['interval'] = 500;
```
!!! setting "poller/ping"
```bash
lnms config:set fping_options.timeout 500
lnms config:set fping_options.count 3
lnms config:set fping_options.interval 500
```
If your devices are slow to respond then you will need to increase the
timeout value and potentially the interval value. However if your
network is stable, you can increase poller performance by dropping the
count value to 1 and/or the timeout+millsec value to 200 or 300:
```php
$config['fping_options']['timeout'] = 300;
$config['fping_options']['count'] = 1;
$config['fping_options']['interval'] = 300;
```
!!! setting "poller/ping"
```bash
lnms config:set fping_options.timeout 300
lnms config:set fping_options.count 1
lnms config:set fping_options.interval 300
```
This will mean that we no longer delay each icmp packet sent (we send
3 in total by default) by 0.5 seconds. With only 1 icmp packet

102
doc/Support/Poller Support.md
View File

@@ -58,52 +58,53 @@ module by setting it to 0. If you just want to
disable it for one device then you can do this within the WebUI Device
-> Edit -> Modules.
```php
$config['poller_modules']['unix-agent'] = false;
$config['poller_modules']['os'] = true;
$config['poller_modules']['ipmi'] = true;
$config['poller_modules']['sensors'] = true;
$config['poller_modules']['processors'] = true;
$config['poller_modules']['mempools'] = true;
$config['poller_modules']['storage'] = true;
$config['poller_modules']['netstats'] = true;
$config['poller_modules']['hr-mib'] = true;
$config['poller_modules']['ucd-mib'] = true;
$config['poller_modules']['ipSystemStats'] = true;
$config['poller_modules']['ports'] = true;
$config['poller_modules']['nac'] = false;
$config['poller_modules']['bgp-peers'] = true;
$config['poller_modules']['junose-atm-vp'] = false;
$config['poller_modules']['printer-supplies'] = false;
$config['poller_modules']['ucd-diskio'] = true;
$config['poller_modules']['wireless'] = true;
$config['poller_modules']['ospf'] = true;
$config['poller_modules']['cisco-ipsec-flow-monitor'] = false;
$config['poller_modules']['cisco-remote-access-monitor'] = false;
$config['poller_modules']['cisco-cef'] = false;
$config['poller_modules']['slas'] = false;
$config['poller_modules']['cisco-mac-accounting'] = false;
$config['poller_modules']['cipsec-tunnels'] = false;
$config['poller_modules']['cisco-ace-loadbalancer'] = false;
$config['poller_modules']['cisco-ace-serverfarms'] = false;
$config['poller_modules']['cisco-asa-firewall'] = false;
$config['poller_modules']['cisco-voice'] = false;
$config['poller_modules']['cisco-cbqos'] = false;
$config['poller_modules']['cisco-otv'] = false;
$config['poller_modules']['cisco-vpdn'] = false;
$config['poller_modules']['netscaler-vsvr'] = false;
$config['poller_modules']['aruba-controller'] = false;
$config['poller_modules']['entity-physical'] = true;
$config['poller_modules']['entity-state'] = false;
$config['poller_modules']['applications'] = true;
$config['poller_modules']['availability'] = true;
$config['poller_modules']['stp'] = true;
$config['poller_modules']['ntp'] = true;
$config['poller_modules']['services'] = true;
$config['poller_modules']['loadbalancers'] = false;
$config['poller_modules']['mef'] = false;
$config['poller_modules']['mef'] = false;
```
!!! setting "poller/poller_modules"
```bash
lnms config:set poller_modules.unix-agent false
lnms config:set poller_modules.os true
lnms config:set poller_modules.ipmi true
lnms config:set poller_modules.sensors true
lnms config:set poller_modules.processors true
lnms config:set poller_modules.mempools true
lnms config:set poller_modules.storage true
lnms config:set poller_modules.netstats true
lnms config:set poller_modules.hr-mib true
lnms config:set poller_modules.ucd-mib true
lnms config:set poller_modules.ipSystemStats true
lnms config:set poller_modules.ports true
lnms config:set poller_modules.nac false
lnms config:set poller_modules.bgp-peers true
lnms config:set poller_modules.junose-atm-vp false
lnms config:set poller_modules.printer-supplies false
lnms config:set poller_modules.ucd-diskio true
lnms config:set poller_modules.wireless true
lnms config:set poller_modules.ospf true
lnms config:set poller_modules.cisco-ipsec-flow-monitor false
lnms config:set poller_modules.cisco-remote-access-monitor false
lnms config:set poller_modules.cisco-cef false
lnms config:set poller_modules.slas false
lnms config:set poller_modules.cisco-mac-accounting false
lnms config:set poller_modules.cipsec-tunnels false
lnms config:set poller_modules.cisco-ace-loadbalancer false
lnms config:set poller_modules.cisco-ace-serverfarms false
lnms config:set poller_modules.cisco-asa-firewall false
lnms config:set poller_modules.cisco-voice false
lnms config:set poller_modules.cisco-cbqos false
lnms config:set poller_modules.cisco-otv false
lnms config:set poller_modules.cisco-vpdn false
lnms config:set poller_modules.netscaler-vsvr false
lnms config:set poller_modules.aruba-controller false
lnms config:set poller_modules.entity-physical true
lnms config:set poller_modules.entity-state false
lnms config:set poller_modules.applications true
lnms config:set poller_modules.availability true
lnms config:set poller_modules.stp true
lnms config:set poller_modules.ntp true
lnms config:set poller_modules.services true
lnms config:set poller_modules.loadbalancers false
lnms config:set poller_modules.mef false
lnms config:set poller_modules.mef false
```
## OS based Poller config
@@ -116,10 +117,11 @@ modules that are not supported by specific OS.
E.g. to deactivate spanning tree but activate unix-agent module for linux OS
```php
$config['os']['linux']['poller_modules']['stp'] = false;
$config['os']['linux']['poller_modules']['unix-agent'] = true;
```
!!! setting "poller/poller_modules"
```bash
lnms config:set os.linux.poller_modules.stp false
lnms config:set os.linux.poller_modules.unix-agent true
```
## Poller modules