Appendix: Use case Scenario and Examples for RBFS REST APIs
CtrlD API: Use Cases and Examples
A single CtrlD instance can serve multiple RBFS containers. Each container forms a network element and has a unique name which is the 'element name'.
All API calls (requests) to an RBFS container contain the element name in the URL path.
| BNG is used as the element name in the following examples. NOTE: 10.0.0.1 is used as the management IP address in the following examples. |
Rebooting a Switch
This example shows how to reboot the switch.
Rebooting a switch is an example of an asynchronous operation.
The API call returns the acknowledgment immediately that the reboot request has been accepted (HTTP Status Code 202).
The following list shows the HTTP request to reboot switch 10.0.0.1. The URL contains no element name because the entire switch will be rebooted.
POST /api/v1/ctrld/system/_reboot HTTP/1.1
Host: 10.0.0.1:19091Triggering a Software Upgrade
A software upgrade can be performed by executing the Zero-Touch Provisioning (ZTP) process again. The switch will be rebooted in Open Network Install Environment (ONIE) update mode and allow ONIE to discover the OS installer image and startup configuration files from the ZTP server.
Rebooting a switch is an example of asynchronous operation.
The API call returns a response immediately that the reboot request has been accepted (HTTP Status Code 202).
The following example shows the HTTP request to reboot switch 10.0.0.1. The URL contains no element name because the entire switch will be rebooted.
POST /api/v1/ctrld/system/_update HTTP/1.1
Host: 10.0.0.1:19091Using the Proxy Endpoint
The CtrlD proxy endpoint forwards API calls to the daemons hosting the API in the RBFS container. Three daemons host publicly available APIs:
-
opsd, the operational state daemon, hosts the Operational State API. -
restconfd, the RESTCONF daemon, hosts the RESTCONF API. -
Prometheus hosts the Prometheus API.
| All examples in the following sections use the CtrlD proxy endpoint. |
The following table summarizes the proxy endpoint paths for the daemons: opsd, restconfd, and Prometheus and an element named BNG.
| Daemon | Path |
|---|---|
Operational State Daemon (opsd) |
|
RESTCONF Daemon (restcondf) |
|
Prometheus |
|
RESTCONF API: Use Cases and Examples
Reading the Current Configuration
The following request returns the complete switch configuration.
GET /api/v1/rbfs/elements/BNG/services/restconfd/proxy/restconf/data HTTP/1.1
Host: 10.0.0.1:19091Reading the Time-series Settings
The RESTCONF Protocol RFC describes a comprehensive query syntax, which allows retrieving certain parts of the configuration.
The following API call retrieves all the time-series settings.
GET /api/v1/rbfs/elements/BNG/services/restconfd/proxy/restconf/data/rtbrick-config:time-series HTTP/1.1
Host: 10.0.0.1:19091{
"rtbrick-config:time-series": {
"metric": [
{
"name": "subscriber_sessions",
"table-name": "local.access.subscriber.count",
"bds-type": "object-metric",
"prometheus-type": "gauge",
"description": "Established subscriber sessions",
"attribute": [
{
"attribute-name": "ipoe_established",
"label": [
{
"label-key": "access_type",
"label-value": "ipoe",
"label-type": "static"
},
{
"label-key": "ifp_name",
"label-value": "ifp_name",
"label-type": "dynamic"
}
]
}
]
},
{
"name": "total_cpu_util_percent",
"table-name": "global.chassis_0.resource.cpu_usage",
"bds-type": "object-metric",
"prometheus-type": "gauge",
"description": "Total CPU utilization in percent",
"attribute": [
{
"attribute-name": "total_cpu",
"label": [
{
"label-key": "cpu",
"label-value": "cpu_id",
"label-type": "dynamic"
}
]
}
]
},
{
"name": "total_memory_free_kilobyte",
"table-name": "global.chassis_0.resource.mem_usage",
"bds-type": "object-metric",
"prometheus-type": "gauge",
"description": "Total free RAM memory in kilo bytes",
"attribute": [
{
"attribute-name": "free_mem",
"label": [
{
"label-key": "memory",
"label-value": "mem_id",
"label-type": "dynamic"
}
]
}
]
},
{
"name": "total_memory_used_kilobyte",
"table-name": "global.chassis_0.resource.mem_usage",
"bds-type": "object-metric",
"prometheus-type": "gauge",
"description": "Total used RAM memory in kilo bytes",
"attribute": [
{
"attribute-name": "used_mem",
"label": [
{
"label-key": "memory",
"label-value": "mem_id",
"label-type": "dynamic"
}
]
}
]
}
]
}
}RESTCONF also allows filtering for a specific time series.
GET /api/v1/rbfs/elements/BNG/services/restconfd/proxy/restconf/data/rtbrick-config:time-series/metric=subscriber_sessions HTTP/1.1
Host: 10.0.0.1:19091{
"rtbrick-config:metric": [
{
"name": "subscriber_sessions",
"table-name": "local.access.subscriber.count",
"bds-type": "object-metric",
"prometheus-type": "gauge",
"description": "Established subscriber sessions",
"attribute": [
{
"attribute-name": "ipoe_established",
"label": [
{
"label-key": "access_type",
"label-value": "ipoe",
"label-type": "static"
},
{
"label-key": "ifp_name",
"label-value": "ifp_name",
"label-type": "dynamic"
}
]
}
]
}
]
}In addition, RESTCONF allows querying the key values. The following API call selects the names of the configured time-series metrics.
GET /api/v1/rbfs/elements/BNG/services/restconfd/proxy/restconf/data/rtbrick-config:time-series/metric=/name HTTP/1.1
Host: 10.0.0.1:19091{
"rtbrick-config:name": [
"subscriber_sessions",
"total_cpu_util_percent",
"total_memory_free_kilobyte",
"total_memory_used_kilobyte"
]
}Adding a New Time-series
The RESTCONF API also allows replacing and adding new configurations to an existing configuration. The data is exchanged in JSON format.
The Content-Type header must be set to application/yang-data+json.
|
YANG is a modeling language that is used to describe the configurations. The RESTCONF Open API definition is generated from the YANG models and contains a reference to the respective YANG model.
The following API request adds a new default_bgp_prefixes_count time-series to the RBFS configuration.
PUT /api/v1/rbfs/elements/BNG/services/restconfd/proxy/restconf/data/rtbrick-config:time-series/metric=default_bgp_prefixes_count HTTP/1.1
Host: 10.0.0.1:19091
Content-Type: application/yang-data+json
Content-Length: 4315
{
"rtbrick-config:metric": [
{
"name": "default_bgp_prefixes_count",
"table-name": "default.bgp.peer",
"bds-type": "object-metric",
"prometheus-type": "gauge",
"description": "BGP peerings default instance",
"attribute": [
{
"attribute-name": "ipv4_unicast_update_rcvd_cnt",
"label": [
{
"label-key": "afi",
"label-value": "ipv4",
"label-type": "static"
},
{
"label-key": "direction",
"label-value": "in",
"label-type": "static"
},
{
"label-key": "peer",
"label-value": "peer_ipv4_address",
"label-type": "dynamic"
},
{
"label-key": "safi",
"label-value": "unicast",
"label-type": "static"
}
]
},
{
"attribute-name": "ipv4_unicast_update_sent_cnt",
"label": [
{
"label-key": "afi",
"label-value": "ipv4",
"label-type": "static"
},
{
"label-key": "direction",
"label-value": "out",
"label-type": "static"
},
{
"label-key": "peer",
"label-value": "peer_ipv4_address",
"label-type": "dynamic"
},
{
"label-key": "safi",
"label-value": "unicast",
"label-type": "static"
}
]
},
{
"attribute-name": "ipv6_unicast_update_rcvd_cnt",
"label": [
{
"label-key": "afi",
"label-value": "ipv6",
"label-type": "static"
},
{
"label-key": "direction",
"label-value": "in",
"label-type": "static"
},
{
"label-key": "peer",
"label-value": "peer_ipv4_address",
"label-type": "dynamic"
},
{
"label-key": "safi",
"label-value": "unicast",
"label-type": "static"
}
]
},
{
"attribute-name": "ipv6_unicast_update_sent_cnt",
"label": [
{
"label-key": "afi",
"label-value": "ipv6",
"label-type": "static"
},
{
"label-key": "direction",
"label-value": "out",
"label-type": "static"
},
{
"label-key": "peer",
"label-value": "peer_ipv4_address",
"label-type": "dynamic"
},
{
"label-key": "safi",
"label-value": "unicast",
"label-type": "static"
}
]
}
]
}
]
}The API returns a 201 Created response if a new metric was added and returns 204 No Content if an existing metric got updated.
Removing a Time-series
The following API request removes the default_bgp_prefixes_count time series from the switch configuration.
DELETE /api/v1/rbfs/elements/BNG/services/restconfd/proxy/restconf/data/rtbrick-config:time-series/metric=default_bgp_prefixes_count HTTP/1.1
Host: 10.0.0.1:19091The API returns a 204 No Content response if the delete operation succeeded. Any API call to remove a configuration that does not exist results in a 409 Conflict error response.
Example Response:
{
"ietf-restconf:errors": {
"error": {
"error-type": "application",
"error-tag": "data-missing",
"error-severity": "error",
"error-message": "Data does not exist; cannot delete resource"
}
}
}Operational State API: Use Cases and Examples
The operational state API provides access to operational state data, including routing protocols, subscriber, and system state information. The operational state is a runtime information and will be reset after each reboot.
| The operational state API is accessed through the CtrlD proxy endpoint. |
| Use Prometheus for operational state monitoring and metric sampling. |
Querying Subscriber Sessions
The following example shows how to read up to five (limit=5) active subscriber sessions on port ifp-0/0/0 (ifp_name=ifp-0/0/0).
GET /api/v1/rbfs/elements/BNG/services/opsd/proxy/subscribers?ifp_name=ifp-0/0/0&limit=5 HTTP/1.1
Host: 10.0.0.1:19091The API call uses the CtrlD proxy endpoint to invoke the Operational State API, the element name is BNG and the service name is opsd.
The following example shows five IPoE subscriber sessions.
[
{
"subscriber_id": 216454257090494480,
"subscriber_id_str": "216454257090494480",
"subscriber_state": "ESTABLISHED",
"subscriber_user_name": "02:00:00:00:00:06@ipoe",
"access_type": "IPoE",
"accounting_session_id": "216454257090494480:1695654885",
"ifp_name": "ifp-0/0/0",
"outer_vlan": 128,
"inner_vlan": 6,
"client_mac": "02:00:00:00:00:06",
"agent_remote_id": "DEU.RTBRICK.6",
"agent_circuit_id": "0.0.0.0/0.0.0.0 eth 0:6"
},
{
"subscriber_id": 216454257090494481,
"subscriber_id_str": "216454257090494481",
"subscriber_state": "ESTABLISHED",
"subscriber_user_name": "02:00:00:00:00:07@ipoe",
"access_type": "IPoE",
"accounting_session_id": "216454257090494481:1695654885",
"ifp_name": "ifp-0/0/0",
"outer_vlan": 128,
"inner_vlan": 7,
"client_mac": "02:00:00:00:00:07",
"agent_remote_id": "DEU.RTBRICK.7",
"agent_circuit_id": "0.0.0.0/0.0.0.0 eth 0:7"
},
{
"subscriber_id": 216454257090494482,
"subscriber_id_str": "216454257090494482",
"subscriber_state": "ESTABLISHED",
"subscriber_user_name": "02:00:00:00:00:08@ipoe",
"access_type": "IPoE",
"accounting_session_id": "216454257090494482:1695654885",
"ifp_name": "ifp-0/0/0",
"outer_vlan": 128,
"inner_vlan": 8,
"client_mac": "02:00:00:00:00:08",
"agent_remote_id": "DEU.RTBRICK.8",
"agent_circuit_id": "0.0.0.0/0.0.0.0 eth 0:8"
},
{
"subscriber_id": 216454257090494483,
"subscriber_id_str": "216454257090494483",
"subscriber_state": "ESTABLISHED",
"subscriber_user_name": "02:00:00:00:00:09@ipoe",
"access_type": "IPoE",
"accounting_session_id": "216454257090494483:1695654885",
"ifp_name": "ifp-0/0/0",
"outer_vlan": 128,
"inner_vlan": 9,
"client_mac": "02:00:00:00:00:09",
"agent_remote_id": "DEU.RTBRICK.9",
"agent_circuit_id": "0.0.0.0/0.0.0.0 eth 0:9"
},
{
"subscriber_id": 216454257090494484,
"subscriber_id_str": "216454257090494484",
"subscriber_state": "ESTABLISHED",
"subscriber_user_name": "02:00:00:00:00:0a@ipoe",
"access_type": "IPoE",
"accounting_session_id": "216454257090494484:1695654885",
"ifp_name": "ifp-0/0/0",
"outer_vlan": 128,
"inner_vlan": 10,
"client_mac": "02:00:00:00:00:0a",
"agent_remote_id": "DEU.RTBRICK.10",
"agent_circuit_id": "0.0.0.0/0.0.0.0 eth 0:10"
}
]Each subscriber session has a unique subscriber ID and the subscriber ID is an unsigned 64-bit integer.
The subscriber_id holds the numeric subscriber ID value, while subscriber_id_str contains a string representation of the subscriber ID.
Some tools and programming libraries comply I-JSON standard. This standard defines numeric values as double-precision floating-point numbers. As a result, subscriber ID values will be rounded and may confuse. It is recommended to read the subscriber ID from the subscriber_id_str in such environments.
|
Terminating a Subscriber Session
The following API call terminates the subscriber session for the subscriber with the subscriber ID: 216454257090494484.
DELETE /api/v1/rbfs/elements/BNG/services/opsd/proxy/subscribers/216454257090494484 HTTP/1.1
Host: 10.0.0.1:19091The switch returns a 202 Accepted status code to acknowledge that the session is going to be terminated.
Prometheus: Use Cases and Examples
Accessing the Federation Endpoint
The Prometheus federation endpoint returns all metrics collected by Prometheus in the Prometheus Exposition Format.
GET /api/v1/rbfs/elements/BNG/services/prometheus/proxy/federate?match%5B%5D=%7Bjob%3D%22bds%22%7D HTTP/1.1
Host: 10.0.0.1:19091
The match condition is required to select all BDS metrics that is metrics collected from brick daemons and the brick data store (BDS).
|