mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
338 lines
7.3 KiB
Markdown
338 lines
7.3 KiB
Markdown
### `get_devicegroups`
|
|
|
|
List all device groups.
|
|
|
|
Route: `/api/v0/devicegroups`
|
|
|
|
Input (JSON):
|
|
|
|
-
|
|
|
|
Examples:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devicegroups
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"status": "ok",
|
|
"message": "Found 1 device groups",
|
|
"count": 1,
|
|
"groups": [
|
|
{
|
|
"id": "1",
|
|
"name": "Testing",
|
|
"desc": "Testing",
|
|
"pattern": "%devices.status = \"1\" &&"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
### `add_devicegroup`
|
|
|
|
Add a new device group. Upon success, the ID of the new device group is returned
|
|
and the HTTP response code is `201`.
|
|
|
|
Route: `/api/v0/devicegroups`
|
|
|
|
Input (JSON):
|
|
|
|
- `name`: *required* - The name of the device group
|
|
- `type`: *required* - should be `static` or `dynamic`. Setting this to static
|
|
requires that the devices input be provided
|
|
- `desc`: *optional* - Description of the device group
|
|
- `rules`: *required if type == dynamic* - A set of rules to determine which
|
|
devices should be included in this device group
|
|
- `devices`: *required if type == static* - A list of devices that should be
|
|
included in this group. This is a static list of devices
|
|
|
|
Examples:
|
|
|
|
Dynamic Example:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
|
|
-X POST https://librenms.org/api/v0/devicegroups \
|
|
--data-raw '
|
|
{
|
|
"name": "New Device Group",
|
|
"desc": "A very fancy dynamic group",
|
|
"type": "dynamic",
|
|
"rules": "{\"condition\":\"AND\",\"rules\":[{\"id\":\"access_points.name\",\"field\":\"access_points.name\",\"type\":\"string\",\"input\":\"text\",\"operator\":\"equal\",\"value\":\"accesspoint1\"}],\"valid\":true}"
|
|
}
|
|
'
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"id": 86,
|
|
"message": "Device group New Device Group created"
|
|
}
|
|
```
|
|
|
|
Static Example:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
|
|
-X POST https://librenms.org/api/v0/devicegroups \
|
|
-d '{"name":"New Device Group","type":"static","devices":[261,271]}'
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"id": 86,
|
|
"message": "Device group New Device Group created"
|
|
}
|
|
```
|
|
|
|
### `update_devicegroup`
|
|
|
|
Updates a device group.
|
|
|
|
Route: `/api/v0/devicegroups/:name`
|
|
|
|
- name Is the name of the device group which can be obtained using
|
|
[`get_devicegroups`](#function-get_devicegroups). Please ensure that
|
|
the name is urlencoded if it needs to be (i.e Linux Servers would
|
|
need to be urlencoded.
|
|
|
|
Input (JSON):
|
|
|
|
- `name`: *optional* - The name of the device group
|
|
- `type`: *optional* - should be `static` or `dynamic`. Setting this to static
|
|
requires that the devices input be provided
|
|
- `desc`: *optional* - Description of the device group
|
|
- `rules`: *required if type == dynamic* - A set of rules to determine which
|
|
devices should be included in this device group
|
|
- `devices`: *required if type == static* - A list of devices that should be
|
|
included in this group. This is a static list of devices
|
|
|
|
Examples:
|
|
|
|
```curl
|
|
curl -X PATCH -d '{"name": "NewLinuxServers"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/LinuxServers
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Device group LinuxServers updated"
|
|
}
|
|
```
|
|
|
|
### `delete_devicegroup`
|
|
|
|
Deletes a device group.
|
|
|
|
Route: `/api/v0/devicegroups/:name`
|
|
|
|
- name Is the name of the device group which can be obtained using
|
|
[`get_devicegroups`](#function-get_devicegroups). Please ensure that
|
|
the name is urlencoded if it needs to be (i.e Linux Servers would
|
|
need to be urlencoded.
|
|
|
|
Input:
|
|
|
|
-
|
|
|
|
Examples:
|
|
|
|
```curl
|
|
curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/LinuxServers
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Device group LinuxServers deleted"
|
|
}
|
|
```
|
|
|
|
### `get_devices_by_group`
|
|
|
|
List all devices matching the group provided.
|
|
|
|
Route: `/api/v0/devicegroups/:name`
|
|
|
|
- name Is the name of the device group which can be obtained using
|
|
[`get_devicegroups`](#function-get_devicegroups). Please ensure that
|
|
the name is urlencoded if it needs to be (i.e Linux Servers would
|
|
need to be urlencoded.
|
|
|
|
Input (JSON):
|
|
|
|
- full: set to any value to return all data for the devices in a given group
|
|
|
|
Examples:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devicegroups/LinuxServers
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"status": "ok",
|
|
"message": "Found 3 in group LinuxServers",
|
|
"count": 3,
|
|
"devices": [
|
|
{
|
|
"device_id": "15"
|
|
},
|
|
{
|
|
"device_id": "18"
|
|
},
|
|
{
|
|
"device_id": "20"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
### `maintenance_devicegroup`
|
|
|
|
Set a device group into maintenance mode.
|
|
|
|
Route: `/api/v0/devicesgroups/:name/maintenance`
|
|
|
|
Input (JSON):
|
|
|
|
- `title`: *optional* - Some title for the Maintenance
|
|
Will be replaced with device group name if omitted
|
|
- `notes`: *optional* - Some description for the Maintenance
|
|
- `start`: *optional* - start time of Maintenance in full format `Y-m-d H:i:00`
|
|
eg: 2022-08-01 22:45:00
|
|
Current system time `now()` will be used if omitted
|
|
- `duration`: *required* - Duration of Maintenance in format `H:i` / `Hrs:Mins`
|
|
eg: 02:00
|
|
|
|
Example with start time:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
|
|
-X POST https://librenms.org/api/v0/devicegroups/Cisco%20switches/maintenance/ \
|
|
--data-raw '
|
|
{
|
|
"title":"Device group Maintenance",
|
|
"notes":"A 2 hour Maintenance triggered via API with start time",
|
|
"start":"2022-08-01 08:00:00",
|
|
"duration":"2:00"
|
|
}
|
|
'
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Device group Cisco switches (2) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
|
|
}
|
|
```
|
|
|
|
Example with no start time:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
|
|
-X POST https://librenms.org/api/v0/devicegroups/Cisco%20switches/maintenance/ \
|
|
--data-raw '
|
|
{
|
|
"title":"Device group Maintenance",
|
|
"notes":"A 2 hour Maintenance triggered via API with no start time",
|
|
"duration":"2:00"
|
|
}
|
|
'
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Device group Cisco switches (2) moved into maintenance mode for 2:00h"
|
|
}
|
|
```
|
|
|
|
### Add devices to group
|
|
|
|
Add devices to a device group.
|
|
|
|
Route: `/api/v0/devicesgroups/:name/devices`
|
|
|
|
- name Is the name of the device group which can be obtained using
|
|
[`get_devicegroups`](#function-get_devicegroups). Please ensure that
|
|
the name is urlencoded if it needs to be (i.e Linux Servers would
|
|
need to be urlencoded.
|
|
|
|
Input (JSON):
|
|
|
|
- `devices`: *required* - A list of devices to be added to the group.
|
|
|
|
Example:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
|
|
-X POST https://librenms.org/api/v0/devicegroups/devices \
|
|
--data-raw '{"devices":[261,271]}'
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Devices added"
|
|
}
|
|
```
|
|
|
|
### Remove devices from group
|
|
|
|
Removes devices from a device group.
|
|
|
|
Route: `/api/v0/devicesgroups/:name/devices`
|
|
|
|
- name Is the name of the device group which can be obtained using
|
|
[`get_devicegroups`](#function-get_devicegroups). Please ensure that
|
|
the name is urlencoded if it needs to be (i.e Linux Servers would
|
|
need to be urlencoded.
|
|
|
|
Input (JSON):
|
|
|
|
- `devices`: *required* - A list of devices to be removed from the group.
|
|
|
|
Example:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
|
|
-X DELETE https://librenms.org/api/v0/devicegroups/devices \
|
|
--data-raw '{"devices":[261,271]}'
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Devices removed"
|
|
}
|
|
```
|