mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
Updated document structure
This commit is contained in:
Neil Lathwood
720
doc/API/API-Docs.md
Normal file
720
doc/API/API-Docs.md
Normal file
@@ -0,0 +1,720 @@
|
||||
<a name="top"></a>
|
||||
- [`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.
|
||||
|
||||
# <a name="api-structure">`Structure`</a> [`top`](#top)
|
||||
|
||||
## <a name="api-versioning">`Versioning`</a> [`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.
|
||||
|
||||
## <a name="api-tokens">`Tokens`</a> [`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.
|
||||
|
||||
## <a name="api-end_points">`Endpoints`</a> [`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"
|
||||
}
|
||||
```
|
||||
|
||||
## <a name="api-input">`Input`</a> [`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
|
||||
```
|
||||
|
||||
## <a name="api-output">`Output`</a> [`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.
|
||||
|
||||
# <a name="api-endpoints">`Endpoints`</a> [`top`](#top)
|
||||
|
||||
## <a name="api-devices">`Devices`</a> [`top`](#top)
|
||||
|
||||
### <a name="api-route-2">Function: `del_device`</a> [`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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-3">Function: `get_device`</a> [`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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-5">Function: `get_graphs`</a> [`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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-6">Function: `get_graph_generic_by_hostname`</a> [`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.
|
||||
|
||||
### <a name="api-route-7">Function: `get_port_graphs`</a> [`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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-8">Function: `get_port_stats_by_port_hostname`</a> [`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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-9">Function: `get_graph_by_port_hostname`</a> [`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.
|
||||
|
||||
### <a name="api-route-10">Function: `list_devices`</a> [`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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-11">Function: `add_device`</a> [`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"
|
||||
}
|
||||
```
|
||||
|
||||
## <a name="api-routing">`Routing`</a> [`top`](#top)
|
||||
|
||||
### <a name="api-route-1">Function: `list_bgp`</a> [`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": [
|
||||
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## <a name="api-switching">`Switching`</a> [`top`](#top)
|
||||
|
||||
### <a name="api-route-4">Function: `get_vlans`</a> [`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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## <a name="api-alerts">`Alerts`</a> [`top`](#top)
|
||||
|
||||
### <a name="api-route-12">Function: `get_alert`</a> [`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"
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-13">Function: `ack_alert`</a> [`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"
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-14">Function: `list_alerts`</a> [`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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## <a name="api-rules">`Rules`</a> [`top`](#top)
|
||||
|
||||
### <a name="api-route-15">Function: `get_alert_rule`</a> [`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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-16">Function: `delete_rule`</a> [`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"
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-17">Function: `list_alert_rules`</a> [`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"
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-18">Function: `add_rule`</a> [`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": ""
|
||||
}
|
||||
```
|
||||
|
||||
### <a name="api-route-19">Function: `edit_rule`</a> [`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": ""
|
||||
}
|
||||
```
|
||||
@@ -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.
|
||||
*
|
||||
|
||||
@@ -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.
|
||||
23
doc/Extensions/Email-Alerting.md
Normal file
23
doc/Extensions/Email-Alerting.md
Normal file
@@ -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" <projectid@`hostname`>
|
||||
$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
|
||||
```
|
||||
@@ -41,7 +41,7 @@ Function( (Type) $Variable [= Default] [,...] ) | Returns | Description
|
||||
|
||||
### <a name="glob.attr">Attributes</a>
|
||||
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";
|
||||
...
|
||||
```
|
||||
```
|
||||
@@ -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`)
|
||||
|
||||
### <a name="commands">IRC-Commands</a>
|
||||
|
||||
@@ -127,4 +127,4 @@ File: includes/ircbot/echo.inc.php
|
||||
} else {
|
||||
return $this->respond("root shouldn't be online so late!");
|
||||
}
|
||||
```
|
||||
```
|
||||
@@ -52,4 +52,4 @@ See [examples](#examples) for formats.
|
||||
|
||||
# <a name="source">Sourcecode</a>:
|
||||
|
||||
* https://github.com/librenms/librenms/blob/master/scripts/ifAlias
|
||||
* https://github.com/librenms/librenms/blob/master/scripts/ifAlias
|
||||
@@ -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).
|
||||
@@ -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
|
||||
|
||||
@@ -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 ;-):
|
||||
```
|
||||
<?php
|
||||
/*
|
||||
* LibreNMS module to frob blurgs from a foo bar
|
||||
*
|
||||
* Copyright (c) 2014 Internet Widgitz Pty Ltd <http://example.com/>
|
||||
*
|
||||
* 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 ;-):
|
||||
```
|
||||
<?php
|
||||
/*
|
||||
* LibreNMS module to frob blurgs from a foo bar
|
||||
*
|
||||
* Copyright (c) 2014 Internet Widgitz Pty Ltd <http://example.com/>
|
||||
*
|
||||
* 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"
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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/).
|
||||
26
doc/General/Roadmap.md
Normal file
26
doc/General/Roadmap.md
Normal file
@@ -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
|
||||
@@ -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.
|
||||
68
doc/Home.md
Normal file
68
doc/Home.md
Normal file
@@ -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"
|
||||
@@ -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/
|
||||
@@ -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;
|
||||
@@ -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;
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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
|
||||
25
doc/_Sidebar.md
Normal file
25
doc/_Sidebar.md
Normal file
@@ -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]]
|
||||
|
||||
Reference in New Issue
Block a user