mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
Merge branch 'laf-issue-99'
(Changed doc/General/Contributing.md to use Unix file format instead of DOS.)
This commit is contained in:
Paul Gear
721
doc/API/API-Docs.md
Normal file
721
doc/API/API-Docs.md
Normal file
@@ -0,0 +1,721 @@
|
||||
- API
|
||||
<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.
|
||||
*
|
||||
|
||||
@@ -160,7 +160,7 @@ $config['alert']['transports']['nagios'] = "/path/to/my.fifo"; //Flapjack expect
|
||||
## <a name="transports-irc">IRC</a>
|
||||
|
||||
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;
|
||||
```
|
||||
@@ -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,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"
|
||||
|
||||
@@ -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.
|
||||
@@ -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;
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -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
|
||||
1
doc/index.md
Normal file
1
doc/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Welcome to the documentation for [LibreNMS](https://github.com/librenms/librenms)
|
||||
Reference in New Issue
Block a user