Appendix D: Monitoring via the REST API

The Routing Suite Daemon supports a REST API to allow remote monitoring of the Router. The REST API is accessed over HTTP and delivers a JSON payload. The JSON payload is identical to the payload delivered when the local API is called. The REST API is Read-Only so a connecting client can only query state in the Router, never change it.

Local Connection within a Router

Here we are on router R01 and we use the Routing Suite Client to retrieve local state within R01. The JSON is delivered via a local Unix Domain Socket.

flock@R01:~$ flockrsc ribv4 --prefix
{"ip_net":"0.0.0.0/0","origin":"Kernel","next_hops":[{"intf_id":5,"ip_addr":"192.168.122.1"}]}
{"ip_net":"10.0.1.0/24","origin":"Kernel","next_hops":[{"intf_id":2}]}
{"ip_net":"10.0.2.0/24","origin":"Ospfv2","next_hops":[{"intf_id":2,"ip_addr":"10.0.1.246"}]}
{"ip_net":"10.0.3.0/24","origin":"Kernel","next_hops":[{"intf_id":4}]}
{"ip_net":"10.0.4.0/24","origin":"Kernel","next_hops":[{"intf_id":3}]}

Remote Connection from one Router to another

From R01 we can view information on another router using the REST API. The JSON is delivered via HTTP. The command is the same, except we append the host name / IP Address of the target router.

flock@R01:~$ flockrsc ribv4 --prefix --host R02
{"ip_net":"0.0.0.0/0","origin":"Ospfv2","next_hops":[{"intf_id":2,"ip_addr":"10.0.1.168"}]}
{"ip_net":"10.0.1.0/24","origin":"Kernel","next_hops":[{"intf_id":2}]}
{"ip_net":"10.0.2.0/24","origin":"Kernel","next_hops":[{"intf_id":3}]}
{"ip_net":"10.0.3.0/24","origin":"Kernel","next_hops":[{"intf_id":4}]}
{"ip_net":"10.0.4.0/24","origin":"Ospfv2","next_hops":[{"intf_id":2,"ip_addr":"10.0.1.168"}]}

Remote Connection from Host to any Router

Lets move to a host H01 that is connected to the network. We can install only the Routing Suite Client, and we can monitor all routers, without running the Routing Suite Daemon. NB: This is the flockrsc package being installed, which only includes the Client, not the flockrsd package which includes the Client and the Daemon.

flock@H01# dpkg -i flockrsc_20.0.x_amd64.deb
flock@H01:~$ flockrsc ribv4 --prefix --host R01
{"ip_net":"0.0.0.0/0","origin":"Kernel","next_hops":[{"intf_id":5,"ip_addr":"192.168.122.1"}]}
...
flock@H01:~$ flockrsc ribv4 --prefix --host R02
{"ip_net":"0.0.0.0/0","origin":"Ospfv2","next_hops":[{"intf_id":2,"ip_addr":"10.0.1.168"}]}
...

Remote Connection your way

Since the REST API is simply a JSON payload inside HTTP, there are many ways to connect. The Host Operating System can be your choice of Linux, Windows, Mac, Redox, etc. The HTTP client application can be any one that the Operating System supports. For instance, the venerable curl will run on all the above Operating Systems.

To use curl you just need to know the URL to connect to. If you run the Flock Client with the --show-url option, then the URL associated with that command will be displayed rather than connected to.

flock@H01:~$ flockrsc ribv4 --prefix --host R01 --show-url
REST API URL would be 'http://R01:8000/ribv4/prefix'

you@your-host:~$ curl -s -X GET "http://R01:8000/ribv4/prefix"
{"ip_net":"0.0.0.0/0","origin":"Kernel","next_hops":[{"intf_id":5,"ip_addr":"192.168.122.1"}]}
...

You can then use the language of your choice to consume and manipulate the JSON information. When feeding into a program we want vanilla JSON (rather than the default of JSON with extra line breaks), so we include the --json option to discover the URL.

flock@H01:~$ flockrsc ribv4 --prefix --json --host R01 --show-url
REST API URL would be 'http://R01:8000/ribv4/prefix/json'

you@your-host:~$ curl -s -X GET "http://R01:8000/ribv4/prefix/json" | python -m json.tool
[
    {
        "ip_net": "0.0.0.0/0",
        "next_hops": [
            {
                "intf_id": 5,
                "ip_addr": "192.168.122.1"
            }
        ],
        "origin": "Kernel"
    },
...

Example: Connecting to the REST API using Python

flock@H01:~$ flockrsc ribv4 -p --host r02 --json --show-url
REST API URL would be 'http://r02:8000/ribv4/prefix/json'

you@your-host:~$ python3
Python 3.7.3 (default, Apr  3 2019, 05:39:12)
[GCC 8.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests
>>> r = requests.get('http://r02:8000/ribv4/prefix/json')
>>> r.json()
[{'ip_net': '0.0.0.0/0', 'origin': 'Ospfv2', 'next_hops': [{'intf_id': 2, 'ip_addr': '10.0.1.168'}, {'intf_id': 4, 'ip_addr': '10.0.3.176'}]}, {'ip_net': '10.0.1.0/24', 'origin': 'Kernel', 'next_hops': [{'intf_id': 2}]}, {'ip_net': '192.168.122.0/24', 'origin': 'Ospfv2', 'next_hops': [{'intf_id': 2, 'ip_addr': '10.0.1.168'}, {'intf_id': 4, 'ip_addr': '10.0.3.176'}]}]

Commonly used REST API URLs

As discussed above the available REST API URL's can be discovered using the Routing Suite Client --show-url option. The URL's mirror the Routing Suite Client long options, for example:

flockrsc ribv4 --prefix maps to the URL /ribv4/prefix

For convenience some commonly used URL's are listed below.

/system
/system/intf
/ospfv2
/ospfv2/lsdb
/ospfv2/prefix-network
/ospfv2/prefix-router
/ospfv2/area?area_id=0.0.0.0
/ospfv2/area?area_id=0.0.0.0/lsdb
/ospfv2/area?area_id=0/intf
/ospfv2/area?area_id=0/intf/neigh
/ribv4
/ribv4/prefix

Append /json if you want vanilla JSON (no extra line breaks)

/ribv4/prefix/json

Append /json-pretty if you want JSON pretty printed

/ribv4/prefix/json-pretty

User Guide: Flock Networks Routing Suite 20.0 [Copyright 2020]