ferrix/docs/content/docs/reference/http-api.md

+++ title = "HTTP API Reference" description = "Describes the endpoints of the Ferrix HTTP interface: the JSON API, the event stream, the status page, and the metrics endpoint." weight = 3

[extra] nav = "HTTP API" +++

Ferrix serves its HTTP interface on the address configured with http_endpoint. All endpoints are read-only and use the GET method.

An error response has a text/plain body that describes the error. The server returns the following error statuses:

Status	Meaning
400 (Bad Request)	A query parameter is invalid.
500 (Internal Server Error)	The server could not produce the response, for example because the metrics could not be encoded.
503 (Service Unavailable)	A table is unavailable because the daemon is shutting down.

Caution

The HTTP interface does not require authentication. Bind it to a loopback address, or place it behind a reverse proxy that requires authentication.

Endpoints

Endpoint	Description
/	Redirects to /statusz.
/statusz	Status page.
/api/status	Router ID, AS number, uptime, table sizes, memory use (memory, as jemalloc accounts for it: allocated, active, metadata, resident, mapped, retained octets), and whether control communities are enabled (control_communities).
/api/config	The configuration that was read at startup.
/api/peers	Configured neighbors and their sessions.
/api/routes/local	Originated routes.
/api/routes/received	Received routes.
/api/routes/rejected	Rejected routes, by neighbor.
/api/rpki	RPKI cache, data, and data age.
/api/kernel	Kernel route installation state and interfaces.
/api/tcp	The TCP connection of one session, as the kernel reports it.
/api/events	Session and route changes, as server-sent events.
/metricz	Prometheus metrics. See Metrics Reference.

Peers

/api/peers returns an array with one object for each configured neighbor:

{
  "name": "test-peer",
  "peer_addr": "127.0.0.1:64815",
  "peer_asn": 65001,
  "state": "Established",
  "direction": "inbound",
  "local_addr": "127.0.0.1:1790",
  "uptime_secs": 2,
  "four_octet_asn": true,
  "extended_next_hop": false,
  "address_families": ["IPv4 unicast", "IPv6 unicast"],
  "add_path_receive": [],
  "add_path_send": [],
  "routes": 1,
  "rejected_routes": 1,
  "advertised_routes": 2,
  "held_routes": 0,
  "expected_routes": null,
  "role": null,
  "role_confirmed": null,
  "last_error": null,
  "retry_at_unix": null,
  "graceful_restart": {
    "restart_time_secs": 120,
    "notification": true,
    "address_families": ["IPv4 unicast", "IPv6 unicast"],
    "forwarding_preserved": ["IPv4 unicast", "IPv6 unicast"]
  },
  "stale_routes": null,
  "stale_until_unix": null
}

Field	Description
state	Session state: Established, Connecting, Backoff, Idle, or Passive (a passive neighbor that has no session).
direction	inbound if the neighbor initiated the connection, outbound otherwise.
routes	Number of the neighbor's routes in the routing table.
rejected_routes	Number of the neighbor's routes rejected by its import policy.
advertised_routes	Number of routes advertised to the neighbor and not withdrawn since. With ADD-PATH and all_paths, every route advertised counts.
held_routes	Number of held routes: routes rejected for a reason that can change without a new UPDATE, such as RPKI validity or next hop resolution.
expected_routes	The expected_routes value from the configuration, or null if it is not set.
role_confirmed	Whether the neighbor advertised a BGP role that matches the configured role.
retry_at_unix	For a neighbor without a session, the time of the next connection attempt.
graceful_restart	Graceful restart, if both neighbors advertised it: the restart time of the neighbor, whether the N bit is in use (RFC 8538), the address families whose routes are retained, and those for which the neighbor preserved its forwarding state.
stale_routes	Number of the neighbor's routes retained from its previous session and not yet advertised again, or null if there are none.
stale_until_unix	For a restarting neighbor without a session, the time at which its retained routes are removed.

