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..c6f3976d90 --- /dev/null +++ b/doc/API/API-Docs.md @@ -0,0 +1,721 @@ +- API + +- [`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 99% rename from doc/Alerting.md rename to doc/Extensions/Alerting.md index 8eeb940205..2d3ea0d69b 100644 --- a/doc/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/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 98% rename from doc/CONTRIBUTING.md rename to doc/General/Contributing.md index b4de37ad26..625251a273 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/General/Contributing.md @@ -1,4 +1,4 @@ -Contributor Agreement +ontributor Agreement --------------------- By contributing code to LibreNMS (whether by a github pull request, or by @@ -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. @@ -194,4 +194,3 @@ git push origin issue-#### "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/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 95% rename from doc/Observium_Welcome.md rename to doc/Observium-Welcome.md index 1a1d91bb98..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,8 +65,9 @@ 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/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/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)