diff --git a/doc/API/API-Docs.md b/doc/API/API-Docs.md index 4f9d4362f..eacdcfada 100644 --- a/doc/API/API-Docs.md +++ b/doc/API/API-Docs.md @@ -112,7 +112,7 @@ Route: /api/v0/devices/:hostname Input: - - + - Example: ```curl @@ -146,7 +146,7 @@ Route: /api/v0/devices/:hostname Input: - - + - Example: ```curl @@ -179,7 +179,7 @@ Route: /api/v0/devices/:hostname/graphs Input: - - + - Example: ```curl @@ -511,8 +511,8 @@ Route: /api/v0/oxidized Input (JSON): - - - + - + Examples: ```curl curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized @@ -548,7 +548,7 @@ Input (JSON): Examples: ```curl -curl -X PATCH -d '{"field": "notes", "data": "This server should be kept online"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost +curl -X PATCH -d '{"field": "notes", "data": "This server should be kept online"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost ``` Output: @@ -751,7 +751,7 @@ Route: /api/v0/devices/:hostname/vlans Input: - - + - Example: ```curl @@ -787,7 +787,7 @@ Route: /api/v0/alerts/:id Input: - - + - Example: ```curl @@ -824,7 +824,7 @@ Route: /api/v0/alerts/:id Input: - - + - Example: ```curl @@ -913,7 +913,7 @@ Route: /api/v0/rules/:id Input: - - + - Example: ```curl @@ -950,7 +950,7 @@ Route: /api/v0/rules/:id Input: - - + - Example: ```curl @@ -972,11 +972,11 @@ List the alert rules. Route: /api/v0/rules - - + - Input: - - + - Example: ```curl @@ -1008,7 +1008,7 @@ Add a new alert rule. Route: /api/v0/rules - - + - Input (JSON): @@ -1017,7 +1017,7 @@ Input (JSON): - severity: The severity level the alert will be raised against, Ok, Warning, Critical. - disabled: Whether the rule will be disabled or not, 0 = enabled, 1 = disabled - count: This is how many polling runs before an alert will trigger and the frequency. - - delay: Delay is when to start alerting and how frequently. The value is stored in seconds but you can specify minutes, hours or days by doing 5 m, 5 h, 5 d for each one. + - delay: Delay is when to start alerting and how frequently. The value is stored in seconds but you can specify minutes, hours or days by doing 5 m, 5 h, 5 d for each one. - mute: If mute is enabled then an alert will never be sent but will show up in the Web UI (true or false). - invert: This would invert the rules check. - name: This is the name of the rule and is mandatory. @@ -1043,7 +1043,7 @@ Edit an existing alert rule Route: /api/v0/rules - - + - Input (JSON): @@ -1053,7 +1053,7 @@ Input (JSON): - severity: The severity level the alert will be raised against, Ok, Warning, Critical. - disabled: Whether the rule will be disabled or not, 0 = enabled, 1 = disabled - count: This is how many polling runs before an alert will trigger and the frequency. - - delay: Delay is when to start alerting and how frequently. The value is stored in seconds but you can specify minutes, hours or days by doing 5 m, 5 h, 5 d for each one. + - delay: Delay is when to start alerting and how frequently. The value is stored in seconds but you can specify minutes, hours or days by doing 5 m, 5 h, 5 d for each one. - mute: If mute is enabled then an alert will never be sent but will show up in the Web UI (true or false). - invert: This would invert the rules check. - name: This is the name of the rule and is mandatory. diff --git a/doc/Developing/Code-Structure.md b/doc/Developing/Code-Structure.md index 32fe6a60a..9e1b4782a 100644 --- a/doc/Developing/Code-Structure.md +++ b/doc/Developing/Code-Structure.md @@ -14,7 +14,7 @@ This is the main file which all links within LibreNMS are parsed through. It loa ### html/css All used css files are located here. Apart from legacy files, anything in here is now a symlink. ### html/forms -This folder contains all of the files that are dynamically included from an ajax call to html/ajax_form.php. +This folder contains all of the files that are dynamically included from an ajax call to html/ajax_form.php. ### html/includes This is where the majority of the website core files are located. These tend to be files that contain functions or often used code segments that can be included where needed rather than duplicating code. ### html/includes/api_functions.inc.php diff --git a/doc/Developing/Dynamic-Config.md b/doc/Developing/Dynamic-Config.md index acc9d3079..14c97beba 100644 --- a/doc/Developing/Dynamic-Config.md +++ b/doc/Developing/Dynamic-Config.md @@ -1,6 +1,6 @@ # Adding new config options to WebUI -Adding support for users to update a new config option via the WebUI is now a lot easier for general options. This +Adding support for users to update a new config option via the WebUI is now a lot easier for general options. This document shows you how to add a new config option and even section to the WebUI. #### Update DB @@ -15,7 +15,7 @@ This will determine the default config option for `$config['alert']['tolerance_w #### Update WebUI -If the sub-section you want to add the new config option already exists then update the relevant file within +If the sub-section you want to add the new config option already exists then update the relevant file within `html/pages/settings/` otherwise you will need to create the new sub-section page. Here's an example of this: [Commit example](https://github.com/librenms/librenms/commit/c5998f9ee27acdac0c0f7d3092fc830c51ff684c) diff --git a/doc/Developing/Style-Guidelines.md b/doc/Developing/Style-Guidelines.md index d6acb1265..e8f06b78f 100644 --- a/doc/Developing/Style-Guidelines.md +++ b/doc/Developing/Style-Guidelines.md @@ -1,26 +1,26 @@ # Style guidelines -This document is here to help style standards for contributions towards LibreNMS. These aren't strict rules but it is in +This document is here to help style standards for contributions towards LibreNMS. These aren't strict rules but it is in the users interest that a consistent well thought out Web UI is available. ### Responsiveness -The Web UI is designed to be mobile friendly and for the most part is and works well. It's worth spending sometime to +The Web UI is designed to be mobile friendly and for the most part is and works well. It's worth spending sometime to read through the [Boostrap website](http://getbootstrap.com/css/#grid) to learn more about how to keep things responsive. ### Navigation bar -- Always pick the best location for new links to go, think about where users would expect the link to be located and name +- Always pick the best location for new links to go, think about where users would expect the link to be located and name it so that it's obvious what it does. - Ensure sub sections within the Navigation are separated correctly using ``. -- Only use [Font Awesome icons](http://fontawesome.io/icons/) within the Navigation. It speeds up page load times quite +- Only use [Font Awesome icons](http://fontawesome.io/icons/) within the Navigation. It speeds up page load times quite considerably. ### Buttons -Try to keep buttons colored to reflect the action they will take. Buttons are set using Bootstrap classes. The size of +Try to keep buttons colored to reflect the action they will take. Buttons are set using Bootstrap classes. The size of the buttons will depend on the area of the website being used but btn-sm is probably the most common. - Delete / Remove buttons: btn btn-danger @@ -31,20 +31,20 @@ the buttons will depend on the area of the website being used but btn-sm is prob ### Tables -Unless the table being used will only ever display a handful of items - yeah that's what we all said, then you need to -write your table using [JQuery Bootgrid](http://www.jquery-bootgrid.com/). This shouldn't take that much more code to -do this but provides so much flexibility along with stopping the need for retrieving all the data from SQL in the first +Unless the table being used will only ever display a handful of items - yeah that's what we all said, then you need to +write your table using [JQuery Bootgrid](http://www.jquery-bootgrid.com/). This shouldn't take that much more code to +do this but provides so much flexibility along with stopping the need for retrieving all the data from SQL in the first place. -As an example pull request, see [PR 706](https://github.com/librenms/librenms/pull/706/files) to get an idea of what +As an example pull request, see [PR 706](https://github.com/librenms/librenms/pull/706/files) to get an idea of what it's like to convert an existing pure html table to Bootgrid. ### Datetime format -When displaying datetimes, please ensure you use the format YYYY-MM-DD mm:hh:ss where possible, you shouldn't change the +When displaying datetimes, please ensure you use the format YYYY-MM-DD mm:hh:ss where possible, you shouldn't change the order of this as it will be confusing to users. Cutting it short to just display YYYY-MM-DD mm:hh is fine :). -To keep things consistent we have the following variables which should be used rather than to format dates yourself. +To keep things consistent we have the following variables which should be used rather than to format dates yourself. This has the added benefit that users can customise the format: ```php diff --git a/doc/Developing/Using-Git.md b/doc/Developing/Using-Git.md index ae2dc43fa..c66400405 100644 --- a/doc/Developing/Using-Git.md +++ b/doc/Developing/Using-Git.md @@ -8,7 +8,7 @@ Some assumptions: - LibreNMS is to be installed in /opt/librenms - You have git installed. - You have a [GitHub Account](https://github.com/). -- You are using ssh to connect to GitHub (If not, replace git@github.com:/yourusername/librenms.git with +- You are using ssh to connect to GitHub (If not, replace git@github.com:/yourusername/librenms.git with https://github.com/yourusername/librenms.git. ** Replace yourusername with your GitHub username. ** @@ -16,7 +16,7 @@ https://github.com/yourusername/librenms.git. #### Fork LibreNMS repo You do this directly within [GitHub](https://github.com/librenms/librenms/fork), click the 'Fork' button near the top right. -If you are associated with multiple organisations within GitHub then you might need to select which account you want to +If you are associated with multiple organisations within GitHub then you might need to select which account you want to push the fork to. #### Prepare your git environment @@ -29,7 +29,7 @@ git config --global user.email johndoe@example.com ``` #### Clone the repo -Ok so now that you have forked the repo, you now need to clone it to your local install where you can then make the +Ok so now that you have forked the repo, you now need to clone it to your local install where you can then make the changes you need and submit them back. ```bash @@ -50,7 +50,7 @@ Now you have two configured remotes: - upstream: This is the main LibreNMS repository and you can only pull changes. #### Workflow guide -As you become more familiar you may find a better workflow that fits your needs, until then this should be a safe +As you become more familiar you may find a better workflow that fits your needs, until then this should be a safe workflow for you to follow. Before you start work on a new branch / feature. Make sure you are upto date. @@ -61,19 +61,19 @@ git pull upstream master git push origin master ``` -Now, create a new branch to do you work on. It's important that you do this as you are then able to work on more than -one feature at a time and submit them as pull requests individually. If you did all your work in the master branch then +Now, create a new branch to do you work on. It's important that you do this as you are then able to work on more than +one feature at a time and submit them as pull requests individually. If you did all your work in the master branch then it gets a bit messy! -Ideally you want to create your new branch name based of the issue number. So firstly create an issue on -[GitHub](https://github.com/librenms/librenms/issues) so that others are aware of the work going on. If the issue number +Ideally you want to create your new branch name based of the issue number. So firstly create an issue on +[GitHub](https://github.com/librenms/librenms/issues) so that others are aware of the work going on. If the issue number you created is 123 then use issue-123 as the branch name. ```bash git checkout -b issue-123 ``` -Now, code away. Make the changes you need, test, change and test again :) When you are ready to submit the updates as a +Now, code away. Make the changes you need, test, change and test again :) When you are ready to submit the updates as a pull request then commit away. ```bash @@ -89,20 +89,20 @@ git push origin issue-123 If after do this you get some merge conflicts then you need to resolve these before carrying on. -Now you will be ready to submit a pull request from within GitHub. To do this, go to your GitHub page for the LibreNMS -repo. Now select the branch you have just been working on (issue-123) from the drop down to the left and then click +Now you will be ready to submit a pull request from within GitHub. To do this, go to your GitHub page for the LibreNMS +repo. Now select the branch you have just been working on (issue-123) from the drop down to the left and then click 'Pull Request'. Fill in the details to describe the work you have done and click 'Create pull request'. -Thanks for your first pull request :) Now, that might have been a simple update, if things get a bit more complicated -then you will need to break down your pull request into separate commits (still a single pull request). This is usually +Thanks for your first pull request :) Now, that might have been a simple update, if things get a bit more complicated +then you will need to break down your pull request into separate commits (still a single pull request). This is usually done when: - You want to add / update MIBS. Do this in a separate commit including the link to where you got them from. - You are adding say 3 related features in one go, try and break them down into 3 separate commits. - Icons for new OS support need to be added as a separate commit including a link to where you got the logo from. -Ok, that should get you started on the contributing path. If you have any other questions then stop by our IRC Channel -on Freenode ##librenms. +Ok, that should get you started on the contributing path. If you have any other questions then stop by our IRC Channel +on Freenode ##librenms. [1]: http://gitready.com [2]: http://git-scm.com/book \ No newline at end of file diff --git a/doc/Extensions/Agent-Setup.md b/doc/Extensions/Agent-Setup.md index f72e64f35..62a9ec473 100644 --- a/doc/Extensions/Agent-Setup.md +++ b/doc/Extensions/Agent-Setup.md @@ -65,7 +65,7 @@ options { ``` Restart your bind9/named after changing the configuration. -Verify that everything works by executing `rndc stats && cat /etc/bind/named.stats`. +Verify that everything works by executing `rndc stats && cat /etc/bind/named.stats`. In case you get a `Permission Denied` error, make sure you chown'ed correctly. Note: if you change the path you will need to change the path in `scripts/agent-local/bind`. @@ -75,26 +75,26 @@ Note: if you change the path you will need to change the path in `scripts/agent- __Installation__: 1. Get tinystats sources from http://www.morettoni.net/tinystats.en.html -2. Compile like as advised. - _Note_: In case you get `Makefile:9: *** missing separator. Stop.`, compile manually using: - * With IPv6: `gcc -Wall -O2 -fstack-protector -DWITH_IPV6 -o tinystats tinystats.c` - * Without IPv6: `gcc -Wall -O2 -fstack-protector -o tinystats tinystats.c` +2. Compile like as advised. + _Note_: In case you get `Makefile:9: *** missing separator. Stop.`, compile manually using: + * With IPv6: `gcc -Wall -O2 -fstack-protector -DWITH_IPV6 -o tinystats tinystats.c` + * Without IPv6: `gcc -Wall -O2 -fstack-protector -o tinystats tinystats.c` 3. Install into preferred path, like `/usr/bin/`. __Configuration__: -_Note_: In this part we assume that you use DJB's [Daemontools](http://cr.yp.to/daemontools.html) to start/stop tinydns. +_Note_: In this part we assume that you use DJB's [Daemontools](http://cr.yp.to/daemontools.html) to start/stop tinydns. And that your tinydns-instance is located in `/service/dns`, adjust this path if necessary. -1. Replace your _log_'s `run` file, typically located in `/service/dns/log/run` with: +1. Replace your _log_'s `run` file, typically located in `/service/dns/log/run` with: ``` #!/bin/sh - + exec setuidgid dnslog tinystats ./main/tinystats/ multilog t n3 s250000 ./main/ ``` -2. Create tinystats directory and chown: +2. Create tinystats directory and chown: `mkdir /service/dns/log/main/tinystats && chown dnslog:nofiles /service/dns/log/main/tinystats` -3. Restart TinyDNS and Daemontools: `/etc/init.d/svscan restart` +3. Restart TinyDNS and Daemontools: `/etc/init.d/svscan restart` _Note_: Some say `svc -t /service/dns` is enough, on my install (Gentoo) it doesn't rehook the logging and I'm forced to restart it entirely. ### MySQL diff --git a/doc/Extensions/Alerting.md b/doc/Extensions/Alerting.md index 02d1958e9..87a542a7c 100644 --- a/doc/Extensions/Alerting.md +++ b/doc/Extensions/Alerting.md @@ -38,7 +38,7 @@ Table of Content: # About -LibreNMS includes a highly customizable alerting system. +LibreNMS includes a highly customizable alerting system. The system requires a set of user-defined rules to evaluate the situation of each device, port, service or any other entity. > You can configure all options for alerting and transports via the WebUI, config options in this document are crossed out but left for reference. @@ -47,15 +47,15 @@ This document only covers the usage of it. See the [DEVELOPMENT.md](https://gith # Rules -Rules are defined using a logical language. -The GUI provides a simple way of creating basic as well as complex Rules in a self-describing manner. +Rules are defined using a logical language. +The GUI provides a simple way of creating basic as well as complex Rules in a self-describing manner. More complex rules can be written manually. ## Syntax -Rules must consist of at least 3 elements: An __Entity__, a __Condition__ and a __Value__. -Rules can contain braces and __Glues__. -__Entities__ are provided as `%`-Noted pair of Table and Field. For Example: `%ports.ifOperStatus`. +Rules must consist of at least 3 elements: An __Entity__, a __Condition__ and a __Value__. +Rules can contain braces and __Glues__. +__Entities__ are provided as `%`-Noted pair of Table and Field. For Example: `%ports.ifOperStatus`. __Conditions__ can be any of: - Equals `=` @@ -67,10 +67,10 @@ __Conditions__ can be any of: - Smaller `<` - Smaller or Equal `<=` -__Values__ can be Entities or any single-quoted data. +__Values__ can be Entities or any single-quoted data. __Glues__ can be either `&&` for `AND` or `||` for `OR`. -__Note__: The difference between `Equals` and `Matches` (and its negation) is that `Equals` does a strict comparison and `Matches` allows the usage of RegExp. +__Note__: The difference between `Equals` and `Matches` (and its negation) is that `Equals` does a strict comparison and `Matches` allows the usage of RegExp. Arithmetics are allowed as well. ## Examples @@ -90,17 +90,17 @@ Alert when: # Templates -Templates can be assigned to a single or a group of rules. -They can contain any kind of text. -The template-parser understands `if` and `foreach` controls and replaces certain placeholders with information gathered about the alert. +Templates can be assigned to a single or a group of rules. +They can contain any kind of text. +The template-parser understands `if` and `foreach` controls and replaces certain placeholders with information gathered about the alert. ## Syntax Controls: -- if-else (Else can be omitted): +- if-else (Else can be omitted): `{if %placeholder == 'value'}Some Text{else}Other Text{/if}` -- foreach-loop: +- foreach-loop: `{foreach %placeholder}Key: %key
Value: %value{/foreach}` Placeholders: @@ -123,7 +123,7 @@ Templates can be matched against several rules. ## Examples -Default Template: +Default Template: ```text %title\r\n Severity: %severity\r\n @@ -138,13 +138,13 @@ Alert sent to: {foreach %contacts}%value <%key> {/foreach} # Transports -Transports are located within `$config['install_dir']/includes/alerts/transports.*.php` and defined as well as configured via ~~`$config['alert']['transports']['Example'] = 'Some Options'`~~. +Transports are located within `$config['install_dir']/includes/alerts/transports.*.php` and defined as well as configured via ~~`$config['alert']['transports']['Example'] = 'Some Options'`~~. -Contacts will be gathered automatically and passed to the configured transports. +Contacts will be gathered automatically and passed to the configured transports. By default the Contacts will be only gathered when the alert triggers and will ignore future changes in contacts for the incident. If you want contacts to be re-gathered before each dispatch, please set ~~`$config['alert']['fixed-contacts'] = false;`~~ in your config.php. -The contacts will always include the `SysContact` defined in the Device's SNMP configuration and also every LibreNMS-User that has at least `read`-permissions on the entity that is to be alerted. -At the moment LibreNMS only supports Port or Device permissions. +The contacts will always include the `SysContact` defined in the Device's SNMP configuration and also every LibreNMS-User that has at least `read`-permissions on the entity that is to be alerted. +At the moment LibreNMS only supports Port or Device permissions. You can exclude the `SysContact` by setting: ~~ ```php @@ -170,7 +170,7 @@ $config['alert']['transports']['mail'] = true; ``` ~~ -The E-Mail transports uses the same email-configuration like the rest of LibreNMS. +The E-Mail transports uses the same email-configuration like the rest of LibreNMS. As a small reminder, here is it's configuration directives including defaults: ~~ ```php @@ -195,13 +195,13 @@ $config['alert']['default_mail'] = ''; //Default ema > You can configure these options within the WebUI now, please avoid setting these options within config.php -API transports definitions are a bit more complex than the E-Mail configuration. -The basis for configuration is ~~`$config['alert']['transports']['api'][METHOD]`~~ where `METHOD` can be `get`,`post` or `put`. -This basis has to contain an array with URLs of each API to call. -The URL can have the same placeholders as defined in the [Template-Syntax](#templates-syntax). -If the `METHOD` is `get`, all placeholders will be URL-Encoded. -The API transport uses cURL to call the APIs, therefore you might need to install `php5-curl` or similar in order to make it work. -__Note__: it is highly recommended to define own [Templates](#templates) when you want to use the API transport. The default template might exceed URL-length for GET requests and therefore cause all sorts of errors. +API transports definitions are a bit more complex than the E-Mail configuration. +The basis for configuration is ~~`$config['alert']['transports']['api'][METHOD]`~~ where `METHOD` can be `get`,`post` or `put`. +This basis has to contain an array with URLs of each API to call. +The URL can have the same placeholders as defined in the [Template-Syntax](#templates-syntax). +If the `METHOD` is `get`, all placeholders will be URL-Encoded. +The API transport uses cURL to call the APIs, therefore you might need to install `php5-curl` or similar in order to make it work. +__Note__: it is highly recommended to define own [Templates](#templates) when you want to use the API transport. The default template might exceed URL-length for GET requests and therefore cause all sorts of errors. Example: ~~ @@ -214,7 +214,7 @@ $config['alert']['transports']['api']['get'][] = "https://api.thirdparti.es/issu > You can configure these options within the WebUI now, please avoid setting these options within config.php -The nagios transport will feed a FIFO at the defined location with the same format that nagios would. +The nagios transport will feed a FIFO at the defined location with the same format that nagios would. This allows you to use other Alerting-Systems to work with LibreNMS, for example [Flapjack](http://flapjack.io). ~~ ```php @@ -226,7 +226,7 @@ $config['alert']['transports']['nagios'] = "/path/to/my.fifo"; //Flapjack expect > You can configure these options within the WebUI now, please avoid setting these options within config.php -The IRC transports only works together with the LibreNMS IRC-Bot. +The IRC transports only works together with the LibreNMS IRC-Bot. Configuration of the LibreNMS IRC-Bot is described [here](https://github.com/librenms/librenms/blob/master/doc/Extensions/IRC-Bot.md). ~~ ```php @@ -349,7 +349,7 @@ $config['alert']['transports']['pushover'][] = array( ## Boxcar -Enabling Boxcar support is super easy. +Enabling Boxcar support is super easy. Copy your access token from the Boxcar app or from the Boxcar.io website and setup the transport in your config.php like: ~~ @@ -384,7 +384,7 @@ $config['alert']['transports']['pushbullet'] = 'MYFANCYACCESSTOKEN'; ## Clickatell -Clickatell provides a REST-API requiring an Authorization-Token and at least one Cellphone number. +Clickatell provides a REST-API requiring an Authorization-Token and at least one Cellphone number. Please consult Clickatell's documentation regarding number formatting. Here an example using 3 numbers, any amount of numbers is supported: @@ -399,8 +399,8 @@ $config['alert']['transports']['clickatell']['to'][] = '+1234567892'; ## PlaySMS -PlaySMS is an OpenSource SMS-Gateway that can be used via their HTTP-API using a Username and WebService-Token. -Please consult PlaySMS's documentation regarding number formating. +PlaySMS is an OpenSource SMS-Gateway that can be used via their HTTP-API using a Username and WebService-Token. +Please consult PlaySMS's documentation regarding number formating. Here an example using 3 numbers, any amount of numbers is supported: ~~ diff --git a/doc/Extensions/Authentication.md b/doc/Extensions/Authentication.md index 2f0a0eccc..d84145db6 100644 --- a/doc/Extensions/Authentication.md +++ b/doc/Extensions/Authentication.md @@ -1,6 +1,6 @@ # Authentication modules -LibreNMS supports multiple authentication modules along with [Two Factor Auth](http://docs.librenms.org/Extensions/Two-Factor-Auth/). +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 @@ -50,9 +50,9 @@ $config['db_name'] = "DBNAME"; 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 +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: @@ -132,7 +132,7 @@ If you have issues with secure LDAP try setting `$config['auth_ad_check_certific ##### Require actual membership of the configured groups -If you set ```$config['auth_ad_require_groupmembership']``` to 1, the authenticated user has to be a member of the specific group. Otherwise all users can authenticate, but are limited to user level 0 and only have access to shared dashboards. +If you set ```$config['auth_ad_require_groupmembership']``` to 1, the authenticated user has to be a member of the specific group. Otherwise all users can authenticate, but are limited to user level 0 and only have access to shared dashboards. > Cleanup of old accounts is done using the authlog. You will need to set the cleanup date for when old accounts will be purged which will happen AUTOMATICALLY. > Please ensure that you set the $config['authlog_purge'] value to be greater than $config['active_directory]['users_purge'] otherwise old users won't be removed. @@ -163,5 +163,5 @@ $config['radius']['port'] = '1812'; $config['radius']['secret'] = 'testing123'; $config['radius']['timeout'] = 3; $config['radius']['users_purge'] = 14;//Purge users who haven't logged in for 14 days. -$config['radius']['default_level'] = 1;//Set the default user level when automatically creating a user. +$config['radius']['default_level'] = 1;//Set the default user level when automatically creating a user. ``` diff --git a/doc/Extensions/Component.md b/doc/Extensions/Component.md index 235335380..40331981d 100644 --- a/doc/Extensions/Component.md +++ b/doc/Extensions/Component.md @@ -118,7 +118,7 @@ $ARRAY = $COMPONENT->getComponents($DEVICE_ID,$OPTIONS); [status] => 0 [ignore] => 1 [disabled] => 1 - [error] => + [error] => ), [Y2] => Array ( @@ -129,7 +129,7 @@ $ARRAY = $COMPONENT->getComponents($DEVICE_ID,$OPTIONS); [status] => 0 [ignore] => 1 [disabled] => 0 - [error] => + [error] => ), ) ) @@ -155,7 +155,7 @@ Where: There are 2 filtering shortcuts: - + $DEVICE_ID is a synonym for: ```php @@ -201,11 +201,11 @@ This will return a new, empty array with a component ID and Type set, all other [1] => Array ( [type] => TESTING - [label] => + [label] => [status] => 1 [ignore] => 0 [disabled] => 0 - [error] => + [error] => ) ) diff --git a/doc/Extensions/Device-Groups.md b/doc/Extensions/Device-Groups.md index c38db06a8..f7207b195 100644 --- a/doc/Extensions/Device-Groups.md +++ b/doc/Extensions/Device-Groups.md @@ -4,10 +4,10 @@ LibreNMS supports grouping your devices together in much the same way as you can ### Pattern -Patterns work in the same was as Entities within the alerting system, the format of the pattern is based on the MySQL structure your data is in such +Patterns work in the same was as Entities within the alerting system, the format of the pattern is based on the MySQL structure your data is in such as __tablename.columnname__. If you are ensure of what the entity is you want then have a 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 you hostname format is dcX.[devicetype].example.com. You would use the pattern +As a working example and a common question, let's assume you want to group devices by hostname. If you hostname format is dcX.[devicetype].example.com. You would use the pattern devices.hostname. Select the condition which in this case would Like and then enter `dc1\..*\.example.com`. This would then match dc1.sw01.example.com, dc1.rtr01.example.com but not dc2.sw01.example.com. @@ -23,8 +23,8 @@ Please see our [Alerting docs](http://docs.librenms.org/Extensions/Alerting/#syn ### Connection -If you only want to group based on one pattern then select And. If however you want to build a group based on multiple patterns then you can build a SQL like +If you only want to group based on one pattern then select And. If however you want to build a group based on multiple patterns then you can build a SQL like query using And / Or. As an example, we want to base our group on the devices hostname AND it's type. Use the pattern as before, devices.hostname, select the condition which in this case would Like and then enter dc1.@.example.com then click And. Now enter devices.type in the pattern, select Equals and enter firewall. This would then match dc1.fw01.example.com but not dc1.sw01.example.com as that is a network type. -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/Distributed-Poller.md b/doc/Extensions/Distributed-Poller.md index ee706a8b7..97b9cb253 100644 --- a/doc/Extensions/Distributed-Poller.md +++ b/doc/Extensions/Distributed-Poller.md @@ -7,13 +7,13 @@ Devices can also be groupped together into a `poller_group` to pin these devices ~~All pollers need to share their RRD-folder, for example via NFS or a combination of NFS and rrdcached.~~ -> This is no longer a strict requirement with the use of rrdtool 1.5 and above. If you are NOT running 1.5 then you will still +> This is no longer a strict requirement with the use of rrdtool 1.5 and above. If you are NOT running 1.5 then you will still need to share the RRD-folder. It is also required that all pollers can access the central memcached to communicate with eachother. -In order to enable distributed polling, set `$config['distributed_poller'] = true` and your memcached details into `$config['distributed_poller_memcached_host']` and `$config['distributed_poller_memcached_port']`. -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']`. +In order to enable distributed polling, set `$config['distributed_poller'] = true` and your memcached details into `$config['distributed_poller_memcached_host']` and `$config['distributed_poller_memcached_port']`. +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']`. Usually the poller's name is equal to the machine's hostname, if you want to change it set `$config['distributed_poller_name']`. One can also specify a comma seperated 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. @@ -55,7 +55,7 @@ Central storage should be provided so all RRD files can be read from and written For this example, we are running RRDCached to allow all pollers and web/api servers to read/write to the rrd iles ~~with the rrd directory also exported by NFS for simple access and maintenance.~~ -Sharing rrd files via something like NFS is no longer required if you run rrdtool 1.5 or greater. If you don't - please share your rrd folder as before. If you run rrdtool +Sharing rrd files via something like NFS is no longer required if you run rrdtool 1.5 or greater. If you don't - please share your rrd folder as before. If you run rrdtool 1.5 or greater then add this config to your pollers: ```php diff --git a/doc/Extensions/Globe-Frontpage.md b/doc/Extensions/Globe-Frontpage.md index adac26f45..6e2d31662 100644 --- a/doc/Extensions/Globe-Frontpage.md +++ b/doc/Extensions/Globe-Frontpage.md @@ -31,7 +31,7 @@ $config['leaflet']['default_zoom'] = 8; ### Jquery-Mapael config -Further custom options are available to load different maps of the world, set default coordinates of where the map will zoom and the zoom level by default. An example of +Further custom options are available to load different maps of the world, set default coordinates of where the map will zoom and the zoom level by default. An example of this is: ```php diff --git a/doc/Extensions/Graylog.md b/doc/Extensions/Graylog.md index 7dd6654ce..1c0da5501 100644 --- a/doc/Extensions/Graylog.md +++ b/doc/Extensions/Graylog.md @@ -1,10 +1,10 @@ # Graylog integration -We have simple integration for Graylog, you will be able to view any logs from within LibreNMS that have been parsed by the syslog input from within -Graylog itself. This includes logs from devices which aren't in LibreNMS still, you can also see logs for a specific device under the logs section +We have simple integration for Graylog, you will be able to view any logs from within LibreNMS that have been parsed by the syslog input from within +Graylog itself. This includes logs from devices which aren't in LibreNMS still, you can also see logs for a specific device under the logs section for the device. -Graylog itself isn't included within LibreNMS, you will need to install this separately either on the same infrastructure as LibreNMS or as a totally +Graylog itself isn't included within LibreNMS, you will need to install this separately either on the same infrastructure as LibreNMS or as a totally standalone appliance. Config is simple, here's an example: diff --git a/doc/Extensions/IRC-Bot-Extensions.md b/doc/Extensions/IRC-Bot-Extensions.md index 0debac380..71f6d1180 100644 --- a/doc/Extensions/IRC-Bot-Extensions.md +++ b/doc/Extensions/IRC-Bot-Extensions.md @@ -41,7 +41,7 @@ Function( (Type) $Variable [= Default] [,...] ) | Returns | Description ### Attributes Attribute | Type | Description ---- | --- | --- +--- | --- | --- `$params` | `String` | Contains all arguments that are passed to the `.command`. `$this->chan` | `Array` | Channels that are configured. `$this->commands` | `Array` | Contains accessible `commands`. diff --git a/doc/Extensions/InfluxDB.md b/doc/Extensions/InfluxDB.md index e96d3393b..d24b441f3 100644 --- a/doc/Extensions/InfluxDB.md +++ b/doc/Extensions/InfluxDB.md @@ -1,15 +1,15 @@ # Enabling support for InfluxDB. -Before we get started it is important that you know and understand that InfluxDB support is currently alpha at best. -All it provides is the sending of data to a InfluxDB install. Due to the current changes that are constantly being -made to InfluxDB itself then we cannot guarantee that your data will be ok so enabling this support is at your own +Before we get started it is important that you know and understand that InfluxDB support is currently alpha at best. +All it provides is the sending of data to a InfluxDB install. Due to the current changes that are constantly being +made to InfluxDB itself then we cannot guarantee that your data will be ok so enabling this support is at your own risk! ### Requirements - InfluxDB 0.94 - Grafana -The setup of the above is completely out of scope here and we aren't really able to provide any help with this side +The setup of the above is completely out of scope here and we aren't really able to provide any help with this side of things. ### What you don't get @@ -31,5 +31,5 @@ $config['influxdb']['password'] = 'admin'; UDP is a supported transport and no credentials are needed if you don't use InfluxDB authentication. -The same data then stored within rrd will be sent to InfluxDB and recorded. You can then create graphs within Grafana +The same data then stored within rrd will be sent to InfluxDB and recorded. You can then create graphs within Grafana to display the information you need. diff --git a/doc/Extensions/Network-Map.md b/doc/Extensions/Network-Map.md index 63a74352c..c0e580ae5 100644 --- a/doc/Extensions/Network-Map.md +++ b/doc/Extensions/Network-Map.md @@ -13,10 +13,10 @@ $config['network_map_items'] = array('mac','xdp'); Either remove mac or xdp depending on which you want. -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. +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. -One can also specicify the parameters to be used for drawing and updating the network map. +One can also specicify the parameters to be used for drawing and updating the network map. Please see http://visjs.org/docs/network/ for details on the configuration parameters. ```php $config['network_map_vis_options'] = '{ diff --git a/doc/Extensions/Oxidized.md b/doc/Extensions/Oxidized.md index 23153780b..e74bf5c3c 100644 --- a/doc/Extensions/Oxidized.md +++ b/doc/Extensions/Oxidized.md @@ -4,7 +4,7 @@ You can integrate LibreNMS with [Oxidized](https://github.com/ytti/oxidized-web) ### Config viewing -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. +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 diff --git a/doc/Extensions/Port-Description-Parser.md b/doc/Extensions/Port-Description-Parser.md index ccdf8740d..f07a2878e 100644 --- a/doc/Extensions/Port-Description-Parser.md +++ b/doc/Extensions/Port-Description-Parser.md @@ -9,7 +9,7 @@ The following information is used from interface descriptions: - Notes - Speed -When setting the description, you use the type followed directly with : and then the information on that port. Some examples based on +When setting the description, you use the type followed directly with : and then the information on that port. Some examples based on configuring a Cisco 2960 interface #### Customer port diff --git a/doc/Extensions/RRDCached.md b/doc/Extensions/RRDCached.md index 4728686fe..f6059234e 100644 --- a/doc/Extensions/RRDCached.md +++ b/doc/Extensions/RRDCached.md @@ -2,7 +2,7 @@ This document will explain how to setup RRDCached for LibreNMS. -> If you are using rrdtool / rrdcached version 1.5 or above then this now supports creating rrd files over rrdcached. To +> If you are using rrdtool / rrdcached version 1.5 or above then this now supports creating rrd files over rrdcached. To enable this set the following config: ```php @@ -21,7 +21,7 @@ vi /etc/yum.repos.d/rpmforge.repo ```ssh yum update rrdtool -vi /etc/yum.repos.d/rpmforge.repo +vi /etc/yum.repos.d/rpmforge.repo ``` - Disable the [rpmforge] and [rpmforge-extras] repos again diff --git a/doc/Extensions/RRDTune.md b/doc/Extensions/RRDTune.md index 7ee7095d2..c7a961ffc 100644 --- a/doc/Extensions/RRDTune.md +++ b/doc/Extensions/RRDTune.md @@ -1,6 +1,6 @@ # 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 +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! @@ -9,7 +9,7 @@ To enable this you can do so in three ways! - For the actual device, Edit Device -> Misc - For each port, Edit Device -> Port Settings -Now when a port interface speed changes (this can happen because of a physical change or just because the device has mis-reported) the max value is set. If you don't want to wait until +Now when a port interface speed changes (this can happen because of a physical change or just because the device has mis-reported) the max value is set. If you don't want to wait until a port speed changes then you can run the included script: script/tune_port.php -h -p diff --git a/doc/Extensions/Services.md b/doc/Extensions/Services.md index dba098588..fe2608552 100644 --- a/doc/Extensions/Services.md +++ b/doc/Extensions/Services.md @@ -2,7 +2,7 @@ Services within LibreNMS provides the ability to use Nagios plugins to perform additional monitoring outside of SNMP. -These services are tied into an existing device so you need at least one device that supports SNMP to be able to add it +These services are tied into an existing device so you need at least one device that supports SNMP to be able to add it to LibreNMS - localhost is a good one. ## Setup @@ -29,7 +29,7 @@ Finally, you now need to add check-services.php to the current cron file (/etc/c Now you can add services via the main Services link in the navbar, or via the Services link within the device page. -> **Please note that at present the service checks will only return the status and the response from the check +> **Please note that at present the service checks will only return the status and the response from the check no graphs will be generated. ** ## Supported checks diff --git a/doc/Extensions/Smokeping.md b/doc/Extensions/Smokeping.md index c04436eb7..92c4e6078 100644 --- a/doc/Extensions/Smokeping.md +++ b/doc/Extensions/Smokeping.md @@ -1,6 +1,6 @@ # Smokeping integration -We currently have two ways to use Smokeping with LibreNMS, the first is using the included script generator to generate the config for Smokeping. The +We currently have two ways to use Smokeping with LibreNMS, the first is using the included script generator to generate the config for Smokeping. The second is to utilise an existing Smokeping setup. ### Included Smokeping script @@ -11,7 +11,7 @@ To use this, please add something similar to your smokeping config file: @include /opt/smokeping/etc/librenms.conf ``` -Then you need to generate the config file (maybe even add a cron to schedule this in and reload smokeping). We've assumed a few locations for smokeping, the config file you want +Then you need to generate the config file (maybe even add a cron to schedule this in and reload smokeping). We've assumed a few locations for smokeping, the config file you want to call it and where LibreNMS is: ```bash diff --git a/doc/Extensions/Sub-Directory.md b/doc/Extensions/Sub-Directory.md index 11a74d67c..a5a99a4b8 100644 --- a/doc/Extensions/Sub-Directory.md +++ b/doc/Extensions/Sub-Directory.md @@ -1,6 +1,6 @@ -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 @@ -14,7 +14,7 @@ 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/, +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, ensure `$config["base_url"]` -- if configured -- is correct as well. diff --git a/doc/Extensions/Syslog.md b/doc/Extensions/Syslog.md index b34f9405a..cb0ef8a0b 100644 --- a/doc/Extensions/Syslog.md +++ b/doc/Extensions/Syslog.md @@ -33,7 +33,7 @@ options { stats_freq(0); bad_hostname("^gconfd$"); }; - + ######################## # Sources ######################## @@ -41,19 +41,19 @@ source s_sys { system(); internal(); }; - + source s_net { tcp(port(514) flags(syslog-protocol)); udp(port(514) flags(syslog-protocol)); }; - + ######################## # Destinations ######################## destination d_librenms { program("/opt/librenms/syslog.php" template ("$HOST||$FACILITY||$PRIORITY||$LEVEL||$TAG||$YEAR-$MONTH-$DAY $HOUR:$MIN:$SEC||$MSG||$PROGRAM\n") template-escape(yes)); }; - + ######################## # Log paths ######################## @@ -62,7 +62,7 @@ log { source(s_sys); destination(d_librenms); }; - + ### # Include all config files in /etc/syslog-ng/conf.d/ ### diff --git a/doc/Extensions/Two-Factor-Auth.md b/doc/Extensions/Two-Factor-Auth.md index 0b9c7513a..1ee4a9b20 100644 --- a/doc/Extensions/Two-Factor-Auth.md +++ b/doc/Extensions/Two-Factor-Auth.md @@ -9,32 +9,32 @@ Table of Content: # 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. +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. +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. +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. ## 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. +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 upto +/- 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. +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 upto +4 increments from the actual counter to create passcodes. # Configuration diff --git a/doc/Extensions/Varnish.md b/doc/Extensions/Varnish.md index 98fda2adf..78cced5a9 100644 --- a/doc/Extensions/Varnish.md +++ b/doc/Extensions/Varnish.md @@ -11,7 +11,7 @@ Varnish is caching software that sits logically between an HTTP client and an HT ### CentOS 7 Varnish Installation ### -In this example we will assume your Apache 2.4.X HTTP server is working and +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 [Using HTTPd Apache2](http://librenms.readthedocs.org/Installation/Installation-(RHEL-CentOS)/#using-httpd-apache2) @@ -30,7 +30,7 @@ By default Varnish listens for HTTP requests on port 6081. - Temporarily add a firewalld rule for testing Varnish. ```bash -firewall-cmd --zone=public --add-port=6081/tcp +firewall-cmd --zone=public --add-port=6081/tcp ``` #### Test Varnish #### @@ -127,16 +127,16 @@ Edit librenms.conf and modify the Apache Virtual Host listening port. - Modify:`` to: `` ```bash -vim /etc/httpd/conf.d/librenms.conf +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 +```bash vim /etc/httpd/conf/httpd.conf ``` - + - Create the librenms.vcl ```bash cd /etc/varnish @@ -205,7 +205,7 @@ sub vcl_backend_response { # 'sub vcl_backend_response' is the same function as 'sub vcl_fetch' in Varnish 3, however, # the syntax is slightly different # This function happens after we read the response headers from the backend (Apache). - # First function 'if (bereq.url ~ "\' removes cookies from the Apache HTTP responses + # First function 'if (bereq.url ~ "\' removes cookies from the Apache HTTP responses # that match the file extensions that are between the quotes, and cache the files for 24 hours. # This assumes you update LibreNMS once a day, otherwise restart Varnish to clear cache. # Second function 'if (bereq.url ~ "^/' removes the Pragma no-cache statements and sets the age diff --git a/doc/General/Changelog.md b/doc/General/Changelog.md index 67d4e2bf0..60a0cbfb0 100644 --- a/doc/General/Changelog.md +++ b/doc/General/Changelog.md @@ -623,7 +623,7 @@ - Enable alerting on tables with relative / indirect glues (PR932) - Added bills support in rulesuggest and alert system (PR934) - Added detection for Sentry Smart CDU (PR938) - - Added basic detection for Netgear devices (PR942) + - Added basic detection for Netgear devices (PR942) - addhost.php now uses distributed_poller_group config if set (PR944) - Added port rewrite function (PR946) - Added basic detection for Ubiquiti Edgeswitch (PR947) @@ -921,7 +921,7 @@ - Fixed layout issue for ports list (PR286) - Removed session regeneration (PR287) - Updated edit button on edit user screen (PR288) - + ####Improvements - Added email field for add user form (PR278) - V0 of API release (PR282) @@ -1043,7 +1043,7 @@ ###Nov 2013 ####Bug fixes - - Updates to fix arp discovery + - Updates to fix arp discovery ####Improvements - Added poller-wrapper (f8debf4) diff --git a/doc/General/Contributing.md b/doc/General/Contributing.md index 31d7b0bc1..09353800c 100644 --- a/doc/General/Contributing.md +++ b/doc/General/Contributing.md @@ -170,7 +170,7 @@ project. Proposed workflow for submitting pull requests ---------------------------------------------- -Please see the new [Using Git](http://docs.librenms.org/Developing/Using-Git/) document which gives you step-by-step +Please see the new [Using Git](http://docs.librenms.org/Developing/Using-Git/) document which gives you step-by-step instructions on using git to submit a pull request. [1]: http://www.gnu.org/licenses/license-list.html diff --git a/doc/Installation/Installation-(RHEL-CentOS).md b/doc/Installation/Installation-(RHEL-CentOS).md index b899aa242..493b8a746 100644 --- a/doc/Installation/Installation-(RHEL-CentOS).md +++ b/doc/Installation/Installation-(RHEL-CentOS).md @@ -153,8 +153,8 @@ Next, add the following to `/etc/httpd/conf.d/librenms.conf` ``` -__Notes:__ -If you are running Apache 2.2.18 or higher then change `AllowEncodedSlashes` to `NoDecode` and append `Require all granted` underneath `Options FollowSymLinks MultiViews`. +__Notes:__ +If you are running Apache 2.2.18 or higher then change `AllowEncodedSlashes` to `NoDecode` and append `Require all granted` underneath `Options FollowSymLinks MultiViews`. If the file `/etc/httpd/conf.d/welcome.conf` exists, you might want to remove that as well unless you're familiar with [Name-based Virtual Hosts](https://httpd.apache.org/docs/2.2/vhosts/name-based.html) ### Using Nginx and PHP-FPM ### diff --git a/doc/Support/Configuration.md b/doc/Support/Configuration.md index 15be9ed6c..4197a3c26 100644 --- a/doc/Support/Configuration.md +++ b/doc/Support/Configuration.md @@ -60,7 +60,7 @@ $config['fping_options']['millisec'] = 200; * `millisec` (`fping` parameter `-p`): Time in milliseconds that fping waits between successive packets to an individual target. You can disable the fping / icmp check that is done for a device to be determined to be up on a global or per device basis. -**We don't advice disabling the fping / icmp check unless you know the impact, at worst if you have a large number of devices down +**We don't advice disabling the fping / icmp check unless you know the impact, at worst if you have a large number of devices down then it's possible that the poller would no longer complete in 5 minutes due to waiting for snmp to timeout.** Globally disable fping / icmp check: @@ -107,7 +107,7 @@ $config['rrdcached'] = "unix:/var/run/rrdcached.sock"; // or a tcp connection $config['rrdcached_dir'] = FALSE; ``` To enable rrdcached you need to set at least the `rrdcached` option. If `rrdcached` is a tcp socket then you need to configure `rrdcached_dir` as well. -This should be set based on your base directory for running rrdcached. For instance if -b for rrdcached is set to /var/lib/rrd but you are expecting +This should be set based on your base directory for running rrdcached. For instance if -b for rrdcached is set to /var/lib/rrd but you are expecting LibreNMS to store them in /var/lib/rrd/librenms then you would need to set `rrdcached_dir` to librenms. #### WebUI Settings @@ -141,7 +141,7 @@ $config['vertical_summary'] = 0; // Enable to use vertical summary on front page $config['top_ports'] = 1; // This enables the top X ports box $config['top_devices'] = 1; // This enables the top X devices box ``` -A number of home pages are provided within the install and can be found in html/pages/front/. You can change the default by +A number of home pages are provided within the install and can be found in html/pages/front/. You can change the default by setting `front_page`. The other options are used to alter the look of those pages that support it (default.php supports these options). ```php @@ -289,7 +289,7 @@ $config['email_smtp_auth'] = FALSE; $config['email_smtp_username'] = NULL; $config['email_smtp_password'] = NULL; ``` -What type of mail transport to use for delivering emails. Valid options for `email_backend` are mail, sendmail or smtp. +What type of mail transport to use for delivering emails. Valid options for `email_backend` are mail, sendmail or smtp. The varying options after that are to support the different transports. #### Alerting @@ -333,14 +333,14 @@ Enable / disable additional port statistics. $config['rancid_configs'][] = '/var/lib/rancid/network/configs/'; $config['rancid_ignorecomments'] = 0; ``` -Rancid configuration, `rancid_configs` is an array containing all of the locations of your rancid files. +Rancid configuration, `rancid_configs` is an array containing all of the locations of your rancid files. Setting `rancid_ignorecomments` will disable showing lines that start with # ```php $config['oxidized']['enabled'] = FALSE; $config['oxidized']['url'] = 'http://127.0.0.1:8888'; ``` -To enable Oxidized support set enabled to `TRUE`. URL needs to be configured to point to the REST API for Oxidized. This +To enable Oxidized support set enabled to `TRUE`. URL needs to be configured to point to the REST API for Oxidized. This is then used to retrieve the config for devices. @@ -390,7 +390,7 @@ The above is an example, this will rewrite basic snmp locations so you don't nee $config['bad_if'][] = "voip-null"; $config['bad_iftype'][] = "voiceEncap"; ``` -Numerous defaults exist for this array already (see includes/defaults.inc.php for the full list). You can expand this list +Numerous defaults exist for this array already (see includes/defaults.inc.php for the full list). You can expand this list by continuing the array. `bad_if` is matched against the ifDescr value. `bad_iftype` is matched against the ifType value. @@ -446,8 +446,8 @@ Please see [IRC Bot](http://docs.librenms.org/Extensions/IRC-Bot/) section of th ```php $config['auth_mechanism'] = "mysql"; ``` -This is the authentication type to use for the WebUI. MySQL is the default and configured when following the installation -instructions. ldap and http-auth are also valid options. For instructions on the different authentication modules please +This is the authentication type to use for the WebUI. MySQL is the default and configured when following the installation +instructions. ldap and http-auth are also valid options. For instructions on the different authentication modules please see [Authentication](http://docs.librenms.org/Extensions/Authentication/). ```php @@ -459,7 +459,7 @@ If the user selects to be remembered on the login page, how long in days do we r $config['allow_unauth_graphs'] = 0; $config['allow_unauth_graphs_cidr'] = array(); ``` -This option will enable unauthenticated access to the graphs from `allow_unauth_graphs_cidr` ranges that you allow. Use +This option will enable unauthenticated access to the graphs from `allow_unauth_graphs_cidr` ranges that you allow. Use of this option is highly discouraged in favour of the [API](http://docs.librenms.org/API/API-Docs/) that is now available. #### Cleanup options @@ -473,7 +473,7 @@ $config['authlog_purge'] = 30; $config['perf_times_purge'] = 30; $config['device_perf_purge'] = 30; ``` -This option will ensure data within LibreNMS over 1 month old is automatically purged. You can alter these individually, +This option will ensure data within LibreNMS over 1 month old is automatically purged. You can alter these individually, values are in days. #### Syslog options @@ -504,7 +504,7 @@ to indicate how you connect to libvirt. You also need to: To test your setup, run `virsh -c qemu+ssh://vmhost/system list` or `virsh -c xen+ssh://vmhost list` as your librenms polling user. - + #### BGP Support ```php diff --git a/doc/Support/Discovery Support.md b/doc/Support/Discovery Support.md index d08a663aa..acba7527d 100644 --- a/doc/Support/Discovery Support.md +++ b/doc/Support/Discovery Support.md @@ -9,30 +9,30 @@ This document will explain how to use discovery.php to debug issues or manually -h even Poll even numbered devices (same as -i 2 -n 1) -h all Poll all devices -h new Poll all devices that have not had a discovery run before - + -i -n Poll as instance of Instances start at 0. 0-3 for -n 4 - - + + Debugging and testing options: -d Enable debugging output -m Specify single module to be run ``` -`-h` Use this to specify a device via either id or hostname (including wildcard using *). You can also specify odd and -even. all will run discovery against all devices whilst +`-h` Use this to specify a device via either id or hostname (including wildcard using *). You can also specify odd and +even. all will run discovery against all devices whilst new will poll only those devices that have recently been added or have been selected for rediscovery. `-i` This can be used to stagger the discovery process. -`-d` Enables debugging output (verbose output) so that you can see what is happening during a discovery run. This includes +`-d` Enables debugging output (verbose output) so that you can see what is happening during a discovery run. This includes things like rrd updates, SQL queries and response from snmp. `-m` This enables you to specify the module you want to run for discovery. #### Discovery config -These are the default discovery config items. You can globally disable a module by setting it to 0. If you just want to +These are the default discovery config items. You can globally disable 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 -> Settings -> Modules. ```php @@ -135,7 +135,7 @@ Here are some examples of running discovery from within your install directory. #### Debugging -To provide debugging output you will need to run the discovery process with the `-d` flag. You can do this either against +To provide debugging output you will need to run the discovery process with the `-d` flag. You can do this either against all modules, single or multiple modules: All Modules @@ -153,7 +153,7 @@ Multiple Modules ./discovery.php -h localhost -m ports,entity-physical -d ``` -It is then advisable to sanitise the output before pasting it somewhere as the debug output will contain snmp details +It is then advisable to sanitise the output before pasting it somewhere as the debug output will contain snmp details amongst other items including port descriptions. The output will contain: @@ -181,5 +181,5 @@ Usage: ./snmp-scan.php -r [-d] [-l] [-h] Example: 192.168.0.0/24 -d Enable Debug -l Show Legend - -h Print this text + -h Print this text ``` diff --git a/doc/Support/FAQ.md b/doc/Support/FAQ.md index d6da5de50..8f9147e88 100644 --- a/doc/Support/FAQ.md +++ b/doc/Support/FAQ.md @@ -71,8 +71,8 @@ If the page you are trying to load has a substantial amount of data in it then i #### Why do I not see any graphs? -This is usually due to there being blank spaces outside of the `` php tags within config.php. Remove these and retry. -It's also worth removing the final `?>` at the end of config.php as this is not required. +This is usually due to there being blank spaces outside of the `` php tags within config.php. Remove these and retry. +It's also worth removing the final `?>` at the end of config.php as this is not required. #### How do I debug pages not loading correctly? @@ -92,12 +92,12 @@ Please see the [Poller Support](http://docs.librenms.org/Support/Poller Support) #### Why do I get a lot apache or rrdtool zombies in my process list? -If this is related to your web service for LibreNMS then this has been tracked down to an issue within php which the developers aren't fixing. We have implemented a work around which means you +If this is related to your web service for LibreNMS then this has been tracked down to an issue within php which the developers aren't fixing. We have implemented a work around which means you shouldn't be seeing this. If you are, please report this in [issue 443](https://github.com/librenms/librenms/issues/443). #### Why do I see traffic spikes in my graphs? -This occurs either when a counter resets or the device sends back bogus data making it look like a counter reset. We have enabled support for setting a maximum value for rrd files for ports. +This occurs either when a counter resets or the device sends back bogus data making it look like a counter reset. We have enabled support for setting a maximum value for rrd files for ports. Before this all rrd files were set to 100G max values, now you can enable support to limit this to the actual port speed. rrdtool tune will change the max value when the interface speed is detected as being changed (min value will be set for anything 10M or over) or when you run the included script (scripts/tune_port.php). @@ -136,7 +136,7 @@ Thanks for asking, sometimes it's not quite so obvious and everyone can contribu #### How can I test another users branch? -LibreNMS can and is developed by anyone, this means someone may be working on a new feature or support for a device that you want. +LibreNMS can and is developed by anyone, this means someone may be working on a new feature or support for a device that you want. It can be helpful for others to test these new features, using Git, this is made easy. ```bash @@ -151,7 +151,7 @@ git status If you see `nothing to commit, working directory clean` then let's go for it :) Let's say that you want to test a users (f0o) new development branch (issue-1337) then you can do the following: - + ```bash git remote add f0o https://github.com/librenms/librenms.git git remote update f0o diff --git a/doc/Support/Features.md b/doc/Support/Features.md index 2d994c4bc..a8fc360ce 100644 --- a/doc/Support/Features.md +++ b/doc/Support/Features.md @@ -16,7 +16,7 @@ If you think something is missing, feel free to ask us. * Traffic Billing (Quota, 95th Percentile) * Two Factor Authentication -### Vendors +### Vendors Here's a brief list of supported vendors, some might be missing. If you are unsure of whether your device is supported or not, feel free to ask us. diff --git a/doc/Support/Install Validation.md b/doc/Support/Install Validation.md index 6283a9972..ba90879de 100644 --- a/doc/Support/Install Validation.md +++ b/doc/Support/Install Validation.md @@ -1,10 +1,10 @@ Install validation ------------------ -With a lot of configuration possibilities and at present the only way to do this being by manually editing config.php then it's not +With a lot of configuration possibilities and at present the only way to do this being by manually editing config.php then it's not uncommon that mistakes get made. It's also impossible to validate user input in config.php when you're just using a text editor :) -So, to try and help with some of the general issues people come across we've put together a simple validation tool which at present will: +So, to try and help with some of the general issues people come across we've put together a simple validation tool which at present will: - Validate config.php from a php perspective including whitespace where it shouldn't be. - Connection to your MySQL server to verify credentials. diff --git a/doc/Support/Poller Support.md b/doc/Support/Poller Support.md index ad99c4219..1ac444c7c 100644 --- a/doc/Support/Poller Support.md +++ b/doc/Support/Poller Support.md @@ -20,21 +20,21 @@ Debugging and testing options: -m Specify module(s) to be run ``` -`-h` Use this to specify a device via either id or hostname (including wildcard using *). You can also specify odd and +`-h` Use this to specify a device via either id or hostname (including wildcard using *). You can also specify odd and even. all will run poller against all devices. `-i` This can be used to stagger the poller process. `-r` This option will suppress the creation or update of RRD files. -`-d` Enables debugging output (verbose output) so that you can see what is happening during a poller run. This includes +`-d` Enables debugging output (verbose output) so that you can see what is happening during a poller run. This includes things like rrd updates, SQL queries and response from snmp. `-m` This enables you to specify the module you want to run for poller. #### Poller config -These are the default poller config items. You can globally disable a module by setting it to 0. If you just want to +These are the default poller config items. You can globally disable 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 -> Settings -> Modules. ```php @@ -131,7 +131,7 @@ $config['poller_modules']['mib'] = 0; `netscaler-vsvr`: Netscaler support. `aruba-controller`: Arube wireless controller support. - + `entity-physical`: Module to pick up the devices hardware support. `applications`: Device application support. @@ -151,7 +151,7 @@ Here are some examples of running poller from within your install directory. #### Debugging -To provide debugging output you will need to run the poller process with the `-d` flag. You can do this either against +To provide debugging output you will need to run the poller process with the `-d` flag. You can do this either against all modules, single or multiple modules: All Modules @@ -169,7 +169,7 @@ Multiple Modules ./poller.php -h localhost -m ports,entity-physical -d ``` -It is then advisable to sanitise the output before pasting it somewhere as the debug output will contain snmp details +It is then advisable to sanitise the output before pasting it somewhere as the debug output will contain snmp details amongst other items including port descriptions. The output will contain: diff --git a/doc/Support/Support-New-OS.md b/doc/Support/Support-New-OS.md index e63244a26..be2bec7c9 100644 --- a/doc/Support/Support-New-OS.md +++ b/doc/Support/Support-New-OS.md @@ -69,7 +69,7 @@ $hardware = "Juniper " . trim(snmp_get($device, "productName.0", "-OQv", "PULSES $hostname = trim(snmp_get($device, "sysName.0", "-OQv", "SNMPv2-MIB"),'"'); ``` -Quick explanation and examples : +Quick explanation and examples : ```bash snmpwalk -v2c -c public -m SNMPv2-MIB -M mibs