clones/librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-09-23 03:18:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
62b4c21a12
librenms/doc/API/API-Docs.md
laf 62b4c21a12 Added API calls for device groups
2015-12-12 12:58:07 +00:00

26 KiB
Raw Blame History

Structure top

Versioning top

Versioning an API is a minefield which saw us looking at numerous options on how to do this. Paul wrote an excellent blog post which touches on this: http://blog.librenms.org/2014/09/restful-apis/

We have currently settled on using versioning within the API end point itself /api/v0. As the API itself is new and still in active development we also decided that v0 would be the best starting point to indicate it's in development.

Tokens top

To access any of the token end points you will be required to authenticate using a token. Tokens can be created directly from within the LibreNMS web interface by going to /api-access/.

  • Click on 'Create API access token'.
  • Select the user you would like to generate the token for.
  • Enter an optional description.
  • Click Create API Token.

Endpoints top

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

Output
{
 "list_bgp": "https://librenms.org/api/v0/bgp",
  ...
 "edit_rule": "https://librenms.org/api/v0/rules"
}

Input top

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 -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}'-H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices

Output top

Output from the API currently is via two output types.

  • JSON Most API responses will output json. As show in the example for calling the API endpoint.
  • PNG This is for when the request is for an image such as a graph for a switch port.

Endpoints top

Devices top

Function: del_device top

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
        }
    ]
}

Function: get_device top

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
        }
    ]
}

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

Output:

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

Function: get_graph_generic_by_hostname top

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 to see the graphs available. Defaults to device_uptime.

Input:

Example:

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

Output:

Output is an image.

Function: get_port_graphs top

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",
    "err-msg": "",
    "count": 3,
    "ports": [
        {
            "ifName": "lo"
        },
        {
            "ifName": "eth0"
        },
        {
            "ifName": "eth1"
        }
    ]
}

Function: get_port_stats_by_port_hostname 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. 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"
 }
}

Function: get_graph_by_port_hostname 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. 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.

Input:

Example:

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

Output:

Output is an image.

Function: list_devices top

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
    • ignored: Only ignored devices
    • up: Only devices that are up
    • down: Only devices that are down
    • disabled: Disabled devices
    • mac: search by mac address
    • ipv4: search by IPv4 address
    • ipv6: search by IPv6 address (compressed or uncompressed)
  • 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
  }
 ]
}

Function: add_device 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.
  • poller_group: This is the poller_group id used for distributed poller setup. Defaults to 0.
  • force_add: Force the device to be added regardless of it being able to respond to snmp or icmp.

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 -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 has been added successfully"
}

Function: list_oxidized top

List devices for use with Oxidized.

Route: /api/v0/oxidized

Input (JSON):

Examples:

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

Output:

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

Function: update_device_field top

Update devices field in the database.

Route: /api/v0/devices/:hostname

Input (JSON):

  • field: The column name within the database
  • data: The data to update the column with

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"
    }
]

Function get_device_groups top

List the device groups that a device is matched on.

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

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\" &&"
        }
        ]
    }
]

Device Groups top

Function get_devicegroups top

List all device groups.

Route: /api/v0/devicegroups

Input (JSON):

Examples:

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

Output:

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

Routing top

Function: list_bgp top

List the current BGP sessions.

Route: /api/v0/bgp

Input:

  • hostname = either the devices hostname or id.

Example:

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

Output:

{
 "status": "ok",
 "err-msg": "",
 "count": 0,
 "bgp_sessions": [

 ]
}

Switching top

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

Output:

{
    "status": "ok",
    "count": 0,
    "vlans": [
    {
   "vlan_vlan": "1",
   "vlan_domain": "1",
   "vlan_name": "default",
   "vlan_type": "ethernet",
   "vlan_mtu": null
    }
  ]
}

Alerts top

Function: get_alert 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.

Input:

Example:

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

Output:

{
 "status": "ok",
 "err-msg": "",
 "count": 7,
 "alerts": [
  {
   "hostname": "localhost",
   "id": "1",
   "device_id": "1",
   "rule_id": "1",
   "state": "1",
   "alerted": "1",
   "open": "1",
   "timestamp": "2014-12-11 14:40:02"
  },
}

Function: ack_alert top

Acknowledge an alert

Route: /api/v0/alerts/:id

  • id is the alert id, you can obtain a list of alert ids from list_alerts.

Input:

Example:

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

Output:

{
 "status": "ok",
 "err-msg": "",
 "message": "Alert has been ackgnowledged"
}

Function: unmute_alert top

Unmute an alert

Route: /api/v0/alerts/unmute/:id

  • id is the alert id, you can obtain a list of alert ids from list_alerts.

Input:

Example:

curl -X PUT -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/alerts/unmute/1

Output:

{
 "status": "ok",
 "err-msg": "",
 "message": "Alert has been unmuted"
}

Function: list_alerts top

List all alerts

Route: /api/v0/alerts

Input:

  • state: Filter the alerts by state, 0 = ok, 1 = alert, 2 = ack

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/alerts?state=1

Output:

{
 "status": "ok",
 "err-msg": "",
 "count": 1,
 "alerts": [
  {
   "id": "1",
   "device_id": "1",
   "rule_id": "1",
   "state": "1",
   "alerted": "1",
   "open": "1",
   "timestamp": "2014-12-11 14:40:02"
  }
}

Rules top

Function: get_alert_rule top

Get the alert rule details.

Route: /api/v0/rules/:id

  • id is the rule id.

Input:

Example:

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

Output:

{
 "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,\"invert\":false}",
   "disabled": "0",
   "name": "A test rule"
  }
 ]
}

