Rebasing

2026-07-12 16:06:25 +02:00 · 2015-09-21 10:17:48 +00:00
parent 4d9163c9ec e11d596c6e
commit f655ea8416
126 changed files with 9220 additions and 574 deletions
@@ -17,6 +17,7 @@ Table of Content:
    - [PagerDuty](#transports-pagerduty)
    - [Pushover](#transports-pushover)
    - [Boxcar](#transports-boxcar)
+    - [Pushbullet](#transports-pushbullet)
 - [Entities](#entities)
    - [Devices](#entity-devices)
    - [BGP Peers](#entity-bgppeers)
@@ -360,6 +361,17 @@ $config['alert']['transports']['boxcar'][] = array(
 ```
 ~~

+## <a name="transports-pushbullet">Pushbullet</a>
+
+Enabling Pushbullet is a piece of cake.
+Get your Access Token from your Pushbullet's settings page and set it in your config like:
+
+~~
+```php
+$config['alert']['transports']['pushbullet'] = 'MYFANCYACCESSTOKEN';
+```
+~~
+
 # <a name="entities">Entities

 Entities as described earlier are based on the table and column names within the database, if you are ensure of what the entity is you want then have a browse around inside MySQL using `show tables` and `desc <tablename>`.
@@ -0,0 +1,30 @@
+# Device Groups
+
+LibreNMS supports grouping your devices together in much the same way as you can configure alerts. This document will hopefully help you get started.
+
+### 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 
+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 <tablename>`.
+
+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.
+
+#### Wildcards
+
+As used in the example above, wildcards are represented by the @ symbol. I.e @.example.com would match any hostnames under example.com.
+
+A list of common entities is maintained in our [Alerting docs](http://docs.librenms.org/Extensions/Alerting/#entities).
+
+### Conditions
+
+Please see our [Alerting docs](http://docs.librenms.org/Extensions/Alerting/#syntax) for explanations.
+
+### 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 
+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 
+Overview -> Alerts -> Rule Mapping.
@@ -2,7 +2,10 @@

 #### Please see [The new alerting docs](http://docs.librenms.org/Extensions/Alerting/#transports-email)

-Currently, the email alerts needs to be set up in the config. If you want to enable it, paste this in your config and change it:
+> None of these configuration options will work on builds older than the 1st of August 2015.
+
+
+~~Currently, the email alerts needs to be set up in the config. If you want to enable it, paste this in your config and change it:~~

 ```php
 // Mailer backend Settings
@@ -0,0 +1,40 @@
+# Oxidized integration
+
+You can integrate LibreNMS with [Oxidized](https://github.com/ytti/oxidized-web) in two ways:
+
+### 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. 
+When you have that, you only need the following config to enable the display of device configs within the device page itself:
+
+```php
+$config['oxidized']['enabled']         = TRUE;
+$config['oxidized']['url']             = 'http://127.0.0.1:8888';
+```
+
+We also support config versioning within Oxidized, this will allow you to see the old configs stored.
+
+```php
+$config['oxidized']['features']['versioning'] = true;
+```
+
+### Feeding Oxidized
+
+Oxidized has support for feeding devices into it via an API call, support for Oxidized has been added to the LibreNMS API. A sample config for Oxidized is provided below.
+
+You will need to configure default credentials for your devices, LibreNMS doesn't provide login credentials at this time.
+
+```bash
+      source:
+        default: http
+        debug: false
+        http:
+          url: https://librenms/api/v0/oxidized
+          scheme: https
+          delimiter: !ruby/regexp /:/
+          map:
+            name: hostname
+            model: os
+          headers:
+            X-Auth-Token: '01582bf94c03104ecb7953dsadsadwed'
+```
@@ -0,0 +1,32 @@
+# Poller Service
+
+# WARNING: THIS IS HIGHLY EXPERIMENTAL AND MAY NOT WORK
+
+The Poller service is an alternative to polling and discovery cron jobs and provides support for distributed polling without memcache. It is multi-threaded and runs continuously discovering and polling devices with the oldest data attempting to honor the polling frequency configured in `config.php`. This service replaces all the required cron jobs except for `/opt/librenms/daily.sh` and `/opt/librenms/alerts.php`.
+
+Configure the maximum number of threads for the service in `$config['poller_service_workers']`. Configure the minimum desired polling frequency in `$config['poller_service_poll_frequency']` and the minimum desired discovery frequency in `$config['poller_service_discover_frequency']`. The service will not poll or discover devices which have data newer than this this configured age in seconds. Configure how frequently the service will attempt to poll devices which are down in `$config['poller_service_down_retry']`.
+
+The poller service is designed to gracefully degrade. If not all devices can be polled within the configured frequency, the service will continuously poll devices refreshing as frequently as possible using the configured number of threads.
+
+The service logs to syslog. A loglevel of INFO will print status updates every 5 minutes. Loglevel of DEBUG will print updates on every device as it is scanned.
+
+## Configuration
+```php
+// Poller-Service settings
+$config['poller_service_loglevel']                       = "INFO";
+$config['poller_service_workers']                        = 16;
+$config['poller_service_poll_frequency']                 = 300;
+$config['poller_service_discover_frequency']             = 21600;
+$config['poller_service_down_retry']                     = 60;
+```
+
+## Distributed Polling
+Distributed polling is possible, and uses the same configuration options as are described for traditional distributed polling, except that the memcached options are not necessary. The database must be acessable from the distributed pollers, and properly configured. Remote access to the RRD directory must also be configured as described in the Distributed Poller documentation. Memcache is not required. Concurrency is managed using mysql GET_LOCK to ensure that devices are only being polled by one device at at time. The poller service is compatible with poller groups.
+
+## Multi-Master MySQL considerations
+Because locks are not replicated in Multi-Master MySQL configurations, if you are using such a configuration, you will need to make sure that all pollers are using the same MySQL server.
+
+## Service Installation
+An upstart configuration `poller-service.conf` is provided. To install run `ln -s /opt/librenms/poller-service.conf /etc/init/poller-service.conf`. The service will start on boot and can be started manually by running `start poller-service`. If you recieve an error that the service does not exist, run `initctl reload-configuration`. The service is configured to run as the user `librenms` and will fail if that user does not exist.
+
+An LSB init script `poller-service.init` is also provided. To install run `ln -s /opt/librenms/poller-service.init /etc/init.d/poller-service && update-rc.d poller-service defaults`.
@@ -0,0 +1,23 @@
+# Proxmox graphing
+
+It is possible to create graphs of the Proxmox VMs that run on your monitored machines. Currently, only trafficgraphs are created. One for each interface on each VM. Possibly, IO grahps will be added later on.
+
+The ultimate goal is to be able to create traffic bills for VMs, no matter on which physical machine that VM runs.
+
+### Enabling Proxmox graphs
+
+To enable Proxmox graphs, do the following:
+
+In config.php, enable Proxmox:
+```php
+$config['enable_proxmox'] = 1
+```
+
+Then, install librenms-agent on the machines running Proxmox, and enable the Proxmox-plugin using:
+```bash
+mk_enplug proxmox
+```
+
+Then, enable the unix-agent on the machines running Proxmox.
+
+You should now see an application in LibreNMS, as well as a new menu-item in the topmenu, allowing you to choose which cluster you want to look at.
@@ -2,23 +2,30 @@

 This document will explain how to setup RRDCached for LibreNMS.

-### RRDCached installation
-This example is based on a fresh LibreNMS install, on a minimimal CentOS installation.
-In this example, we'll use the Repoforge repository.
+> 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
+$config['rrdtool_version'] = 1.5;
+```
+
+### RRDCached installation CentOS 6
+This example is based on a fresh LibreNMS install, on a minimimal CentOS 6 installation.
+In this example, we'll use the Repoforge repository.
+
+```ssh
 rpm -ivh http://pkgs.repoforge.org/rpmforge-release/rpmforge-release-0.5.3-1.el6.rf.x86_64.rpm
 vi /etc/yum.repos.d/rpmforge.repo
 ```
 - Enable the Extra repo

-```php
+```ssh
 yum update rrdtool
 vi /etc/yum.repos.d/rpmforge.repo 
 ```
 - Disable the [rpmforge] and [rpmforge-extras] repos again

-```php
+```ssh
 vi /etc/sysconfig/rrdcached

 # Settings for rrdcached
@@ -33,14 +40,73 @@ chkconfig rrdcached on
 service rrdcached start
 ```

-Edit config.php to include:
+- Edit /opt/librenms/config.php to include:
 ```php
 $config['rrdcached']    = "unix:/var/run/rrdcached/rrdcached.sock";
 ```
+### RRDCached installation CentOS 7
+This example is based on a fresh LibreNMS install, on a minimimal CentOS 7.x installation.
+We'll use the epel-release and setup a RRDCached as a service.
+It is recommended that you monitor your LibreNMS server with LibreNMS so you can view the disk I/O usage delta.
+See [Installation (RHEL CentOS)][1] for localhost monitoring.

-> 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
-$config['rrdtool_version'] = 1.5;
+- Install the EPEL and update the repos and RRDtool.
+```ssh
+yum install epel-release
+yum update
+yum update rrdtool
 ```
+
+- Create the needed directories, set ownership and permissions.
+```ssh
+mkdir /var/run/rrdcached
+chown librenms:librenms /var/run/rrdcached
+chmod 755 /var/run/rrdcached
+```
+
+- Create an rrdcache service for easy daemon management.
+```ssh
+touch /etc/systemd/system/rrdcache.service
+```
+- Edit rrdcache.service and paste the example config:
+```ssh
+[Unit]
+Description=RRDtool Cache
+After=network.service
+
+[Service]
+Type=forking
+PIDFile=/run/rrdcached.pid
+ExecStart=/usr/bin/rrdcached -w 1800 -z 1800 -f 3600 -s librenms -j /var/tmp -l unix:/var/run/rrdcached/rrdcached.sock -t 4 -F -b /opt/librenms/rrd/
+RRDC_USER=librenms
+
+[Install]
+WantedBy=default.target
+```
+
+- Restart the systemctl daemon so it can recognize the newly created rrdcache.service. Enable the rrdcache.service on boot, and start the service.
+```ssh
+systemctl daemon-reload
+systemctl enable rrdcache.service
+systemctl start rrdcache.service
+```
+
+- Edit /opt/librenms/config.php to include:
+```ssh
+$config['rrdcached']    = "unix:/var/run/rrdcached/rrdcached.sock";
+```
+
+- Restart Apache
+```ssh
+systemctl restart httpd
+```
+
+Check to see if the graphs are being drawn in LibreNMS. This might take a few minutes.
+After at least one poll cycle (5 mins), check the LibreNMS disk I/O performance delta.
+Disk I/O can be found under the menu Devices>All Devices>[localhost hostname]>Health>Disk I/O.
+
+Depending on many factors, you should see the Ops/sec drop by ~30-40%.
+
+
+[1]: http://librenms.readthedocs.org/Installation/Installation-(RHEL-CentOS)/#add-localhost
+"Add localhost to LibreNMS"
@@ -0,0 +1,53 @@
+# Setting up Varnish 
+
+This document will explain how to setup Varnish for LibreNMS.
+
+### Varnish installation
+This example is based on a fresh LibreNMS install, on a minimimal CentOS installation.
+In this example, we'll use the default package available through yum.
+
+- Install Varnish
+
+```ssh
+yum install varnish
+chkconfig varnish on
+```
+- Confirm that Varnish has been installed 
+
+```ssh
+varnishd -V
+varnishd (varnish-2.1.5 SVN )
+```
+- Change the webservers port to 8080, since we'll put Varnish in front(Or whatever you prefer) 
+
+- Point Varnish towards the webserver by editing the default.vcl 
+
+```ssh
+vi /etc/varnish/default.vcl
+
+backend default {
+  .host = "127.0.0.1";
+  .port = "8080";
+}
+
+```
+- Change the default port Varnish listens on
+
+```ssh
+vi /etc/sysconfig/varnish
+
+VARNISH_LISTEN_PORT=80
+```
+
+- Restart webserver(Apache in this case) and start Varnish afterwards
+
+```ssh
+service httpd restart
+service varnish start
+```
+
+- Browse around the webui to build up the cache, verify that the cache is working afterwards
+
+```ssh
+varnishstat
+```
@@ -1,3 +1,48 @@
+### September 2015
+
+#### Bug fixes
+  - Alerting:
+    - Process followups if there are changes (PR1817)
+    - Typo in alert_window setting (PR1841)
+    - Issue alert-trigger as test object (PR1850)
+  - WebUI:
+    - Fix permissions for World-map widget (PR1866)
+    - Clean up Gloabl / World Map name mixup (PR1874)
+  - Services:
+    - Honour IP field for DNS checks (PR1933)
+  - Discovery / Poller:
+    - Fix Huawei VRP os detection (PR1931)t
+  - General:
+    - Remove 'sh' from cronjob (PR1818)
+    - Remove MySQL Locks (PR1822,PR1826,PR1829,PR1836)
+
+#### Improvements
+  - WebUI:
+    - Ability to edit ifAlias (PR1811)
+    - Honour Mouseout/Mouseleave on map widget (PR1814)
+    - Make syslog/eventlog responsive (PR1816)
+    - Reformat Proxmox UI (PR1825,PR1827)
+    - Misc Changes (PR1828,PR1830,PR1875,PR1885,PR1886,PR1887,PR1891,PR1896,PR1901,PR1913)
+    - Added support for Oxidized versioning (PR1842)
+    - Added graph widget + settings for widgets (PR1835,PR1861)
+    - Added Support for multiple dashboards (PR1869)
+    - Added settings page for Worldmap widget (PR1872)
+    - Added uptime to availability widget (PR1881)
+    - Added top devices and ports widgets (PR1903)
+    - Added support for saving notes for devices (PR1927)
+  - Added detection for:
+    - FortiOS (PR1815)
+  - Discovery / Poller:
+    - Added Proxmox support (PR1789)
+  - Documentation:
+    - Add varnish docs (PR1809)
+    - Added CentOS 7 RRCached docs (1893)
+  - General:
+    - Make installer more responsive (PR1832)
+    - Update fping millisec option to 200 default (PR1833)
+    - Reduced cleanup of device_perf (PR1837)
+    - Added support for negative values in munin-plugins (PR1907)
+
 ### August 2015

 #### Bug fixes
@@ -8,6 +53,9 @@
    - Fixed Web installer due to code tidying update (PR1644)
    - Updated gridster variable names to make unique (PR1646)
    - Fixed issues with displaying devices with ' in location (PR1655)
+    - Fixes updating snmpv3 details in webui (PR1727)
+    - Check for user perms before listing neighbour ports (PR1749)
+    - Fixed Test-Transport button (PR1772)
  - DB:
    - Added proper indexes on device_perf table (PR1621)
    - Fixed multiple mysql strict issues (PR1638, PR1659)
@@ -17,8 +65,18 @@
    - Fixed discovery-arp not running since code formatting update (PR1671)
    - Correct the DSM upgrade OID (PR1696)
    - Fix MySQL agent host variable usage (PR1710)
+    - Pass snmp-auth parameters enclosed by single-quotes (PR1730)
+    - Revert change which skips over down ports (PR1742)
+    - Stop PoE polling for each port (PR1747)
+    - Use ifHighSpeed if ifSpeed equals 0 (PR1750)
+    - Keep PHP Backwards compatibility (PR1766)
+    - False identification of Zyxel as Cisco (PR1776)
+    - Fix MySQL statement in poller-service.py (PR1794)
+    - Fix upstart script for poller-service.py (PR1812)
  - General:
    - Fixed path to defaults.inc.php in config.php.default (PR1673)
+    - Strip '::ffff:' from syslog input (PR1734)
+    - Fix RRA (PR1791)

 #### Improvements
  - WebUI Updates:
@@ -32,29 +90,50 @@
    - Added support for running under sub-directory (PR1667)
    - Updated vis.js to latest version (PR1708)
    - Added border on availability map (PR1713)
+    - Make new dashboard the default (PR1719)
+    - Rearrange about page (PR1735,PR1743)
+    - Center/Cleanup graphs (PR1736)
+    - Added Hover-Effect on devices table (PR1738)
+    - Show Test-Transport result (PR1777)
+    - Add arrows to the network map (PR1787)
+    - Add errored ports to summary widget (PR1788)
+    - Show message if no Device-Groups exist (PR1796)
+    - Misc UI fixes (Titles, Headers, ...) (PR1797,PR1798,PR1800,PR1801,PR1802,PR1803,PR1804,PR1805)
+    - Move packages to overview dropdown (PR1810)
  - API Updates:
    - Improvided billing support in API (PR1599)
+    - Extended support for list devices to support mac/ipv4 and ipv6 filtering (PR1744)
  - Added detection for:
    - Perle Media convertors (PR1607)
+    - Mac OSX 10 (PR1774)
  - Improved detection for:
    - Windows devices (PR1639)
-    - Zywall CPU, Version and Memory (PR1660)
+    - Zywall CPU, Version and Memory (PR1660,PR1784)
    - Added LLDP support for PBN devices (PR1705)
+    - Netgear GS110TP (PR1751)
  - Additional Sensors:
    - Added Compressor state for PCOWEB (PR1600)
    - Added dbm support for IOS-XR (PR1661)
+    - Added temperature support for DNOS (PR1782)
  - Discovery / Poller:
    - Updated autodiscovery function to log new type (PR1623)
+    - Improve application polling (PR1724)
+    - Improve debug output (PR1756)
  - DB:
    - Added MySQLi support (PR1647)
  - Documentation:
    - Added docs on MySQL strict mode (PR1635)
    - Updated billing docs to use librenms user in cron (PR1676)
    - Updated LDAP docs to indicate php-ldap module needs installing (PR1716)
+    - Typo/Spellchecks (PR1731,PR1806)
+    - Improved Alerting and Device-Groups (PR1781)
  - Alerting:
    - Reformatted eventlog message to show state for alerts (PR1685)
+    - Add basic Pushbullet transport (PR1721)
+    - Allow custom titles (PR1807)
  - General:
    - Added more debugging and checks to discovery-protocols (PR1590)
+    - Cleanup debug statements (PR1725,PR1737)

 ### July 2015

@@ -170,7 +170,7 @@ project.
 Proposed workflow for submitting pull requests
 ----------------------------------------------

-Please see the new [Using Git](http://doc.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
@@ -27,14 +27,13 @@ service mariadb start
 Now continue with the installation:

 ```bash
-yum install net-snmp mysql-server
 service snmpd start
 chkconfig snmpd on
 mysql_secure_installation
 mysql -uroot -p
 ```

-Enter the MySQL root password to enter the MySQL command-line interface.
+Enter the MySQL/MariaDB root password to enter the command-line interface.

 Create database.

@@ -50,7 +50,7 @@ $config['fping6']           = "/usr/bin/fping6";
 $config['fping_options']['retries'] = 3;
 $config['fping_options']['timeout'] = 500;
 $config['fping_options']['count'] = 3;
-$config['fping_options']['millisec'] = 5;
+$config['fping_options']['millisec'] = 200;
 ```
 fping configuration options, this includes setting the timeout and retry options.

@@ -143,6 +143,7 @@ $config['show_locations']          = 1;  # Enable Locations on menu
 $config['show_locations_dropdown'] = 1;  # Enable Locations dropdown on menu
 $config['show_services']           = 0;  # Enable Services on menu
 $config['int_customers']           = 1;  # Enable Customer Port Parsing
+$config['summary_errors']          = 0;  # Show Errored ports in summary boxes on the dashboard
 $config['customers_descr']         = 'cust'; // The description to look for in ifDescr. Can be an array as well array('cust','cid');
 $config['transit_descr']           = ""; // Add custom transit descriptions (can be an array)
 $config['peering_descr']           = ""; // Add custom peering descriptions (can be an array)