Received Routes

/api/routes/received returns received routes, one page at a time. Table 1 lists the query parameters.

Parameter	Description
prefix	Returns all routes for the prefix, in order of path selection. Example: prefix=193.0.0.0/21.
address	Returns all routes for the prefixes that contain the address, most specific first. Example: address=193.0.0.1.
within	Returns the routes for the prefix and all more specific prefixes. Example: within=193.0.0.0/16.
peer	Returns only routes from the neighbor, identified by name or address.
origin	Returns only routes originated by the AS: the last AS of the AS path. The value is a number, with or without the prefix AS. Routes with an empty AS path are originated by the local AS. Example: origin=AS64496.
best	If true, returns only the best path for each prefix.
limit	Specifies the approximate number of routes in a page. Default: 1000. Maximum: 100000.
after	Returns the page after the specified prefix. Use the next_after value of the previous page.
before	Returns the page before the specified prefix. Use the prev_before value of the next page.

A page contains only complete prefixes. It ends before the prefix whose routes would exceed limit, but always contains at least one prefix. Prefixes are sorted by address, with IPv4 prefixes first.

{
  "routes": [{
    "peer_name": "test-peer",
    "peer_addr": "127.0.0.1:64815",
    "peer_asn": 65001,
    "prefix": "203.0.113.0/24",
    "path_id": 0,
    "best": true,
    "rank": 1,
    "stale": false,
    "rpki": null,
    "aspa": null,
    "summary": {
      "origin": "IGP",
      "as_path": [65001],
      "next_hop": "10.0.0.2",
      "med": null,
      "local_pref": null,
      "communities": ["65001:1"],
      "large_communities": [],
      "other": [{ "name": "aggregator", "value": "AS65001 10.0.0.2" }]
    },
    "attributes": [ ... ]
  }],
  "next_after": null,
  "prev_before": null
}

Field	Description
path_id	ADD-PATH path identifier, or 0.
best	Whether the route is the best path for the prefix.
rank	The position of the route in path selection for the prefix: 1 for the best path, 2 for the path that would be selected if the best path were withdrawn, and so on.
stale	Whether the route is retained from a previous session of the neighbor and has not been advertised again (graceful restart).
rpki, aspa	Route origin validation and ASPA verification state, if RPKI validation is configured.
summary	The path attributes as text. other lists, in received order, the attributes that have no field of their own: atomic aggregate, aggregator, extended communities, AS4_PATH, only to customer, originator ID, cluster list, and unrecognized attributes.
attributes	All path attributes, as received.

Rejected Routes

/api/routes/rejected returns, for each neighbor with rejected routes, the number of rejected routes for each reason and the 200 most recent rejected routes. To return the records for one neighbor, add ?peer=NAME.

[{
  "peer": "test-peer",
  "peer_addr": "127.0.0.1",
  "total": 1,
  "by_reason": { "own AS in path": 1 },
  "recent": [{
    "prefix": "198.51.100.0/24",
    "path_id": 0,
    "reason": "own AS in path",
    "as_path": [65001, 64500],
    "at_unix": 1791020702,
    "summary": {
      "origin": "IGP",
      "as_path": [65001, 64500],
      "next_hop": "10.0.0.2",
      "med": null,
      "local_pref": null,
      "communities": [],
      "large_communities": [],
      "other": []
    },
    "attributes": [
      { "Origin": 0 },
      { "AsPath": { "segments": [{ "ordered": true, "path": [65001, 64500] }] } },
      { "NextHop": "10.0.0.2" }
    ]
  }]
}]

Field	Description
summary, attributes	The path attributes of the rejected route, in the same format as for received routes. For a route rejected when RPKI data changed, the attributes as stored, including those added by the import policy.

Kernel

/api/kernel returns the state of kernel route installation:

{
  "enabled": true,
  "table": 254,
  "metric": 20,
  "synced": true,
  "installed": 0,
  "kept": 0,
  "blackholes": 0,
  "unresolved": {},
  "refused": 0,
  "errors": 0,
  "last_error": null,
  "interfaces": [
    { "name": "eth0", "index": 2, "up": true,
      "addresses": ["192.168.5.15/24", "fe80::5055:55ff:fed4:2526/64"] }
  ]
}

Field	Description
synced	Whether the kernel routing table has been synchronized with the routing table since the daemon started.
installed	Number of routes installed.
kept	Number of routes from a previous run that are retained during startup.
blackholes	Number of installed routes that are blackhole routes, which discard traffic for their prefix (RFC 7999).
unresolved	Number of prefixes whose active route is not installed, by reason.
refused	Number of prefixes whose active route the kernel rejected.
errors	Number of requests that the kernel rejected.

TCP Connection

/api/tcp?peer=ADDRESS returns what the kernel reports about the TCP connection of the session with the neighbor at ADDRESS, given as peer_addr in /api/peers shows it: the round-trip time, the congestion and receive windows, the queues, the retransmissions, and how long the connection has been held up by the neighbor's receive window or by the local send buffer. Linux only; on other systems, and for a session the kernel has no connection for, available is false and reason says why.

{
  "available": true,
  "reason": null,
  "connection": {
    "state": "established",
    "congestion": "cubic",
    "rtt_ms": 0.62,
    "rtt_variance_ms": 0.11,
    "min_rtt_ms": 0.4,
    "rto_ms": 201,
    "mss": 1428,
    "pmtu": 1500,
    "cwnd_segments": 10,
    "ssthresh_segments": null,
    "send_window": 1048576,
    "receive_window": 3145728,
    "receive_space": 65536,
    "send_window_scale": 7,
    "receive_window_scale": 10,
    "send_queue": 0,
    "not_sent": 0,
    "recv_queue": 0,
    "unacked_segments": 0,
    "retrans_segments": 0,
    "lost_segments": 0,
    "total_retrans": 0,
    "bytes_retrans": 0,
    "pacing_rate": 2309920000,
    "delivery_rate": 184860000,
    "bytes_sent": 312993,
    "bytes_acked": 312994,
    "bytes_received": 190,
    "segments_out": 230,
    "segments_in": 118,
    "busy_ms": 41,
    "limited_by_receive_window_ms": 0,
    "limited_by_send_buffer_ms": 0,
    "limited_by_receive_window_share": 0,
    "limited_by_send_buffer_share": 0,
    "last_data_sent_ms": 1234,
    "last_data_received_ms": 1300,
    "last_ack_received_ms": 1234
  }
}

Times are in milliseconds, sizes in octets, rates in octets per second. send_window is the neighbor's receive window, which bounds what Ferrix can send; receive_window is what Ferrix lets the neighbor send. The two _share values are the fractions of the busy time, 0 to 1, in which the connection was held up by the neighbor's window and by the local send buffer. A session that advertises a table to a neighbor that reads it slowly shows a high limited_by_receive_window_share. The status page shows the same information under the tcp link of each established session.

Events

/api/events is a stream of server-sent events. Each event has the name bgp and contains a JSON object. The type field identifies the event, as listed in Table 2.

type	Description
session_up	A session was established. The peer field has the format of /api/peers.
session_down	A session ended. Fields: peer_addr, peer_asn.
route_refresh_requested	A neighbor sent a ROUTE-REFRESH message.
local_announced, local_withdrawn	An originated route was advertised or withdrawn.
best_changed	The best path for a prefix changed. The route field contains the new best path.
best_withdrawn	A prefix no longer has a route.
lagged	The client did not read events quickly enough and missed events on stream. Reload the corresponding table. The missed field gives the number of missed events for the sessions and local_routes streams; the best_routes stream omits it because the number is not known.

The following command displays the event stream:

curl -sN 127.0.0.1:8080/api/events