Function: delete_rule top

Delete an alert rule by id

Route: /api/v0/rules/:id

  • id is the rule id.

Input:

Example:

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

Output:

{
 "status": "ok",
 "err-msg": "",
 "message": "Alert rule has been removed"
}

Function: list_alert_rules top

List the alert rules.

Route: /api/v0/rules

Input:

Example:

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

Output:

{
 "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\",\"invert\":false}",
   "disabled": "0",
   "name": "A test rule"
  },
}

Function: add_rule 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).
  • invert: This would invert the rules check.
  • name: This is the name of the rule and is mandatory.

Example:

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:

rules
{
 "status": "ok",
 "err-msg": ""
}

Function: edit_rule 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).
  • invert: This would invert the rules check.
  • name: This is the name of the rule and is mandatory.

Example:

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:

rules
{
 "status": "ok",
 "err-msg": ""
}

Inventory top

Function: get_inventory top

Retrieve the inventory for a device. If you call this without any parameters then you will only get part of the inventory. This is because a lot of devices nest each component, for instance you may initially have the chassis, within this the ports - 1 being an sfp cage, then the sfp itself. The way this API call is designed is to enable a recursive lookup. The first call will retrieve the root entry, included within this response will be entPhysicalIndex, you can then call for entPhysicalContainedIn which will then return the next layer of results.

Route: /api/v0/inventory/:hostname

  • hostname can be either the device hostname or the device id

Input:

  • entPhysicalClass: This is used to restrict the class of the inventory, for example you can specify chassis to only return items in the inventory that are labelled as chassis.
  • entPhysicalContainedIn: This is used to retrieve items within the inventory assigned to a previous component, for example specifying the chassis (entPhysicalIndex) will retrieve all items where the chassis is the parent.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/inventory/localhost?entPhysicalContainedIn=65536

Output:

{
    "status": "ok",
    "err-msg": "",
    "count": 1,
    "inventory": [
        {
            "entPhysical_id": "2",
            "device_id": "32",
            "entPhysicalIndex": "262145",
            "entPhysicalDescr": "Linux 3.3.5 ehci_hcd RB400 EHCI",
            "entPhysicalClass": "unknown",
            "entPhysicalName": "1:1",
            "entPhysicalHardwareRev": "",
            "entPhysicalFirmwareRev": "",
            "entPhysicalSoftwareRev": "",
            "entPhysicalAlias": "",
            "entPhysicalAssetID": "",
            "entPhysicalIsFRU": "false",
            "entPhysicalModelName": "0x0002",
            "entPhysicalVendorType": "zeroDotZero",
            "entPhysicalSerialNum": "rb400_usb",
            "entPhysicalContainedIn": "65536",
            "entPhysicalParentRelPos": "-1",
            "entPhysicalMfgName": "0x1d6b",
            "ifIndex": "0"
        }
    ]
}

Bills top

Function: list_bills top

Retrieve the list of bills currently in the system.

Route: /api/v0/bills

Input:

Example:

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

Output:

{
 "status": "ok",
 "err-msg": "",
 "count": 1,
 "bills": [
  {
   "bill_id": "1",
   "bill_name": "Router bills",
   "bill_type": "cdr",
   "bill_cdr": "10000000",
   "bill_day": "1",
   "bill_quota": "0",
   "rate_95th_in": "0",
   "rate_95th_out": "0",
   "rate_95th": "0",
   "dir_95th": "in",
   "total_data": "0",
   "total_data_in": "0",
   "total_data_out": "0",
   "rate_average_in": "0",
   "rate_average_out": "0",
   "rate_average": "0",
   "bill_last_calc": "2015-07-02 17:01:26",
   "bill_custid": "Router",
   "bill_ref": "Router",
   "bill_notes": "Bill me",
   "bill_autoadded": "0",
   "ports_total": "0",
   "allowed": "10Mbps",
   "used": "0bps",
   "percent": 0,
   "overuse": "-"
  }
 ]
}

Function: get_bill top

Retrieve a specific bill

Route: /api/v0/bills/:id /api/v0/bills?ref=:ref /api/v0/bills?custid=:custid

  • id is the specific bill id
  • ref is the billing reference
  • custid is the customer reference

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?ref=:customerref
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?custid=:custid

Output:

{
 "status": "ok",
 "err-msg": "",
 "count": 1,
 "bills": [
  {
   "bill_id": "1",
   "bill_name": "Router bills",
   "bill_type": "cdr",
   "bill_cdr": "10000000",
   "bill_day": "1",
   "bill_quota": "0",
   "rate_95th_in": "0",
   "rate_95th_out": "0",
   "rate_95th": "0",
   "dir_95th": "in",
   "total_data": "0",
   "total_data_in": "0",
   "total_data_out": "0",
   "rate_average_in": "0",
   "rate_average_out": "0",
   "rate_average": "0",
   "bill_last_calc": "2015-07-02 17:01:26",
   "bill_custid": "Router",
   "bill_ref": "Router",
   "bill_notes": "Bill me",
   "bill_autoadded": "0",
   "ports_total": "0",
   "allowed": "10Mbps",
   "used": "0bps",
   "percent": 0,
   "overuse": "-"
  }
 ]
}