librenms-librenms/doc/API/Devices.md at master

mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00

Files

Tony Murray e08571c38c Transceiver Support (#16165 )

* Add transceivers module

Move os specific code to OS

Fix errors and updated connector names

Add RouterOS, a lot less data there.

Add Comware

Add Exa, required a transformer function (mw to dBm)

Add Junos, revision was too short

Just starting on ui

Graphs, and more ui
some polling fixes

collapse header for small screens

refactor a bit

Missed graphs

Transceivers icon inline

Use @once on popup javascript

update db_schema.yaml

Don't show transceivers in basic view
basic view could use a review

Apply fixes from StyleCI

API functions

Comware don't fail if port is missing

Apply fixes from StyleCI

Add alert rules to collection

Device Overview

Attempt to fix bad alert rule, probably needs more

Fix up Comware and remove old sensors

Mark transceiver metrics without thresholds as Unknown

Routeros cleanup

Exa cleanup

Handle missing port

Graph allow filter by channel

More translations

Add transceiver graphs to port graphs

Add Cisco support, use entPhyscial module data if available

Fix OcNos divisors

Labels on transceiver page

Show encoding if available

Hacky OcNos port mapping

Fix up Junos optics and remove old sensors

FS switch support
Metric casts to prevent thrashing
Extra transform_function support

Add link to transceivers page from overview

Change default sort to group by type, then channel
move some code out of overview blade template
Fix bad type ocnos

Apply fixes from StyleCI

Add scales to graphs

Add some test data

Default sort order for metrcis in SQL applied by default

Transceiver metrics threshold manual settings via WebUI and API

Fixes to channels verbiage

Fix severity calculations

Add cable field for SM/MM/Copper

Apply fixes from StyleCI

update test data

Show DDM

Update DB schema file

Extend serial field to 32, even though devices shouldn't be able to have one longer than 16

Missing import

Add status field to database, that way we can support snmp implementations that only return an enum

Add missing files

Fix db_schema

Fix style

Fixes

Style fix

Work around phpstan issue

Update transceivers.blade.php

Missed getStatus() call

Prevent extra dots when channels are not changed

Update module to match upstream

Save ocnos metrics as sensors

Move to regular sensors

add entity physical index

Update UI to sensors WIP

Apply fixes from StyleCI

Forgot one change

Update ui to use sensors

Remove transceiver metrics

Remove metric os discover code
fs-switch pending

Remove transceiver metrics for fs-centec

Exa link up

Revert all test data

Fix up transceiver module interface

Remove unused Convert class

comware cache and transceiver type

Fix some transceiver metrics filtering and formatting issues

Consolidate display formatting

Coalesce commare hh3cTransceiverTable walks to prevent double walk

Use group to identify transceiver sensors

Fixup routeros

Fix up cisco

update db_schema

Small addition to docs

Improve overview layout and add graph popup

Update Junos

update css files

ddm should be nullable

Increase the field length for type and model

Cisco Improve detection when there is an intermediary container

Add transceiver test data

Apply fixes from StyleCI

Fix incorrect test data

Improve display formatting

Fix test data

Apply fixes from StyleCI

Fix up more data

Fix up more data

Fix incorrect return type in routeros

Update ocnos data

* Remove some remaining references to transceiver_metrics table

2024-09-29 11:05:44 -05:00

35 KiB

Raw Permalink Blame History

`del_device`

Delete a given device.

Route: /api/v0/devices/:hostname

hostname can be either the device hostname or id

Input:

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

{
    "status": "ok",
    "message": "Removed device localhost",
    "devices": [
        {
            "device_id": "1",
            "hostname": "localhost",
            ...
            "serial": null,
            "icon": null
        }
    ]
}

`get_device`

Get details of a given device.

Route: /api/v0/devices/:hostname

hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

{
    "status": "ok",
    "devices": [
        {
            "device_id": "1",
            "hostname": "localhost",
            ...
            "serial": null,
            "icon": null
        }
    ]
}

`discover_device`

Trigger a discovery of given device.

Route: /api/v0/devices/:hostname/discover

hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/discover

Output:

{
    "status": "ok",
    "result": {
        "status": 0,
        "message": "Device will be rediscovered"
    },
    "count": 2
}

`availability`

Get calculated availabilities of given device.

Route: /api/v0/devices/:hostname/availability

hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/availability

Output:

{
    "status": "ok",
    "availability": [
        {
            "duration": 86400,
            "availability_perc": "100.000000"
        },
        {
            "duration": 604800,
            "availability_perc": "100.000000"
        },
        {
            "duration": 2592000,
            "availability_perc": "99.946000"
        },
        {
            "duration": 31536000,
            "availability_perc": "99.994000"
        }
    ],
    "count": 4
}

`outages`

Get detected outages of given device.

Route: /api/v0/devices/:hostname/outages

hostname can be either the device hostname or id

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/outages

Output:

{
    "status": "ok",
    "outages": [
        {
            "going_down": 1593194031,
            "up_again": 1593194388
        },
        {
            "going_down": 1593946507,
            "up_again": 1593946863
        },
        {
            "going_down": 1594628616,
            "up_again": 1594628968
        },
        {
            "going_down": 1594628974,
            "up_again": 1594629339
        },
        {
            "going_down": 1594638668,
            "up_again": 1594638992
        }
    ],
    "count": 5
}

`get_graphs`

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 -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs

Output:

{
    "status": "ok",
    "message": "",
    "count": 3,
    "graphs": [
        {
            "desc": "Poller Time",
            "name": "device_poller_perf"
        },
        {
            "desc": "Ping Response",
            "name": "device_ping_perf"
        },
        {
            "desc": "System Uptime",
            "name": "uptime"
        }
    ]
}

`list_available_health_graphs`

This function allows to do three things:

Get a list of overall health graphs available.
Get a list of health graphs based on provided class.
Get the health sensors information based on ID.

Route: /api/v0/devices/:hostname/health(/:type)(/:sensor_id)

hostname can be either the device hostname or id
type (optional) is health type / sensor class
sensor_id (optional) is the sensor id to retrieve specific information.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health

Output:

{
    "status": "ok",
    "message": "",
    "count": 2,
    "graphs": [
        {
            "desc": "Airflow",
            "name": "device_airflow"
        },
        {
            "desc": "Voltage",
            "name": "device_voltage"
        }
    ]
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_voltage

Output:

{
    "status": "ok",
    "message": "",
    "count": 2,
    "graphs": [
        {
            "sensor_id": "1",
            "desc": "Input Feed A"
        },
        {
            "sensor_id": "2",
            "desc": "Output Feed"
        }
    ]
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_voltage/1

Output:

{
    "status": "ok",
    "message": "",
    "count": 1,
    "graphs": [
        {
            "sensor_id": "1",
            "sensor_deleted": "0",
            "sensor_class": "voltage",
            "device_id": "1",
            "poller_type": "snmp",
            "sensor_oid": ".1.3.6.1.4.1.318.1.1.27.1.1.0",
            "sensor_index": "1",
            "sensor_type": "apc",
            "sensor_descr": "Input",
            "sensor_divisor": "1",
            "sensor_multiplier": "1",
            "sensor_current": "1",
            "sensor_limit": "1.15",
            "sensor_limit_warn": null,
            "sensor_limit_low": "0.85",
            "sensor_limit_low_warn": null,
            "sensor_alert": "1",
            "sensor_custom": "No",
            "entPhysicalIndex": null,
            "entPhysicalIndex_measured": null,
            "lastupdate": "2017-01-13 13:50:26",
            "sensor_prev": "1"
        }
    ]
}

`list_available_wireless_graphs`

This function allows to do three things:

Get a list of overall wireless graphs available.
Get a list of wireless graphs based on provided class.
Get the wireless sensors information based on ID.

Route: /api/v0/devices/:hostname/wireless(/:type)(/:sensor_id)

hostname can be either the device hostname or id
type (optional) is wireless type / wireless class
sensor_id (optional) is the sensor id to retrieve specific information.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/wireless

Output:

{
    "status": "ok",
    "graphs": [
        {
            "desc": "Ccq",
            "name": "device_wireless_ccq"
        },
        {
            "desc": "Clients",
            "name": "device_wireless_clients"
        }
    ],
    "count": 2
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/wireless/device_wireless_ccq

Output:

{
    "status": "ok",
    "graphs": [
        {
            "sensor_id": "791",
            "desc": "SSID: bast (ng)"
        },
        {
            "sensor_id": "792",
            "desc": "SSID: bast (na)"
        }
    ],
    "count": 2
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_wireless_ccq/1

Output:

{
    "status": "ok",
    "graphs": [
        {
            "sensor_id": "791",
            "sensor_deleted": "0",
            "sensor_class": "ccq",
            "device_id": "381",
            "sensor_index": "0",
            "sensor_type": "unifi",
            "sensor_descr": "SSID: bast (ng)",
            "sensor_divisor": "10",
            "sensor_multiplier": "1",
            "sensor_aggregator": "sum",
            "sensor_current": "100",
            "sensor_prev": "100",
            "sensor_limit": null,
            "sensor_limit_warn": null,
            "sensor_limit_low": null,
            "sensor_limit_low_warn": null,
            "sensor_alert": "1",
            "sensor_custom": "No",
            "entPhysicalIndex": null,
            "entPhysicalIndex_measured": null,
            "lastupdate": "2017-12-06 21:26:29",
            "sensor_oids": "[\".1.3.6.1.4.1.41112.1.6.1.2.1.3.0\"]",
            "access_point_id": null
        }
    ],
    "count": 1
}

`get_health_graph`

Get a particular health class graph for a device, if you provide a sensor_id as well then a single sensor graph will be provided. If no sensor_id value is provided then you will be sent a stacked sensor graph.

Route: /api/v0/devices/:hostname/graphs/health/:type(/:sensor_id)

hostname can be either the device hostname or id
type is the name of the health graph as returned by list_available_health_graphs
sensor_id (optional) restricts the graph to return a particular health sensor graph.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/health/device_voltage

Output:

Output is a stacked graph for the health type provided.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/health/device_voltage/1

Output:

Output is the graph of the particular health type sensor provided.

`get_wireless_graph`

Get a particular wireless class graph for a device, if you provide a sensor_id as well then a single sensor graph will be provided. If no sensor_id value is provided then you will be sent a stacked wireless graph.

Route: /api/v0/devices/:hostname/graphs/wireless/:type(/:sensor_id)

hostname can be either the device hostname or id
type is the name of the wireless graph as returned by list_available_wireless_graphs
sensor_id (optional) restricts the graph to return a particular wireless sensor graph.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/wireless/device_wireless_ccq

Output:

Output is a stacked graph for the wireless type provided.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/wireless/device_wireless_ccq/1

Output:

Output is the graph of the particular wireless type sensor provided.

`get_graph_generic_by_hostname`

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](#function-get_graphs 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.
output: Set how the graph should be outputted (base64, display), defaults to display.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/device_poller_perf

Output:

Output is an image.

`get_graph_by_service`

Get the graph for a service

Route: /api/v0/devices/:hostname/services/:service_id/graphs/:datasource

hostname can be either the device hostname or id
service id
datasource is the name of the service datasource

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 -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/services/localhost/35/graphs/loss

Output:

Output is an image.

`get_port_graphs`

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 -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports

Output:

{
    "status": "ok",
    "message": "",
    "count": 3,
    "ports": [
        {
            "ifName": "lo"
        },
        {
            "ifName": "eth0"
        },
        {
            "ifName": "eth1"
        }
    ]
}

`get_device_fdb`

Get a list of FDB entries associated with a device.

Route: /api/v0/devices/:hostname/fdb

hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/fdb

Output:

{
    "status": "ok",
    "ports_fdb": {
        "ports_fdb_id": 10,
        "port_id": 10000,
        "mac_address": "1aaa2bbb3ccc",
        "vlan_id": 20000,
        "device_id": 1,
        "created_at": "2019-01-1 01:01:01",
        "updated_at": "2019-01-1 01:01:01"
    }
}

`get_device_ip_addresses`

Get a list of IP addresses (v4 and v6) associated with a device.

Route: /api/v0/devices/:hostname/ip

hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ip

Output:

{
    "status": "ok",
    "message": "",
    "addresses": [
        {
          "ipv4_address_id": "290",
          "ipv4_address": "192.168.99.292",
          "ipv4_prefixlen": "30",
          "ipv4_network_id": "247",
          "port_id": "323",
          "context_name": ""
        }
    ]
}

`get_port_stack`

Get a list of port mappings for a device. This is useful for showing physical ports that are in a virtual port-channel.

Route: /api/v0/devices/:hostname/port_stack

hostname can be either the device hostname or id

Input:

valid_mappings: Filter the result by only showing valid mappings ("0" values not shown).

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/port_stack?valid_mappings

Output:

{
  "status": "ok",
  "message": "",
  "count": 2,
  "mappings": [
    {
      "device_id": "3742",
      "port_id_high": "1001000",
      "port_id_low": "51001",
      "ifStackStatus": "active"
    },
    {
      "device_id": "3742",
      "port_id_high": "1001000",
      "port_id_low": "52001",
      "ifStackStatus": "active"
    }
  ]
}

`get_device_transceivers`

Get a list of FDB entries associated with a device.

Route: /api/v0/devices/:hostname/transceivers

hostname can be either the device hostname or id

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/transceivers

Output:

{
    "status": "ok",
    "transceivers": [
        {
            "id": 12,
            "created_at": "2024-06-26T23:46:06.000000Z",
            "updated_at": "2024-06-26T23:46:57.000000Z",
            "device_id": 3138,
            "port_id": 50735,
            "index": "50",
            "type": "10G_BASE_LR_SFP",
            "vendor": "FS",
            "oui": "00 00 00",
            "model": null,
            "revision": "",
            "serial": "G000999AA",
            "date": null,
            "ddm": true,
            "encoding": null,
            "cable": "SM",
            "distance": 20000,
            "wavelength": 1330,
            "connector": "LC",
            "channels": 1
        },
        {
            "id": 13,
            "created_at": "2024-06-26T23:46:06.000000Z",
            "updated_at": "2024-06-27T00:00:07.000000Z",
            "device_id": 3138,
            "port_id": 50736,
            "index": "51",
            "type": "10G_BASE_SR_SFP",
            "vendor": "HPE",
            "oui": "64 9D 99",
            "model": null,
            "revision": "1",
            "serial": "AAAA0000AAA",
            "date": null,
            "ddm": true,
            "encoding": null,
            "cable": "SM",
            "distance": 300,
            "wavelength": 850,
            "connector": "LC",
            "channels": 1
        }
    ]
}

`get_components`

Get a list of components for a particular device.

Route: /api/v0/devices/:hostname/components

hostname can be either the device hostname or id

Input:

type: Filter the result by type (Equals).
id: Filter the result by id (Equals).
label: Filter the result by label (Contains).
status: Filter the result by status (Equals).
disabled: Filter the result by disabled (Equals).
ignore: Filter the result by ignore (Equals).

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components

Output:

{
    "status": "ok",
    "message": "",
    "count": 3,
    "components": {
        "2": {
            "TestAttribute-1": "Value1",
            "TestAttribute-2": "Value2",
            "TestAttribute-3": "Value3",
            "type": "TestComponent-1",
            "label": "This is a really cool blue component",
            "status": "1",
            "ignore": "0",
            "disabled": "0"
        },
        "20": {
            "TestAttribute-1": "Value4",
            "TestAttribute-2": "Value5",
            "TestAttribute-3": "Value6",
            "type": "TestComponent-1",
            "label": "This is a really cool red component",
            "status": "1",
            "ignore": "0",
            "disabled": "0"
        },
        "27": {
            "TestAttribute-1": "Value7",
            "TestAttribute-2": "Value8",
            "TestAttribute-3": "Value9",
            "type": "TestComponent-2",
            "label": "This is a really cool yellow widget",
            "status": "1",
            "ignore": "0",
            "disabled": "0"
        }
    }
}

`add_components`

Create a new component of a type on a particular device.

Route: /api/v0/devices/:hostname/components/:type

hostname can be either the device hostname or id
type is the type of component to add

Example:

curl -X POST -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components/APITEST

Output:

{
    "status": "ok",
    "message": "",
    "count": 1,
    "components": {
        "4459": {
            "type": "APITEST",
            "label": "",
            "status": 1,
            "ignore": 0,
            "disabled": 0,
            "error": ""
        }
    }
}

`edit_components`

Edit an existing component on a particular device.

Route: /api/v0/devices/:hostname/components

hostname can be either the device hostname or id

In this example we set the label and add a new field: TestField:

curl -X PUT -d '{"4459": {"type": "APITEST","label": "This is a test label","status": 1,"ignore": 0,"disabled": 0,"error": "","TestField": "TestData"}}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components

Output:

{
    "status": "ok",
    "message": "",
    "count": 1
}

Just take the JSON array from add_components or edit_components, edit as you wish and submit it back to edit components.

`delete_components`

Delete an existing component on a particular device.

Route: /api/v0/devices/:hostname/components/:component

hostname can be either the device hostname or id
component is the component ID to be deleted.

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/components/4459

Output:

{
    "status": "ok",
    "message": ""
}

`get_port_stats_by_port_hostname`

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. 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 -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports/eth0

Output:

{
 "status": "ok",
 "port": {
  "port_id": "2",
  "device_id": "1",
  ...
  "poll_prev": "1418412902",
  "poll_period": "300"
 }
}

`get_graph_by_port_hostname`

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. 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](#function-get_port graphs).

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.
ifDescr: If this is set to true then we will use ifDescr to lookup the port instead of ifName. Pass the ifDescr value you want to search as you would ifName.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/ports/eth0/port_bits

Output:

Output is an image.

`list_sensors`

Get a list of all Sensors.

Route: /api/v0/resources/sensors

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/resources/sensors

Output:

{
    "status": "ok",
    "sensors": [
        {
            "sensor_id": 218810,
            "sensor_deleted": 0,
            "sensor_class": "dbm",
            "device_id": 136,
            "poller_type": "snmp",
            "sensor_oid": ".1.3.6.1.4.1.2636.3.60.1.1.1.1.7.919",
            "sensor_index": "tx-919",
            "sensor_type": "junos",
            "sensor_descr": "xe-2/1/4 Tx Power",
            "group": null,
            "sensor_divisor": 100,
            "sensor_multiplier": 1,
            "sensor_current": -1.81,
            "sensor_limit": 2,
            "sensor_limit_warn": 0.5,
            "sensor_limit_low": -9.7,
            "sensor_limit_low_warn": -8.21,
            "sensor_alert": 1,
            "sensor_custom": "No",
            "entPhysicalIndex": "919",
            "entPhysicalIndex_measured": "ports",
            "lastupdate": "2019-02-18 02:47:09",
            "sensor_prev": -1.77,
            "user_func": null
        },
        ...
    ],
    "count": 100
}

`list_devices`

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 to filter or search by:
- all: All devices
- active: Only not ignored and not disabled devices
- ignored: Only ignored devices
- up: Only devices that are up
- down: Only devices that are down
- disabled: Disabled devices
- os: search by os type
- mac: search by mac address
- ipv4: search by IPv4 address
- ipv6: search by IPv6 address (compressed or uncompressed)
- location: search by location
- location_id: search by location_id
- hostname: search by hostname
- sysName: search by sysName
- display: search by display name
- device_id: exact match by device-id
- type: search by device type
query: If searching by, then this will be used as the input.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices?order=hostname%20DESC&type=down

Output:

{
 "status": "ok",
 "count": 1,
 "devices": [
  {
   "device_id": "1",
   "hostname": "localhost",
   ...
   "serial": null,
   "icon": null
  }
 ]
}

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices?type=mac&query=00000c9ff013

Output:

{
 "status": "ok",
 "count": 1,
 "devices": [
  {
   "device_id": "1",
   "hostname": "localhost",
   ...
   "serial": null,
   "icon": null
  }
 ]
}

`device_under_maintenance`

Get the current maintenance status of a device.

Route: /api/v0/devices/:hostname/maintenance

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/maintenance

Output:

{
    "status": "ok",
    "is_under_maintenance": true
}

`maintenance_device`

Set a device into maintenance mode.

Route: /api/v0/devices/:hostname/maintenance

Input (JSON):

title: optional - Some title for the Maintenance
Will be replaced with hostname if omitted
notes: optional - Some description for the Maintenance
Will also be added to device notes if user prefs "Add schedule notes to devices notes" is set
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 -H 'X-Auth-Token: YOURAPITOKENHERE' \
  -X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
  --data-raw '
 "title":"Device Maintenance",
  "notes":"A 2 hour Maintenance triggered via API with start time",
  "start":"2022-08-01 08:00:00",
  "duration":"2:00"
}
'

Output:

{
    "status": "ok",
    "message": "Device localhost (1) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
}

Example with no start time:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
  -X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
  --data-raw '
 "title":"Device Maintenance",
  "notes":"A 2 hour Maintenance triggered via API with no start time",
  "duration":"2:00"
}
'

Output:

{
    "status": "ok",
    "message": "Device localhost (1) moved into maintenance mode for 2:00h"
}

`add_device`

Add a new device. Most fields are optional. You may omit snmp credentials to attempt each system credential in order. See snmp.version, snmp.community, and snmp.v3

To guarantee device is added, use force_add. This will skip checks for duplicate device and snmp reachability, but not duplicate hostname.

Route: /api/v0/devices

Input (JSON):

Fields:

hostname (required): device hostname or IP
display: A string to display as the name of this device, defaults to hostname (or device_display_default setting). May be a simple template using replacements: {{ $hostname }}, {{ $sysName }}, {{ $sysName_fallback }}, {{ $ip }}
snmpver: SNMP version to use, v1, v2c or v3. During checks detection order is v2c,v3,v1
port: SNMP port (defaults to port defined in config).
transport: SNMP protocol (udp,tcp,udp6,tcp6) Defaults to transport defined in config.
port_association_mode: method to identify ports: ifIndex (default), ifName, ifDescr, ifAlias
poller_group: This is the poller_group id used for distributed poller setup. Defaults to 0.
location or location_id: set the location by text or location id

Options:

force_add: Skip all checks and attempts to detect credentials. Add the device as given directly to the database.
ping_fallback: if snmp checks fail, add the device as ping only instead of failing

SNMP v1 or v2c credentials:

community: Required for SNMP v1 or v2c.

SNMP v3 credentials:

authlevel: SNMP authlevel (noAuthNoPriv, authNoPriv, authPriv).
authname: SNMP Auth username
authpass: SNMP Auth password
authalgo: SNMP Auth algorithm (MD5, SHA) (SHA-224, SHA-256, SHA-384, SHA-512 if supported by your server)
cryptopass: SNMP Crypto Password
cryptoalgo: SNMP Crypto algorithm (AES, DES)

For ICMP only:

snmp_disable: set to true for ICMP only. Disables SNMP checks and polling.
os: OS short name for the device (defaults to ping).
sysName: sysName for the device.
hardware: Device hardware.

Example:

curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices

Output:

{
    "status": "ok",
    "message": "Device localhost.localdomain (57) has been added successfully",
    "devices": [
        {
            "device_id": "57",
            "hostname": "localhost",
            ...
            "serial": null,
            "icon": null
        }
}

`list_oxidized`

List devices for use with Oxidized. If you have group support enabled then a group will also be returned based on your config.

LibreNMS will automatically map the OS to the Oxidized model name if they don't match.

Route: /api/v0/oxidized(/:hostname)

Input (JSON):

Examples:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized

Output:

[
    {
        "hostname": "localhost",
        "os": "linux"
    },
    {
        "hostname": "otherserver",
        "os": "linux"
    }
]

`update_device_field`

Update devices field in the database.

Route: /api/v0/devices/:hostname

hostname can be either the device hostname or id

Input (JSON):

field: The column name within the database (can be an array of fields)
data: The data to update the column with (can be an array of data))

Examples:

curl -X PATCH -d '{"field": "notes", "data": "This server should be kept online"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

[
    {
        "status": "ok",
        "message": "Device notes has been updated"
    }
]

`update_device_port_notes`

Update a device port notes field in the devices_attrs database.

Route: /api/v0/devices/:hostname/port/:portid

hostname can be either the device hostname or id
portid needs to be the port unique id (int).

Input (JSON):

notes: The string data to populate on the port notes field.

Examples:

curl -X PATCH -d '{"notes": "This port is in a scheduled maintenance with the provider."}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/port/5

Output:

[
    {
        "status": "ok",
        "message": "Port notes field has been updated"
    }
]

curl -X PATCH -d '{"field": ["notes","purpose"], "data": ["This server should be kept online", "For serving web traffic"]}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost

Output:

[
    {
        "status": "ok",
        "message": "Device fields have been updated"
    }
]

`rename_device`

Rename device.

Route: /api/v0/devices/:hostname/rename/:new_hostname

hostname can be either the device hostname or id

Input:

Examples:

curl -X PATCH  -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/rename/localhost2

Output:

[
    {
        "status": "ok",
        "message": "Device has been renamed"
    }
]

`get_device_groups`

List the device groups that a device is matched on.

Route: /api/v0/devices/:hostname/groups

hostname can be either the device hostname or id

Input (JSON):

Examples:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/groups

Output:

[
    {
        "status": "ok",
        "message": "Found 1 device groups",
        "count": 1,
        "groups": [
        {
            "id": "1",
            "name": "Testing",
            "desc": "Testing",
            "pattern": "%devices.status = \"1\" &&"
        }
        ]
    }
]

`search_oxidized`

search all oxidized device configs for a string.

Route: api/v0/oxidized/config/search/:searchstring

searchstring is the specific string you would like to search for.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized/config/search/vlan10

Output:

{
    "status": "ok",
    "nodes": [
        {
            "node": "asr9k.librenms.org",
            "full_name": "cisco\/ASR9K.Librenms.org"
        },
        {
            "node": "ios.Librenms.org",
            "full_name": "cisco\/ios.Librenms.org"
        }
    ],
    "count": 2
}

`get_oxidized_config`

Returns a specific device's config from oxidized.

Route: api/v0/oxidized/config/:hostname

hostname is the Hostname or IP of the device used when adding the device to librenms.

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/oxidized/config/router.corp.com

Output:

{
    "status": "ok",
    "config": "DEVICE CONFIG HERE"
}

`add_parents_to_host`

Add one or more parents to a host.

Route: /api/v0/devices/:device/parents

Input (JSON):

parent_ids: one or more parent ids or hostnames

Example:

curl -X POST -d '{"parent_ids":"15,16,17"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/1/parents

Output:

{
    "status": "ok",
    "message": "Device dependencies have been saved"
}

`delete_parents_from_host`

Deletes some or all the parents from a host.

Route: /api/v0/devices/:device/parents

Input (JSON):

parent_ids: One or more parent ids or hostnames, if not specified deletes all parents from host.

Example:

curl -X DELETE -d '{"parent_ids":"15,16,17"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/1/parents

Output:

{
    "status": "ok",
    "message": "All device dependencies have been removed"
}

`list_parents_of_host`

This is not a seperate API call. Instead, you obtain the list of parents from list_devices. See that entry point for more detailed information.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' 'http://librenms.org/api/v0/devices?type=device_id&query=34'

Output:

{
    "status": "ok",
    "devices": [
        {
            ...
            "dependency_parent_id": "98,99",
            "dependency_parent_hostname": "HOSTNAME1,HOSTNAME2",
            ...
        }
    ],
    "count": 1
}

35 KiB Raw Permalink Blame History

del_device

get_device

discover_device

availability

outages

get_graphs

list_available_health_graphs

list_available_wireless_graphs

get_health_graph

get_wireless_graph

get_graph_generic_by_hostname

get_graph_by_service

get_port_graphs

get_device_fdb

get_device_ip_addresses

get_port_stack

get_device_transceivers

get_components

add_components

edit_components

delete_components

get_port_stats_by_port_hostname

get_graph_by_port_hostname

list_sensors

list_devices

device_under_maintenance

maintenance_device

add_device

list_oxidized

update_device_field

update_device_port_notes

rename_device

get_device_groups

search_oxidized

get_oxidized_config

add_parents_to_host

delete_parents_from_host

list_parents_of_host

35 KiB

Raw Permalink Blame History

`del_device`

`get_device`

`discover_device`

`availability`

`outages`

`get_graphs`

`list_available_health_graphs`

`list_available_wireless_graphs`

`get_health_graph`

`get_wireless_graph`

`get_graph_generic_by_hostname`

`get_graph_by_service`

`get_port_graphs`

`get_device_fdb`

`get_device_ip_addresses`

`get_port_stack`

`get_device_transceivers`

`get_components`

`add_components`

`edit_components`

`delete_components`

`get_port_stats_by_port_hostname`

`get_graph_by_port_hostname`

`list_sensors`

`list_devices`

`device_under_maintenance`

`maintenance_device`

`add_device`

`list_oxidized`

`update_device_field`

`update_device_port_notes`

`rename_device`

`get_device_groups`

`search_oxidized`

`get_oxidized_config`

`add_parents_to_host`

`delete_parents_from_host`

`list_parents_of_host`