From 91e40a91ce01597e105d85c1a5a9ae0396a64684 Mon Sep 17 00:00:00 2001 From: Neil Lathwood Date: Sat, 10 Jan 2015 00:10:51 +0000 Subject: [PATCH 1/3] Updated document structure --- doc/AUTHORS.md => AUTHORS.md | 0 doc/API/API-Docs.md | 720 ++++++++++++++++++ doc/{Agent.md => Extensions/Agent-Setup.md} | 1 - doc/{ => Extensions}/Alerting.md | 0 .../Billing-Module.md} | 2 +- doc/Extensions/Email-Alerting.md | 23 + doc/{ => Extensions}/IRC-Bot-Extensions.md | 4 +- doc/{ => Extensions}/IRC-Bot.md | 4 +- .../Interface-Description-Parsing.md | 2 +- .../Plugin-System.md} | 2 +- .../Two-Factor-Auth.md} | 1 + .../Contributing.md} | 393 +++++----- doc/{CREDITS.md => General/Credits.md} | 1 + .../Developing-for-LibreNMS.md} | 6 +- doc/General/Roadmap.md | 26 + doc/{UPDATING.md => General/Updating.md} | 2 +- doc/Home.md | 68 ++ .../Installation-(Debian-Ubuntu).md} | 2 +- .../Installation-(RHEL-CentOS).md} | 2 +- .../Installation-Lighttpd-(Debian-Ubuntu).md} | 2 +- ...ervium_Welcome.md => Observium-Welcome.md} | 1 + doc/ROADMAP.md | 27 - doc/_Sidebar.md | 25 + 23 files changed, 1074 insertions(+), 240 deletions(-) rename doc/AUTHORS.md => AUTHORS.md (100%) create mode 100644 doc/API/API-Docs.md rename doc/{Agent.md => Extensions/Agent-Setup.md} (99%) rename doc/{ => Extensions}/Alerting.md (100%) rename doc/{Billing_Module.md => Extensions/Billing-Module.md} (92%) create mode 100644 doc/Extensions/Email-Alerting.md rename doc/{ => Extensions}/IRC-Bot-Extensions.md (99%) rename doc/{ => Extensions}/IRC-Bot.md (97%) rename doc/{ => Extensions}/Interface-Description-Parsing.md (99%) rename doc/{Plugin_System.md => Extensions/Plugin-System.md} (97%) rename doc/{TwoFactor.md => Extensions/Two-Factor-Auth.md} (99%) rename doc/{CONTRIBUTING.md => General/Contributing.md} (97%) rename doc/{CREDITS.md => General/Credits.md} (99%) rename doc/{DEVEL.md => General/Developing-for-LibreNMS.md} (92%) create mode 100644 doc/General/Roadmap.md rename doc/{UPDATING.md => General/Updating.md} (89%) create mode 100644 doc/Home.md rename doc/{INSTALL.md => Installation/Installation-(Debian-Ubuntu).md} (99%) rename doc/{INSTALL_RHEL.md => Installation/Installation-(RHEL-CentOS).md} (99%) rename doc/{INSTALL_LIGHTTPD.md => Installation/Installation-Lighttpd-(Debian-Ubuntu).md} (99%) rename doc/{Observium_Welcome.md => Observium-Welcome.md} (99%) delete mode 100644 doc/ROADMAP.md create mode 100644 doc/_Sidebar.md diff --git a/doc/AUTHORS.md b/AUTHORS.md similarity index 100% rename from doc/AUTHORS.md rename to AUTHORS.md diff --git a/doc/API/API-Docs.md b/doc/API/API-Docs.md new file mode 100644 index 0000000000..db09bb93cc --- /dev/null +++ b/doc/API/API-Docs.md @@ -0,0 +1,720 @@ + +- [`structure`](#api-structure) + - [`versioning`](#api-versioning) + - [`token`](#api-tokens) + - [`end-points`](#api-end_points) + - [`input`](#api-input) + - [`output`](#api-output) +- [`endpoints`](#api-endpoints) + - [`devices`](#api-devices) + - [`del_device`](#api-route-2) + - [`get_device`](#api-route-3) + - [`get_graphs`](#api-route-5) + - [`get_graph_generic_by_hostname`](#api-route-6) + - [`get_port_graphs`](#api-route-7) + - [`get_port_stats_by_port_hostname`](#api-route-8) + - [`get_graph_by_port_hostname`](#api-route-9) + - [`list_devices`](#api-route-10) + - [`add_device`](#api-route-11) + - [`routing`](#api-routing) + - [`list_bgp`](#api-route-1) + - [`switching`](#api-switching) + - [`get_vlans`](#api-route-4) + - [`alerts`](#api-alerts) + - [`get_alert`](#api-route-12) + - [`ack_alert`](#api-route-13) + - [`list_alerts`](#api-route-14) + - [`rules`](#api-rules) + - [`get_alert_rule`](#api-route-15) + - [`delete_rule`](#api-route-16) + - [`list_alert_rules`](#api-route-17) + - [`add_rule`](#api-route-18) + - [`edit_rule`](#api-route-19) + +Describes the API structure. + +# `Structure` [`top`](#top) + +## `Versioning` [`top`](#top) + +Versioning an API is a minefield which saw us looking at numerous options on how to do this. Paul wrote an excellent blog post which touches on this: http://blog.librenms.org/2014/09/restful-apis/ + +We have currently settled on using versioning within the API end point itself `/api/v0`. As the API itself is new and still in active development we also decided that v0 would be the best starting point to indicate it's in development. + +## `Tokens` [`top`](#top) + +To access any of the token end points you will be required to authenticate using a token. Tokens can be created directly from within the LibreNMS web interface by going to `/api-access/`. + +- Click on 'Create API access token'. +- Select the user you would like to generate the token for. +- Enter an optional description. +- Click Create API Token. + +## `Endpoints` [`top`](#top) + +Whilst this documentation will describe and show examples of the end points, we've designed the API so you should be able to traverse through it without know any of the available API routes. + +You can do this by first calling `/api/v0`: + +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0 + +Output +{ + "list_bgp": "https://librenms.org/api/v0/bgp", + ... + "edit_rule": "https://librenms.org/api/v0/rules" +} +``` + +## `Input` [`top`](#top) + +Input to the API is done in three different ways, sometimes a combination two or three of these. + +- Passing parameters via the api route. For example when obtaining a devices details you will pass the hostname of the device in the route: `/api/v0/devices/:hostname`. +- Passing parameters via the query string. For example you can list all devices on your install but limit the output to devices that are currently down: `/api/v0/devices?type=down` +- Passing data in via JSON, this will mainly be used when adding or updating information via the API, for instance adding a new device: +```curl +curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}'-H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices +``` + +## `Output` [`top`](#top) + +Output from the API currently is via two output types. + +- JSON Most API responses will output json. As show in the example for calling the API endpoint. +- PNG This is for when the request is for an image such as a graph for a switch port. + +# `Endpoints` [`top`](#top) + +## `Devices` [`top`](#top) + +### Function: `del_device` [`top`](#top) + +Delete a given device. + +Route: /api/v0/devices/:hostname + +- hostname can be either the device hostname or id + +Input: + + - + +Example: +```curl +curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost +``` + +Output: +```text +{ + "status": "ok", + "message": "Removed device localhost", + "devices": [ + { + "device_id": "1", + "hostname": "localhost", + ... + "serial": null, + "icon": null + } + ] +} +``` + +### Function: `get_device` [`top`](#top) + +Get details of a given device. + +Route: /api/v0/devices/:hostname + +- hostname can be either the device hostname or id + +Input: + + - + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost +``` + +Output: +```text +{ + "status": "ok", + "devices": [ + { + "device_id": "1", + "hostname": "localhost", + ... + "serial": null, + "icon": null + } + ] +} +``` + +### Function: `get_graphs` [`top`](#top) + +Get a list of available graphs for a device, this does not include ports. + +Route: /api/v0/devices/:hostname/graphs + +- hostname can be either the device hostname or id + +Input: + + - + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "count": 3, + "graphs": [ + { + "desc": "Poller Time", + "name": "device_poller_perf" + }, + { + "desc": "Ping Response", + "name": "device_ping_perf" + }, + { + "desc": "System Uptime", + "name": "uptime" + } + ] +} +``` + +### Function: `get_graph_generic_by_hostname` [`top`](#top) + +Get a specific graph for a device, this does not include ports. + +Route: /api/v0/devices/:hostname/:type + +- hostname can be either the device hostname or id +- type is the type of graph you want, use [`get_graphs`](#api-route-5) to see the graphs available. Defaults to device_uptime. + +Input: + + - from: This is the date you would like the graph to start - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information. + - to: This is the date you would like the graph to end - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information. + - width: The graph width, defaults to 1075. + - height: The graph height, defaults to 300. + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/device_poller_perf +``` + +Output: + +Output is an image. + +### Function: `get_port_graphs` [`top`](#top) + +Get a list of ports for a particular device. + +Route: /api/v0/devices/:hostname/ports + +- hostname can be either the device hostname or id + +Input: + + - columns: Comma separated list of columns you want returned. + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports +``` + +Output: + +```text +{ + "status": "ok", + "err-msg": "", + "count": 3, + "ports": [ + { + "ifName": "lo" + }, + { + "ifName": "eth0" + }, + { + "ifName": "eth1" + } + ] +} +``` + +### Function: `get_port_stats_by_port_hostname` [`top`](#top) + +Get information about a particular port for a device. + +Route: /api/v0/devices/:hostname/ports/:ifname + +- hostname can be either the device hostname or id +- ifname can be any of the interface names for the device which can be obtained using [`get_port_graphs`](#api-route-7). Please ensure that the ifname is urlencoded if it needs to be (i.e Gi0/1/0 would need to be urlencoded. + +Input: + + - columns: Comma separated list of columns you want returned. + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports/eth0 +``` + +Output: + +```text +{ + "status": "ok", + "port": { + "port_id": "2", + "device_id": "1", + ... + "poll_prev": "1418412902", + "poll_period": "300" + } +} +``` + +### Function: `get_graph_by_port_hostname` [`top`](#top) + +Get a graph of a port for a particular device. + +Route: /api/v0/devices/:hostname/ports/:ifname/:type + +- hostname can be either the device hostname or id +- ifname can be any of the interface names for the device which can be obtained using [`get_port_graphs`](#api-route-7). Please ensure that the ifname is urlencoded if it needs to be (i.e Gi0/1/0 would need to be urlencoded. +- type is the port type you want the graph for, you can request a list of ports for a device with [`get_port_graphs`](#api-route-7). + +Input: + + - from: This is the date you would like the graph to start - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information. + - to: This is the date you would like the graph to end - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information. + - width: The graph width, defaults to 1075. + - height: The graph height, defaults to 300. + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports/eth0/port_bits +``` + +Output: + +Output is an image. + +### Function: `list_devices` [`top`](#top) + +Return a list of devices. + +Route: /api/v0/devices + +Input: + + - order: How to order the output, default is by hostname. Can be prepended by DESC or ASC to change the order. + - type: can be one of the following, all, ignored, up, down, disabled to filter by that device status. + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices?order=hostname%20DESC&type=down +``` + +Output: + +```text +{ + "status": "ok", + "devices": [ + { + "device_id": "1", + "hostname": "localhost", + ... + "serial": null, + "icon": null + } + ] +} +``` + +### Function: `add_device` [`top`](#top) + +Add a new device. + +Route: /api/v0/devices + +Input (JSON): + + - hostname: device hostname + - port: SNMP port (defaults to port defined in config). + - transport: SNMP protocol (defaults to transport defined in config). + - version: SNMP version to use, v1, v2c or v3. Defaults to v2c. + + For SNMP v1 or v2c + + - community: Required for SNMP v1 or v2c. + + For SNMP v3 + + - authlevel: SNMP authlevel (NoAuthNoPriv, AuthNoPriv, AuthPriv). + - authname: SNMP Auth username + - authpass: SNMP Auth password + - authalgo: SNMP Auth algorithm (MD5, SHA) + - cryptopass: SNMP Crypto Password + - cryptoalgo: SNMP Crypto algorithm (AES, DES) + +Example: +```curl +curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices +``` + +Output: + +```text +{ + "status": "ok", + "message": "Device localhost.localdomain has been added successfully" +} +``` + +## `Routing` [`top`](#top) + +### Function: `list_bgp` [`top`](#top) + +List the current BGP sessions. + +Route: /api/v0/bgp + +Input: + + - hostname = either the devices hostname or id. + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bgp +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "count": 0, + "bgp_sessions": [ + + ] +} +``` + +## `Switching` [`top`](#top) + +### Function: `get_vlans` [`top`](#top) + +Get a list of all VLANs for a given device. + +Route: /api/v0/devices/:hostname/vlans + +- hostname can be either the device hostname or id + +Input: + + - + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/vlans +``` + +Output: +```text +{ + "status": "ok", + "count": 0, + "vlans": [ + { + "vlan_vlan": "1", + "vlan_domain": "1", + "vlan_name": "default", + "vlan_type": "ethernet", + "vlan_mtu": null + } + ] +} +``` + +## `Alerts` [`top`](#top) + +### Function: `get_alert` [`top`](#top) + +Get details of an alert + +Route: /api/v0/alerts/:id + +- id is the alert id, you can obtain a list of alert ids from [`list_alerts`](#api-route-14). + +Input: + + - + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/alerts/1 +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "count": 7, + "alerts": [ + { + "id": "1", + "device_id": "1", + "rule_id": "1", + "state": "1", + "alerted": "1", + "open": "1", + "timestamp": "2014-12-11 14:40:02" + }, +} +``` + +### Function: `ack_alert` [`top`](#top) + +Acknowledge an alert + +Route: /api/v0/alerts/:id + +- id is the alert id, you can obtain a list of alert ids from [`list_alerts`](#api-route-14). + +Input: + + - + +Example: +```curl +curl -X PUT -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/alerts/1 +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "message": "Alert has been ackgnowledged" +} +``` + +### Function: `list_alerts` [`top`](#top) + +List all alerts + +Route: /api/v0/alerts + +Input: + + - state: Filter the alerts by state, 0 = ok, 1 = alert, 2 = ack + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/alerts +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "count": 1, + "alerts": [ + { + "id": "1", + "device_id": "1", + "rule_id": "1", + "state": "1", + "alerted": "1", + "open": "1", + "timestamp": "2014-12-11 14:40:02" + } +} +``` + +## `Rules` [`top`](#top) + +### Function: `get_alert_rule` [`top`](#top) + +Get the alert rule details. + +Route: /api/v0/rules/:id + + - id is the rule id. + +Input: + + - + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules/1 +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "count": 1, + "rules": [ + { + "id": "1", + "device_id": "1", + "rule": "%devices.os != \"Juniper\"", + "severity": "warning", + "extra": "{\"mute\":true,\"count\":\"15\",\"delay\":null}", + "disabled": "0" + } + ] +} +``` + +### Function: `delete_rule` [`top`](#top) + +Delete an alert rule by id + +Route: /api/v0/rules/:id + + - id is the rule id. + +Input: + + - + +Example: +```curl +curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules/1 +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "message": "Alert rule has been removed" +} +``` + +### Function: `list_alert_rules` [`top`](#top) + +List the alert rules. + +Route: /api/v0/rules + + - + +Input: + + - + +Example: +```curl +curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules +``` + +Output: +```text +{ + "status": "ok", + "err-msg": "", + "count": 1, + "rules": [ + { + "id": "1", + "device_id": "-1", + "rule": "%devices.os != \"Juniper\"", + "severity": "critical", + "extra": "{\"mute\":false,\"count\":\"15\",\"delay\":\"300\"}", + "disabled": "0" + }, +} +``` + +### Function: `add_rule` [`top`](#top) + +Add a new alert rule. + +Route: /api/v0/rules + + - + +Input (JSON): + + - device_id: This is either the device id or -1 for a global rule + - rule: The rule which should be in the format %entity $condition $value (i.e %devices.status != 0 for devices marked as down). + - 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. + - mute: If mute is enabled then an alert will never be sent but will show up in the Web UI (true or false). + + +Example: +```curl +curl -X POST -d '{"device_id":"-1", "rule":"%devices.os != \"Cisco\"","severity": "critical","count":15,"delay":"5 m","mute":false}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules +``` + +Output: +```text +rules +{ + "status": "ok", + "err-msg": "" +} +``` + +### Function: `edit_rule` [`top`](#top) + +Edit an existing alert rule + +Route: /api/v0/rules + + - + +Input (JSON): + + - rule_id: You must specify the rule_id to edit an existing rule, if this is absent then a new rule will be created. + - device_id: This is either the device id or -1 for a global rule + - rule: The rule which should be in the format %entity $condition $value (i.e %devices.status != 0 for devices marked as down). + - 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. + - mute: If mute is enabled then an alert will never be sent but will show up in the Web UI (true or false). + +Example: +```curl +curl -X PUT -d '{"rule_id":1,"device_id":"-1", "rule":"%devices.os != \"Cisco\"","severity": "critical","count":15,"delay":"5 m","mute":false}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/rules +``` + +Output: +```text +rules +{ + "status": "ok", + "err-msg": "" +} +``` diff --git a/doc/Agent.md b/doc/Extensions/Agent-Setup.md similarity index 99% rename from doc/Agent.md rename to doc/Extensions/Agent-Setup.md index 31c99de26e..296ba1790a 100644 --- a/doc/Agent.md +++ b/doc/Extensions/Agent-Setup.md @@ -34,5 +34,4 @@ mkdir -p /usr/lib/check_mk_agent/plugins /usr/lib/check_mk_agent/local * Login to the LibreNMS web interface and edit the device you want to monitor. Under the modules section, ensure that unix-agent is enabled. * Then under Applications, enable the apps that you plan to monitor. * Wait, in around 10 minutes you should start seeing data in your graphs under Apps for the device. -* diff --git a/doc/Alerting.md b/doc/Extensions/Alerting.md similarity index 100% rename from doc/Alerting.md rename to doc/Extensions/Alerting.md diff --git a/doc/Billing_Module.md b/doc/Extensions/Billing-Module.md similarity index 92% rename from doc/Billing_Module.md rename to doc/Extensions/Billing-Module.md index 4654b8f416..18908a0e38 100644 --- a/doc/Billing_Module.md +++ b/doc/Extensions/Billing-Module.md @@ -15,4 +15,4 @@ Edit `/etc/cron.d/librenms` and add the following: 01 * * * * root /opt/librenms/billing-calculate.php >> /dev/null 2>&1 ``` -Create billing graphs as required. +Create billing graphs as required. \ No newline at end of file diff --git a/doc/Extensions/Email-Alerting.md b/doc/Extensions/Email-Alerting.md new file mode 100644 index 0000000000..6908a88c50 --- /dev/null +++ b/doc/Extensions/Email-Alerting.md @@ -0,0 +1,23 @@ +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 +$config['email_backend'] = 'mail'; // Mail backend. Allowed: "mail" (PHP's built-in), "sendmail", "smtp". +$config['email_from'] = NULL; // Mail from. Default: "ProjectName" +$config['email_user'] = $config['project_id']; +$config['email_sendmail_path'] = '/usr/sbin/sendmail'; // The location of the sendmail program. +$config['email_smtp_host'] = 'localhost'; // Outgoing SMTP server name. +$config['email_smtp_port'] = 25; // The port to connect. +$config['email_smtp_timeout'] = 10; // SMTP connection timeout in seconds. +$config['email_smtp_secure'] = NULL; // Enable encryption. Use 'tls' or 'ssl' +$config['email_smtp_auth'] = FALSE; // Whether or not to use SMTP authentication. +$config['email_smtp_username'] = NULL; // SMTP username. +$config['email_smtp_password'] = NULL; // Password for SMTP authentication. + +// Alerting Settings +$config['alerts']['email']['default'] = 'sendto@somewhere.com'; // Default alert recipient +$config['alerts']['email']['default_only'] = FALSE; // Only use default recipient +$config['alerts']['email']['enable'] = TRUE; // Enable email alerts +$config['alerts']['bgp']['whitelist'] = NULL; // Populate as an array() with ASNs to alert on. +$config['alerts']['port']['ifdown'] = FALSE; // Generate alerts for ports that go down +``` \ No newline at end of file diff --git a/doc/IRC-Bot-Extensions.md b/doc/Extensions/IRC-Bot-Extensions.md similarity index 99% rename from doc/IRC-Bot-Extensions.md rename to doc/Extensions/IRC-Bot-Extensions.md index 87f7b46080..0debac3807 100644 --- a/doc/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`. @@ -77,4 +77,4 @@ Attribute | Type | Description ... $config['irc_external'][] = "join-ng"; ... -``` +``` \ No newline at end of file diff --git a/doc/IRC-Bot.md b/doc/Extensions/IRC-Bot.md similarity index 97% rename from doc/IRC-Bot.md rename to doc/Extensions/IRC-Bot.md index eb00a48a7c..fa9214affe 100644 --- a/doc/IRC-Bot.md +++ b/doc/Extensions/IRC-Bot.md @@ -30,7 +30,7 @@ Option | Default-Value | Notes `$config['irc_maxretry]` | `5` | Optional; How many connection attempts should be made before giving up `$config['irc_nick']` | `LibreNMS` | Optional; `$config['irc_pass']` | | Optional; This sends the IRC-PASS Sequence to IRC-Servers that require Password on Connect -`$config['irc_port]` | `6667` | Required; To enable SSL append a `+` before the Port. (Example: `+6697`) +`$config['irc_port']` | `6667` | Required; To enable SSL append a `+` before the Port. (Example: `+6697`) ### IRC-Commands @@ -127,4 +127,4 @@ File: includes/ircbot/echo.inc.php } else { return $this->respond("root shouldn't be online so late!"); } -``` +``` \ No newline at end of file diff --git a/doc/Interface-Description-Parsing.md b/doc/Extensions/Interface-Description-Parsing.md similarity index 99% rename from doc/Interface-Description-Parsing.md rename to doc/Extensions/Interface-Description-Parsing.md index d1844ebb8d..4033ffb19d 100644 --- a/doc/Interface-Description-Parsing.md +++ b/doc/Extensions/Interface-Description-Parsing.md @@ -52,4 +52,4 @@ See [examples](#examples) for formats. # Sourcecode: -* https://github.com/librenms/librenms/blob/master/scripts/ifAlias +* https://github.com/librenms/librenms/blob/master/scripts/ifAlias \ No newline at end of file diff --git a/doc/Plugin_System.md b/doc/Extensions/Plugin-System.md similarity index 97% rename from doc/Plugin_System.md rename to doc/Extensions/Plugin-System.md index 3d0c41ce91..544f7a1a0e 100644 --- a/doc/Plugin_System.md +++ b/doc/Extensions/Plugin-System.md @@ -58,4 +58,4 @@ This would then add the name and a link to your plugin. The following system hooks are currently available: menu() -* This is called to build the plugin menu system and you can use this to link to your plugin (you don't have to). +* This is called to build the plugin menu system and you can use this to link to your plugin (you don't have to). \ No newline at end of file diff --git a/doc/TwoFactor.md b/doc/Extensions/Two-Factor-Auth.md similarity index 99% rename from doc/TwoFactor.md rename to doc/Extensions/Two-Factor-Auth.md index ccc9dd0594..de6ee6d83c 100644 --- a/doc/TwoFactor.md +++ b/doc/Extensions/Two-Factor-Auth.md @@ -70,3 +70,4 @@ Usage: - Create a key like described above - Scan provided QR or click on 'Manual' and type down the Secret - On next login, enter the passcode that the App provides + diff --git a/doc/CONTRIBUTING.md b/doc/General/Contributing.md similarity index 97% rename from doc/CONTRIBUTING.md rename to doc/General/Contributing.md index b4de37ad26..3075467427 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/General/Contributing.md @@ -1,197 +1,196 @@ -Contributor Agreement ---------------------- - -By contributing code to LibreNMS (whether by a github pull request, or by -any other means), you assert that: - -- You have the rights to include the code, either as its original author, - or due to it being released to you under a compatible license. - -- You are not aware of any third party claims on the code, including - copyright infringement, patent, or any other claim. - -- You have not viewed code written under the [Observium License][4] in the - production of contributed code. This includes all Observium code after - Subversion revision 3250 and any patches or other code covered by that - license from Observium web sites after Tue May 29 13:08:01 2012 +0000 (the - date of Observium r3250). - -To agree with these assertions, please submit a github pull request against -the file doc/AUTHORS.md including your name, email address, and github user -id in the file (so that it can be matched to your commits), and stating in -the commit log: -``` - I agree to the conditions of the Contributor Agreement - contained in doc/CONTRIBUTING.md. -``` - - -Copyright ---------- - -All contributors to LibreNMS retain copyright to their own code and are not -required to sign over their rights to any other party. - -We recommend that if you add a new file containing original code to the code -base that you include a copyright notice in it as per the Free Software -Foundation's guidelines. You might find something like the following header -appropriate (although this is not legal advice ;-): -``` - - * - * This program is free software: you can redistribute it and/or modify it - * under the terms of the GNU General Public License as published by the - * Free Software Foundation, either version 3 of the License, or (at your - * option) any later version. Please see LICENSE.txt at the top level of - * the source code distribution for details. - */ - ?> -``` -The GPLv3 itself also contains recommendations about applying the GPL to -your code. Please see LICENSE.txt at the top of this source code -distribution for details. - - -General Guidelines ------------------- - -- Test your patches first. It's easy to set up git to push to a bare - repository on a local test system, and pull from this into a live test - installation at very frequent intervals. - -- Don't break the poller. User interface blemishes are not critical, but - losing data from network monitoring systems might be. - -- As a general rule, if you're replacing lines of code with new lines of - code, don't comment them out, just delete them. Commented out code makes - the patch and the resultant code harder to read, and there's no good - reason to it since we can easily get them back from git. - -- If you're fixing a bug or making another minor change, don't reformat the - code at the same time. This makes it harder to see what's changed. If - you need to reformat it after making the change, do so in a separate - commit. - -- Please join us in IRC at irc.freenode.net in channel ##librenms if you're - able. Collaborating in real time makes the coordination of contributions - easier. - - -Integrating other code ----------------------- - -Giving credit where credit is due is critical to the Free Software -philosophy. If you use code from somewhere else, even if it's trivial, -be sure to note this as a comment in the code (preferably) or the commit -message. - -- To incorporate larger blocks of code from third parties (e.g. JavaScript - libraries): - - Include its name, source URL, copyright notice, and license in - doc/CREDITS.md - - preferred locations are html/js, html/lib, and lib - - Add it in a separate commit into its own directory, using - 'git subtree --squash' if it is available via git. - - Add the code to integrate it in a separate commit. Include: - - code to update it in Makefile - - Scrutinizer exclusions to .scrutinizer.yml - - symlinks where necessary to maintain sensible paths - -- Don't submit code whose license conflicts with the GPLv3. If you're not - sure, consult the [Free Software Foundation's license list][1] and see if - your code's license is on the compatible or incompatible list. If you - prefer a non-copyleft license, Apache 2.0 is the recommended choice as per - the FSF guidelines. - -- The current Observium license is incompatible with GPLv3. Don't submit - code from current Observium unless you are the copyright holder, and you - specifically state in the code that you are releasing it under GPLv3 (or a - compatible license). - - Because contributing to Observium requires that you reassign copyright to - Adam Armstrong, if you want to release the same code for both Observium - and LibreNMS, you need to release it for LibreNMS first and mark it with - your own copyright notice, then release it to Observium and remove your - copyright, granting Adam ownership. - - Please note that the above is necessary even if you don't care about - keeping the copyright to your code, because otherwise we could be accused - of misappropriating Obserivum's code. As the code bases develop, we - expect them to diverge, which means this will become less of an issue - anyway. - -- Because the GPL's provisions about linking don't apply to PHP-based - projects, we interpret the linking provisions of the license to refer to - the use of PHP library functions called from LibreNMS code. - - We consider inclusion of files such as MIBs in the LibreNMS repository to - be merely aggregation in a distribution medium as per the last paragraph - of the GPLv3 section 5 ("Conveying Modified Source Versions"), and because - they are not combined with LibreNMS to form a larger program, the GPLv3 - does not apply to them. This is not a legal ruling - it is simply a - statement of our intent and current interpretation. - - -Proposed workflow for submitting pull requests ----------------------------------------------- - -The basic rule is: don't create merge conflicts in master. Merges should be -simple fast-forwards from current master. - -Following is a proposed workflow designed to minimise the scope of merge -conflicts when submitting pull requests. It's not mandatory, but seems to -work well enough. - -We don't recommend git flow because we don't want to maintain separate -development and master branches, but if it works better for you, feel free -to do that, as long as you follow the golden rule of not creating merge -conflicts in master. - -Workflow: - -- Ensure you have auto rebase switched on in your gitconfig. -``` -[branch] - autosetuprebase = always -``` -- Fork the [LibreNMS repo master branch][2] in your own GitHub account. -- Create an [issue][3] explaining what work you plan to do. -- Create a branch in your copy of the repo called issue-####, where #### is - the issue number you created. -``` -git push origin master:issue-#### -``` -- Make and test your changes in the issue branch as needed - this might take - a few days or weeks. -- When you are happy with your issue branch's changes and ready to submit - your patch, update your copy of the master branch to the current revision; - this should just result in a fast forward of your copy of master: -``` -git checkout master -git pull -``` -- Rebase your issue branch from your clone of master; fix any conflicts at - this stage: -```` -git checkout issue-#### -git pull -```` -- Push your changes to your remote git hub branch so you can submit a pull from your issue-#### branch: -```` -git push origin issue-#### -```` -- Submit a pull request for your patch from your issue-#### branch. - -[1]: http://www.gnu.org/licenses/license-list.html -"Free Software Foundation's license list" -[2]: https://github.com/librenms/librenms/tree/master -"LibreNMS master branch" -[3]: https://github.com/librenms/librenms/issues -"LibreNMS issue database" -[4]: http://www.observium.org/wiki/License -"Observium License" - +Contributor Agreement +--------------------- + +By contributing code to LibreNMS (whether by a github pull request, or by +any other means), you assert that: + +- You have the rights to include the code, either as its original author, + or due to it being released to you under a compatible license. + +- You are not aware of any third party claims on the code, including + copyright infringement, patent, or any other claim. + +- You have not viewed code written under the [Observium License][4] in the + production of contributed code. This includes all Observium code after + Subversion revision 3250 and any patches or other code covered by that + license from Observium web sites after Tue May 29 13:08:01 2012 +0000 (the + date of Observium r3250). + +To agree with these assertions, please submit a github pull request against +the file doc/AUTHORS.md including your name, email address, and github user +id in the file (so that it can be matched to your commits), and stating in +the commit log: +``` + I agree to the conditions of the Contributor Agreement + contained in doc/CONTRIBUTING.md. +``` + + +Copyright +--------- + +All contributors to LibreNMS retain copyright to their own code and are not +required to sign over their rights to any other party. + +We recommend that if you add a new file containing original code to the code +base that you include a copyright notice in it as per the Free Software +Foundation's guidelines. You might find something like the following header +appropriate (although this is not legal advice ;-): +``` + + * + * This program is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the + * Free Software Foundation, either version 3 of the License, or (at your + * option) any later version. Please see LICENSE.txt at the top level of + * the source code distribution for details. + */ + ?> +``` +The GPLv3 itself also contains recommendations about applying the GPL to +your code. Please see LICENSE.txt at the top of this source code +distribution for details. + + +General Guidelines +------------------ + +- Test your patches first. It's easy to set up git to push to a bare + repository on a local test system, and pull from this into a live test + installation at very frequent intervals. + +- Don't break the poller. User interface blemishes are not critical, but + losing data from network monitoring systems might be. + +- As a general rule, if you're replacing lines of code with new lines of + code, don't comment them out, just delete them. Commented out code makes + the patch and the resultant code harder to read, and there's no good + reason to it since we can easily get them back from git. + +- If you're fixing a bug or making another minor change, don't reformat the + code at the same time. This makes it harder to see what's changed. If + you need to reformat it after making the change, do so in a separate + commit. + +- Please join us in IRC at irc.freenode.net in channel ##librenms if you're + able. Collaborating in real time makes the coordination of contributions + easier. + + +Integrating other code +---------------------- + +Giving credit where credit is due is critical to the Free Software +philosophy. If you use code from somewhere else, even if it's trivial, +be sure to note this as a comment in the code (preferably) or the commit +message. + +- To incorporate larger blocks of code from third parties (e.g. JavaScript + libraries): + - Include its name, source URL, copyright notice, and license in + doc/CREDITS.md + - preferred locations are html/js, html/lib, and lib + - Add it in a separate commit into its own directory, using + 'git subtree --squash' if it is available via git. + - Add the code to integrate it in a separate commit. Include: + - code to update it in Makefile + - Scrutinizer exclusions to .scrutinizer.yml + - symlinks where necessary to maintain sensible paths + +- Don't submit code whose license conflicts with the GPLv3. If you're not + sure, consult the [Free Software Foundation's license list][1] and see if + your code's license is on the compatible or incompatible list. If you + prefer a non-copyleft license, Apache 2.0 is the recommended choice as per + the FSF guidelines. + +- The current Observium license is incompatible with GPLv3. Don't submit + code from current Observium unless you are the copyright holder, and you + specifically state in the code that you are releasing it under GPLv3 (or a + compatible license). + + Because contributing to Observium requires that you reassign copyright to + Adam Armstrong, if you want to release the same code for both Observium + and LibreNMS, you need to release it for LibreNMS first and mark it with + your own copyright notice, then release it to Observium and remove your + copyright, granting Adam ownership. + + Please note that the above is necessary even if you don't care about + keeping the copyright to your code, because otherwise we could be accused + of misappropriating Obserivum's code. As the code bases develop, we + expect them to diverge, which means this will become less of an issue + anyway. + +- Because the GPL's provisions about linking don't apply to PHP-based + projects, we interpret the linking provisions of the license to refer to + the use of PHP library functions called from LibreNMS code. + + We consider inclusion of files such as MIBs in the LibreNMS repository to + be merely aggregation in a distribution medium as per the last paragraph + of the GPLv3 section 5 ("Conveying Modified Source Versions"), and because + they are not combined with LibreNMS to form a larger program, the GPLv3 + does not apply to them. This is not a legal ruling - it is simply a + statement of our intent and current interpretation. + + +Proposed workflow for submitting pull requests +---------------------------------------------- + +The basic rule is: don't create merge conflicts in master. Merges should be +simple fast-forwards from current master. + +Following is a proposed workflow designed to minimise the scope of merge +conflicts when submitting pull requests. It's not mandatory, but seems to +work well enough. + +We don't recommend git flow because we don't want to maintain separate +development and master branches, but if it works better for you, feel free +to do that, as long as you follow the golden rule of not creating merge +conflicts in master. + +Workflow: + +- Ensure you have auto rebase switched on in your gitconfig. +``` +[branch] + autosetuprebase = always +``` +- Fork the [LibreNMS repo master branch][2] in your own GitHub account. +- Create an [issue][3] explaining what work you plan to do. +- Create a branch in your copy of the repo called issue-####, where #### is + the issue number you created. +``` +git push origin master:issue-#### +``` +- Make and test your changes in the issue branch as needed - this might take + a few days or weeks. +- When you are happy with your issue branch's changes and ready to submit + your patch, update your copy of the master branch to the current revision; + this should just result in a fast forward of your copy of master: +``` +git checkout master +git pull +``` +- Rebase your issue branch from your clone of master; fix any conflicts at + this stage: +```` +git checkout issue-#### +git pull +```` +- Push your changes to your remote git hub branch so you can submit a pull from your issue-#### branch: +```` +git push origin issue-#### +```` +- Submit a pull request for your patch from your issue-#### branch. + +[1]: http://www.gnu.org/licenses/license-list.html +"Free Software Foundation's license list" +[2]: https://github.com/librenms/librenms/tree/master +"LibreNMS master branch" +[3]: https://github.com/librenms/librenms/issues +"LibreNMS issue database" +[4]: http://www.observium.org/wiki/License +"Observium License" diff --git a/doc/CREDITS.md b/doc/General/Credits.md similarity index 99% rename from doc/CREDITS.md rename to doc/General/Credits.md index c89c6f2c7b..125eb3d25a 100644 --- a/doc/CREDITS.md +++ b/doc/General/Credits.md @@ -25,3 +25,4 @@ Other components (needs details filled in): - check_mk (scripts/observium_agent*): GPLv2 - qTip (html/css/jquery.qtip.min.css and html/js/qtip/jquery.qtip.min.js): GPLv2 + diff --git a/doc/DEVEL.md b/doc/General/Developing-for-LibreNMS.md similarity index 92% rename from doc/DEVEL.md rename to doc/General/Developing-for-LibreNMS.md index e4d8e31bee..3a63348208 100644 --- a/doc/DEVEL.md +++ b/doc/General/Developing-for-LibreNMS.md @@ -1,5 +1,3 @@ -# Developing for LibreNMS - Developing for LibreNMS has never been easier. Thanks to [Wes Kennedy](https://twitter.com/livearchivist), there is @@ -9,7 +7,7 @@ that has LibreNMS already running on it! To get started, you can just copy the script from `/contrib/dev_init`, or you can enter the following commands into your shell: -```bash +``` mkdir -p dev/librenms && cd $_ curl -O http://wkennedy.co/uploads/librenms/Vagrantfile curl -O http://wkennedy.co/uploads/librenms/bootstrap.sh @@ -19,4 +17,4 @@ vagrant up This may take a few minutes and requires you to already have Vagrant installed. If you don't have Vagrant installed, it's easy to setup. -See the [installation instructions here](http://docs.vagrantup.com/v2/installation/). +See the [installation instructions here](http://docs.vagrantup.com/v2/installation/). \ No newline at end of file diff --git a/doc/General/Roadmap.md b/doc/General/Roadmap.md new file mode 100644 index 0000000000..acd9a1eb86 --- /dev/null +++ b/doc/General/Roadmap.md @@ -0,0 +1,26 @@ +- Device support: + - Ruckus wireless controllers (Paul) + - Investigate generic device support based on MIBs. It should be + possible to do basic graphs based just on the MIB. They would + obviously not be as customised as the specifically supported devices + but should still be useful to users. + +- Functionality/performance improvements: + - Investigate solutions for poller performance improvement. (Tyler) + - Investigate solutions for multiple communities per device. (tooms) + - Eliminate interface churn for transient interfaces (e.g. ppp/tun) on + net-snmp. + +- Integrate Nagios-based alerting. Allow user to choose their preferred + Nagios distribution/fork. + +- Consider adding some non-monitoring administrative functions: + - enabling/disabling ports + - changing access port VLANs + - editing port labels + +- Integrate as many usability improvements as time permits: + - Integrate nice menus like current Observium? + - Front page: more automation; GUI configuration? + +- Improve / Change alerting system \ No newline at end of file diff --git a/doc/UPDATING.md b/doc/General/Updating.md similarity index 89% rename from doc/UPDATING.md rename to doc/General/Updating.md index 416b65cc6a..5ac6973155 100644 --- a/doc/UPDATING.md +++ b/doc/General/Updating.md @@ -9,4 +9,4 @@ Is no longer commented out. If you would like to perform a manual update then yo git pull --no-edit --quiet php includes/sql-schema/update.php -This will update both the core LibreNMS files but also update the database structure if updates are available. +This will update both the core LibreNMS files but also update the database structure if updates are available. \ No newline at end of file diff --git a/doc/Home.md b/doc/Home.md new file mode 100644 index 0000000000..2fa884a5e0 --- /dev/null +++ b/doc/Home.md @@ -0,0 +1,68 @@ +LibreNMS is a fork of Observium. The reason for the fork is nothing to do +with Observium's [recent move to community vs. paid versions][1]. It is +simply that we have different priorities and values to the Observium +developers. We decided to fork (reluctantly) because we like using +Observium, but we want to collaborate on a community-based project with +like-minded IT professionals. See [README.md][2] and the references there +for more information about the kind of community we're trying to promote. + +LibreNMS was forked from [the last GPL-licensed version of Observium][3]. +This has a few implications: +- ~~It doesn't look as nice as the current version of Observium.~~ +- We've lost quite a bit of functionality that has been added to Observium + in the last year. +- You won't be able to take an existing Observium installation later than + r3250 and just change it to LibreNMS. This would probably break (although + if you were on a version between r3250 and the next database schema + change, it might be feasible). Upgrades from versions earlier than r3251 + might work. Please try it on an unimportant system and tell us your + experiences! + +How LibreNMS will be different from Observium: +- We will have an inclusive community, where it's OK to ask stupid + questions, and OK to ask for things that aren't on the roadmap. If you'd + like to see something added, add or comment on the relevant issue in our + [GitHub issue database][9]. +- Development decisions will be community-driven. We want to make software + that fulfills its users' needs. See the [ROADMAP][4] for more thoughts + on our current plans. +- Development will probably proceed at a slower pace, at least initially. +- There are no plans for a paid version, and we don't anticipate this ever + changing. +- There are no current plans for paid support, but this may be added later + if there is sufficient demand. +- We use git for version control and GitHub for hosting to make it as easy + and painless as possible to create forked or private versions. + +Reasons why you might want to use Observium instead of LibreNMS: +- You have a financial investment in Observium and aren't concerned about + community contributions. +- You need the extra functionality that has been added to Observium since + r3250. +- You don't like the [GNU General Public License, version 3][5] or the + [philosophy of Free Software][6] in general. + +Reasons why you might want to use LibreNMS instead of Observium: +- You want to work with others on the project, knowing that [your + investment of time and effort will not be wasted][7]. +- You want to add and experiment with features that are not a priority for + the Observium developers. See [CONTRIBUTING][8] for more details. + +[1]: http://postman.memetic.org/pipermail/observium/2013-October/003915.html +"Observium edition split announcement" +[2]: https://github.com/librenms/librenms/blob/master/README.md +"LibreNMS README" +[3]: http://fisheye.observium.org/rdiff/Observium?csid=3251&u&N +"Link to Observium license change" +[4]: https://github.com/librenms/librenms/blob/master/doc/ROADMAP.md +"LibreNMS ROADMAP" +[5]: https://github.com/librenms/librenms/blob/master/LICENSE.txt +"LibreNMS copy of GPL v3" +[6]: http://www.gnu.org/philosophy/free-sw.html +"Free Software Foundation - what is free software?" +[7]: http://libertysys.com.au/blog/observium-and-gpl +"Paul's blog on what the GPL offers users" +[8]: https://github.com/librenms/librenms/blob/master/doc/CONTRIBUTING.md +"Contribution guidelines" +[9]: https://github.com/librenms/librenms/issues +"LibreNMS issue database at GitHub" \ No newline at end of file diff --git a/doc/INSTALL.md b/doc/Installation/Installation-(Debian-Ubuntu).md similarity index 99% rename from doc/INSTALL.md rename to doc/Installation/Installation-(Debian-Ubuntu).md index 7b7da82e12..000d947a07 100644 --- a/doc/INSTALL.md +++ b/doc/Installation/Installation-(Debian-Ubuntu).md @@ -174,4 +174,4 @@ That's it! You now should be able to log in to http://librenms.example.com/. P [1]: https://github.com/Atrato/observium-poller-wrapper [2]: http://git-scm.com/book -[3]: http://gitready.com/ +[3]: http://gitready.com/ \ No newline at end of file diff --git a/doc/INSTALL_RHEL.md b/doc/Installation/Installation-(RHEL-CentOS).md similarity index 99% rename from doc/INSTALL_RHEL.md rename to doc/Installation/Installation-(RHEL-CentOS).md index f2d2c096a0..e3c9ee9a7f 100644 --- a/doc/INSTALL_RHEL.md +++ b/doc/Installation/Installation-(RHEL-CentOS).md @@ -204,4 +204,4 @@ ing your `config.php` file. Remove the comment (the `#` mark) on the line: so that it looks like this: - $config['update'] = 0; + $config['update'] = 0; \ No newline at end of file diff --git a/doc/INSTALL_LIGHTTPD.md b/doc/Installation/Installation-Lighttpd-(Debian-Ubuntu).md similarity index 99% rename from doc/INSTALL_LIGHTTPD.md rename to doc/Installation/Installation-Lighttpd-(Debian-Ubuntu).md index 1673b7e137..abb62fbe38 100644 --- a/doc/INSTALL_LIGHTTPD.md +++ b/doc/Installation/Installation-Lighttpd-(Debian-Ubuntu).md @@ -146,4 +146,4 @@ LibreNMS performs daily updates by default. At 00:15 system time every day, a ` so that it looks like this: - $config['update'] = 0; + $config['update'] = 0; \ No newline at end of file diff --git a/doc/Observium_Welcome.md b/doc/Observium-Welcome.md similarity index 99% rename from doc/Observium_Welcome.md rename to doc/Observium-Welcome.md index 1a1d91bb98..f8bd25e4a1 100644 --- a/doc/Observium_Welcome.md +++ b/doc/Observium-Welcome.md @@ -70,3 +70,4 @@ Reasons why you might want to use LibreNMS instead of Observium: [9]: https://github.com/librenms/librenms/issues "LibreNMS issue database at GitHub" + diff --git a/doc/ROADMAP.md b/doc/ROADMAP.md deleted file mode 100644 index cbe215ca6d..0000000000 --- a/doc/ROADMAP.md +++ /dev/null @@ -1,27 +0,0 @@ -Roadmap -------- - -- Device support: - - Investigate generic device support based on MIBs. It should be - possible to do basic graphs based just on the MIB. They would - obviously not be as customised as the specifically supported devices - but should still be useful to users. - - Ruckus wireless controllers - -- Functionality/performance improvements: - - Eliminate interface churn for transient interfaces (e.g. ppp/tun) - on net-snmp. - - Investigate solutions for poller performance improvement. - - Investigate solutions for multiple communities/ports per device. - -- Integrate Nagios-based alerting. Allow user to choose their preferred - Nagios distribution/fork. - -- Consider adding some non-monitoring administrative functions: - - enabling/disabling ports - - changing access port VLANs - - editing port labels - -- Integrate as many usability improvements as time permits: - - Front page customisation - - GUI configuration of most options diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md new file mode 100644 index 0000000000..699cfb590b --- /dev/null +++ b/doc/_Sidebar.md @@ -0,0 +1,25 @@ +- **[[Home]]** +- **General** + - [[Observium Welcome]] + - [[Contributing]] + - [[Updating]] + - [[Roadmap]] + - [[Developing for LibreNMS]] + - [[Credits]] +- **Installation** + - [[Installation (Debian Ubuntu)]] + - [[Installation (RHEL CentOS)]] + - [[Installation Lighttpd (Debian Ubuntu)]] +- **Extensions** + - [[Billing Module]] + - [[Email Alerting]] + - [[IRC Bot]] + - [[IRC Bot Extensions]] + - [[Plugin System]] + - [[Interface Description Parsing]] + - [[Agent Setup]] + - [[Alerting]] + - [[Two Factor Auth]] +- **API** + - [[API Docs]] + From 9c716caf2c3469b9bbdba9a308fd0b0f7f6054ab Mon Sep 17 00:00:00 2001 From: Neil Lathwood Date: Sat, 10 Jan 2015 00:23:25 +0000 Subject: [PATCH 2/3] Updating docs for RTD --- doc/API/API-Docs.md | 61 +++++++++++++++++++++++---------------------- doc/_Sidebar.md | 25 ------------------- 2 files changed, 31 insertions(+), 55 deletions(-) delete mode 100644 doc/_Sidebar.md diff --git a/doc/API/API-Docs.md b/doc/API/API-Docs.md index db09bb93cc..c6f3976d90 100644 --- a/doc/API/API-Docs.md +++ b/doc/API/API-Docs.md @@ -1,35 +1,36 @@ +- API -- [`structure`](#api-structure) - - [`versioning`](#api-versioning) - - [`token`](#api-tokens) - - [`end-points`](#api-end_points) - - [`input`](#api-input) - - [`output`](#api-output) +- [`Structure`](#api-structure) + - [`Versioning`](#api-versioning) + - [`token`](#api-tokens) + - [`end-points`](#api-end_points) + - [`input`](#api-input) + - [`output`](#api-output) - [`endpoints`](#api-endpoints) - - [`devices`](#api-devices) - - [`del_device`](#api-route-2) - - [`get_device`](#api-route-3) - - [`get_graphs`](#api-route-5) - - [`get_graph_generic_by_hostname`](#api-route-6) - - [`get_port_graphs`](#api-route-7) - - [`get_port_stats_by_port_hostname`](#api-route-8) - - [`get_graph_by_port_hostname`](#api-route-9) - - [`list_devices`](#api-route-10) - - [`add_device`](#api-route-11) - - [`routing`](#api-routing) - - [`list_bgp`](#api-route-1) - - [`switching`](#api-switching) - - [`get_vlans`](#api-route-4) - - [`alerts`](#api-alerts) - - [`get_alert`](#api-route-12) - - [`ack_alert`](#api-route-13) - - [`list_alerts`](#api-route-14) - - [`rules`](#api-rules) - - [`get_alert_rule`](#api-route-15) - - [`delete_rule`](#api-route-16) - - [`list_alert_rules`](#api-route-17) - - [`add_rule`](#api-route-18) - - [`edit_rule`](#api-route-19) + - [`devices`](#api-devices) + - [`del_device`](#api-route-2) + - [`get_device`](#api-route-3) + - [`get_graphs`](#api-route-5) + - [`get_graph_generic_by_hostname`](#api-route-6) + - [`get_port_graphs`](#api-route-7) + - [`get_port_stats_by_port_hostname`](#api-route-8) + - [`get_graph_by_port_hostname`](#api-route-9) + - [`list_devices`](#api-route-10) + - [`add_device`](#api-route-11) + - [`routing`](#api-routing) + - [`list_bgp`](#api-route-1) + - [`switching`](#api-switching) + - [`get_vlans`](#api-route-4) + - [`alerts`](#api-alerts) + - [`get_alert`](#api-route-12) + - [`ack_alert`](#api-route-13) + - [`list_alerts`](#api-route-14) + - [`rules`](#api-rules) + - [`get_alert_rule`](#api-route-15) + - [`delete_rule`](#api-route-16) + - [`list_alert_rules`](#api-route-17) + - [`add_rule`](#api-route-18) + - [`edit_rule`](#api-route-19) Describes the API structure. diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md deleted file mode 100644 index 699cfb590b..0000000000 --- a/doc/_Sidebar.md +++ /dev/null @@ -1,25 +0,0 @@ -- **[[Home]]** -- **General** - - [[Observium Welcome]] - - [[Contributing]] - - [[Updating]] - - [[Roadmap]] - - [[Developing for LibreNMS]] - - [[Credits]] -- **Installation** - - [[Installation (Debian Ubuntu)]] - - [[Installation (RHEL CentOS)]] - - [[Installation Lighttpd (Debian Ubuntu)]] -- **Extensions** - - [[Billing Module]] - - [[Email Alerting]] - - [[IRC Bot]] - - [[IRC Bot Extensions]] - - [[Plugin System]] - - [[Interface Description Parsing]] - - [[Agent Setup]] - - [[Alerting]] - - [[Two Factor Auth]] -- **API** - - [[API Docs]] - From 3a53d50e279b1e5ca29da0b06fb858c209367ecb Mon Sep 17 00:00:00 2001 From: Neil Lathwood Date: Sat, 10 Jan 2015 01:24:38 +0000 Subject: [PATCH 3/3] Updated some links and created initial index page --- doc/Extensions/Alerting.md | 2 +- doc/General/Contributing.md | 4 +-- doc/Home.md | 68 ------------------------------------- doc/Observium-Welcome.md | 4 +-- doc/index.md | 1 + 5 files changed, 6 insertions(+), 73 deletions(-) delete mode 100644 doc/Home.md create mode 100644 doc/index.md diff --git a/doc/Extensions/Alerting.md b/doc/Extensions/Alerting.md index 8eeb940205..2d3ea0d69b 100644 --- a/doc/Extensions/Alerting.md +++ b/doc/Extensions/Alerting.md @@ -160,7 +160,7 @@ $config['alert']['transports']['nagios'] = "/path/to/my.fifo"; //Flapjack expect ## IRC 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/IRC-Bot.md). +Configuration of the LibreNMS IRC-Bot is described [here](https://github.com/librenms/librenms/blob/master/doc/Extensions/IRC-Bot.md). ```php $config['alert']['transports']['irc'] = true; ``` diff --git a/doc/General/Contributing.md b/doc/General/Contributing.md index 3075467427..b73c1cd04f 100644 --- a/doc/General/Contributing.md +++ b/doc/General/Contributing.md @@ -22,7 +22,7 @@ id in the file (so that it can be matched to your commits), and stating in the commit log: ``` I agree to the conditions of the Contributor Agreement - contained in doc/CONTRIBUTING.md. + contained in doc/General/Contributing.md. ``` @@ -92,7 +92,7 @@ message. - To incorporate larger blocks of code from third parties (e.g. JavaScript libraries): - Include its name, source URL, copyright notice, and license in - doc/CREDITS.md + doc/General/Credits.md - preferred locations are html/js, html/lib, and lib - Add it in a separate commit into its own directory, using 'git subtree --squash' if it is available via git. diff --git a/doc/Home.md b/doc/Home.md deleted file mode 100644 index 2fa884a5e0..0000000000 --- a/doc/Home.md +++ /dev/null @@ -1,68 +0,0 @@ -LibreNMS is a fork of Observium. The reason for the fork is nothing to do -with Observium's [recent move to community vs. paid versions][1]. It is -simply that we have different priorities and values to the Observium -developers. We decided to fork (reluctantly) because we like using -Observium, but we want to collaborate on a community-based project with -like-minded IT professionals. See [README.md][2] and the references there -for more information about the kind of community we're trying to promote. - -LibreNMS was forked from [the last GPL-licensed version of Observium][3]. -This has a few implications: -- ~~It doesn't look as nice as the current version of Observium.~~ -- We've lost quite a bit of functionality that has been added to Observium - in the last year. -- You won't be able to take an existing Observium installation later than - r3250 and just change it to LibreNMS. This would probably break (although - if you were on a version between r3250 and the next database schema - change, it might be feasible). Upgrades from versions earlier than r3251 - might work. Please try it on an unimportant system and tell us your - experiences! - -How LibreNMS will be different from Observium: -- We will have an inclusive community, where it's OK to ask stupid - questions, and OK to ask for things that aren't on the roadmap. If you'd - like to see something added, add or comment on the relevant issue in our - [GitHub issue database][9]. -- Development decisions will be community-driven. We want to make software - that fulfills its users' needs. See the [ROADMAP][4] for more thoughts - on our current plans. -- Development will probably proceed at a slower pace, at least initially. -- There are no plans for a paid version, and we don't anticipate this ever - changing. -- There are no current plans for paid support, but this may be added later - if there is sufficient demand. -- We use git for version control and GitHub for hosting to make it as easy - and painless as possible to create forked or private versions. - -Reasons why you might want to use Observium instead of LibreNMS: -- You have a financial investment in Observium and aren't concerned about - community contributions. -- You need the extra functionality that has been added to Observium since - r3250. -- You don't like the [GNU General Public License, version 3][5] or the - [philosophy of Free Software][6] in general. - -Reasons why you might want to use LibreNMS instead of Observium: -- You want to work with others on the project, knowing that [your - investment of time and effort will not be wasted][7]. -- You want to add and experiment with features that are not a priority for - the Observium developers. See [CONTRIBUTING][8] for more details. - -[1]: http://postman.memetic.org/pipermail/observium/2013-October/003915.html -"Observium edition split announcement" -[2]: https://github.com/librenms/librenms/blob/master/README.md -"LibreNMS README" -[3]: http://fisheye.observium.org/rdiff/Observium?csid=3251&u&N -"Link to Observium license change" -[4]: https://github.com/librenms/librenms/blob/master/doc/ROADMAP.md -"LibreNMS ROADMAP" -[5]: https://github.com/librenms/librenms/blob/master/LICENSE.txt -"LibreNMS copy of GPL v3" -[6]: http://www.gnu.org/philosophy/free-sw.html -"Free Software Foundation - what is free software?" -[7]: http://libertysys.com.au/blog/observium-and-gpl -"Paul's blog on what the GPL offers users" -[8]: https://github.com/librenms/librenms/blob/master/doc/CONTRIBUTING.md -"Contribution guidelines" -[9]: https://github.com/librenms/librenms/issues -"LibreNMS issue database at GitHub" \ No newline at end of file diff --git a/doc/Observium-Welcome.md b/doc/Observium-Welcome.md index f8bd25e4a1..60f108bd74 100644 --- a/doc/Observium-Welcome.md +++ b/doc/Observium-Welcome.md @@ -57,7 +57,7 @@ Reasons why you might want to use LibreNMS instead of Observium: "LibreNMS README" [3]: http://fisheye.observium.org/rdiff/Observium?csid=3251&u&N "Link to Observium license change" -[4]: https://github.com/librenms/librenms/blob/master/doc/ROADMAP.md +[4]: https://github.com/librenms/librenms/blob/master/doc/General/Roadmap.md "LibreNMS ROADMAP" [5]: https://github.com/librenms/librenms/blob/master/LICENSE.txt "LibreNMS copy of GPL v3" @@ -65,7 +65,7 @@ Reasons why you might want to use LibreNMS instead of Observium: "Free Software Foundation - what is free software?" [7]: http://libertysys.com.au/blog/observium-and-gpl "Paul's blog on what the GPL offers users" -[8]: https://github.com/librenms/librenms/blob/master/doc/CONTRIBUTING.md +[8]: https://github.com/librenms/librenms/blob/master/doc/General/Contributing.md "Contribution guidelines" [9]: https://github.com/librenms/librenms/issues "LibreNMS issue database at GitHub" diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000000..1fd87742d7 --- /dev/null +++ b/doc/index.md @@ -0,0 +1 @@ +# Welcome to the documentation for [LibreNMS](https://github.com/librenms/librenms)