Download PDF
Home

1. RBFS REST APIs

This document contains all the information about RBFS REST API services, their purposes and how to use these APIs. This documentation goes hand-in-hand with the RBFS OpenAPI document which provides information about all RBFS REST API endpoints. It is recommended to refer to this document in conjunction with the RBFS OpenAPI document.

1.1. Introduction to RBFS REST APIs

RBFS REST APIs allow customers and partners to programmatically access information from the RBFS software components. RBFS REST APIs enable users to manage and automate many of their tasks by accessing and consuming the RBFS data simply and securely.

RBFS REST API architecture supports containerized deployments with a centralized configuration and management. It also enables the configuration and management of distinct daemons and services.

RBFS APIs adhere to the Representational State Transfer (REST) principles and allow consumers to securely connect to the RBFS device, obtain information (read) and run actions or operations to apply changes. RBFS REST APIs use JavaScript Object Notation (JSON) for the exchange of information. The OpenAPI Specification format, which is a broadly accepted industry standard for describing REST APIs, is used to describe, consume, and visualize RBFS REST APIs.

1.2. Understanding RBFS APIs

RBFS, a disaggregated Broadband Network Gateway, provides many APIs to make all communications possible with various RBFS software components, the host operating system (ONL), and the hardware platform. RBFS consists of several independent microservices including the API Gateway daemon (ApiGwD) and Control daemon (CtrlD). Both of these microservices, known as daemons, play crucial roles in managing RBFS instances.

API gateway functions only if management plane security is enabled. All API requests from external clients are routed to the API Gateway. After successful authentication by the API Gateway, these requests are forwarded to the Control daemon. CtrlD, which is aware of the state and port information of all daemons that reside in the RBFS container, can forward requests to the respective daemons.

Note If security is disabled, API Gateway does not function and, then CtrlD becomes the first entry point for external requests.
RBFS REST APIs

The illustration presents how the RBFS REST APIs communication happens with various underlying software components. RBFS microservices, which perform various functions, are containerized in an open Linux container. RBFS APIs are generally categorized into Public Management APIs and Internal APIs. Public Management APIs include CtrlD API, RESTCONF API, and Operational state API. These APIs are used for managing and automating many of the network administration tasks.

Note The use of internal APIs such Brick Daemon APIs and BDS APIs are not supported.

The illustration also presents the API Gateway daemon (ApiGwD) and Control daemon (CtrlD), which are deployed on the host operating system (open network Linux) along with the RBFS container. The API Gateway acts as an entry point that provides a secure channel for all REST APIs by authenticating all requests. After successful authentication by the API Gateway, CtrlD (Control Daemon) passes all the requests to the respective daemons (that reside in the RBFS container) which are responsible for performing certain tasks.

1.2.1. RBFS APIs

CtrlD API: CtrlD runs on the host OS (ONL) and acts as a proxy to the other APIs including high-level APIs for the RBFS configurations. The CtrlD API, implemented by the CtrlD, performs various tasks such as starting the container and rebooting the device. In case of a software upgrade, this API is used to trigger the upgrade.

API Gateway: You can deploy the API Gateway Daemon (ApiGwD) on the host OS (that is ONL) to secure the RBFS management plane. The API Gateway authenticates all API requests using JSON web tokens. The API Gateway Daemon acts as the TLS endpoint for the hardware platform and it converts external access token into an internal RtBrick token /SEC/. Finally, it forwards the requests to the CtrlD.

The API Gateway also enforces an API throttler that provides a mechanism called API throttle quotas to protect the RBFS system resources from being exhausted with too many requests by a single client system that uses the RBFS APIs very extensively.

Operational State APIs: The Operational State API, provided by the Operational State Daemon (opsd), allows accessing system states such as routing protocol states, interface states, subscriber states and resource utilization. The Operational State Daemon takes care of examining the operational state of a switch and runs actions to diagnose and troubleshoot the problems. The operational state is ephemeral and state data is lost when the switch reboots.

RESTCONF APIs: With RESTCONF, you can manage all the configurations in RBFS.

Prometheus APIs: Prometheus APIs help to retrieve metrics from various RBFS components for visibility.

Note RFC and draft compliance mentioned in the document are partial except as specified.

2. Functions and Use cases of RBFS REST APIs

2.1. CtrlD API

The CtrlD performs various functions in the lifecycle of an RBFS container. Zero-Touch Provisioning installs the RBFS software on the hardware devices with minimal human intervention. It is the responsibility of the CtrlD to initiate, discover and download the startup configuration files as part of zero-touch provisioning (ZTP) process. The CtrlD retrieves the base URL and executes the startup configuration on the device, that is pre-installed with ONL, the host operating system.

CtrlD API acts as a proxy endpoint that defines the way the API proxy interacts with the backend services. CtrlD is a go-between, which sits in the middle, for requests from clients and the API. As the API proxy, CtrlD, resides in front of the API, enforcing policies that dictate the usage of the API.

CtrlD API can be used to reboot the switch with or without a software upgrade. As a proxy endpoint, users can access the following APIs through CtrlD:

  • RESTCONF API

  • Operational State API

  • Prometheus API

For more information about CtrlD API use case and examples, see section 5.1. CtrlD API: Use Case and Example'.

You can see the CtrlD OpenAPI Specification at CTRLD API Reference.

2.2. RESTCONF API

RESTCONF is an HTTP-based REST API protocol for network management and automation. It provides a programmatic interface for accessing data defined in YANG. The YANG model describes the configuration syntax. In RBFS, the RESTCONF API provides the configuration data.

Users can use RESTCONF API to execute various configurations in RBFS. RESTCONF API can be used for the following tasks:

  • Read configurations

  • Replace configurations

  • Partial configuration update

  • Remove configurations

For more information about RESTCONF API use case and examples, see section 5.2. RESTCONF API: Use Case and Example.

You can see the RESTCONF OpenAPI Specification at RESTCONF API Reference

2.3. Operational State API

The Operational State API (opsd) provides the system state information. The ospd is backward compatible and supports running older and newer versions of applications together in the network. The Backward compatibility feature is useful whenever newer RBFS releases are rolled out.

The Operational State API was implemented using the Python language that provides a collaborative system to all stakeholders including integration partners, customers, professional services and engineering to collaborate on the API endpoints.

You can locate the Operational State OpenAPI Specification at Operational State API Reference.

For more information about Operational State API use case and examples, see section 5.3. Operational State API: Use Case and Example.

2.4. Guidelines and Limitations

When you execute configurations through management APIs, and then with the Command Line Interface at the same time, it results in conflicts when you commit the configuration through the CLI. The reason is that CtrlD directly interacts with the backend applications and these changes are not synced with the CLI.

3. Configure API Gateway and CtrlD Components

The section provides configuration information for various components of the API Gateway and CtrlD. Both the API Gateway and CtrlD have been installed as part of the RBFS installation on the host operating system. You must complete some additional configurations for running API Gateway and CtrlD.

3.1. Configure API Gateway Components

The API Gateway service is called rtbrick-apigwd and the API Gateway daemon contains some default parameters.

  • To know the installed API gateway version, run the apigwd -version command.

  • To display the default settings and the location of configuration files, run the apigwd -help command.

The mandatory API Gateway configuration files include:

  • API Gateway configuration file: /etc/rtbrick/apigwd/config.json

  • JWKS file for access token verification: /etc/rtbrick/apigwd/access_secret_jwks.json

  • X509 public/private key file in the 'pem' format: /etc/rtbrick/apigwd/tls.pem

3.1.1. SSL/TLS Certificate

API Gateway uses Transport Layer Security (TLS), also known as Secure Sockets Layer (SSL), certificates to authenticate and secure all requests pass through API Gateway.

If there is no TLS certificate provided, API Gateway generates one certificate signed by a self-signed root CA.

You can specify a TLS certificate in any of the following ways:

  • Deploy the TLS file through ZTP

  • Provide the URL for TLS file downloading in the config.json file.

With this setting, API Gateway monitors the server periodically for new TLS files using the HTTP caching directives as described in the RFC 7234 to avoid unnecessary downloads.

tls.pem file

The tls.pem file, which contains the X509 certificate (public and private key), enables TLS in PEM format (as described in the RFC 7468). The tls.pem file can be changed on the file system. API Gateway automatically reloads the tls.pem file whenever it gets changed or replaced.

/etc/rtbrick/apigwd/tls.pem example
-----BEGIN CERTIFICATE-----
NOT A REAL KEY
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
NOT A REAL KEY
-----END RSA PRIVATE KEY-----

3.1.2. JSON Web Token File

JSON Web Token (RFC 7517 enables secure transmission of information between client and server as a JSON object. API Gateway validates the access token against a JSON Web Key Set (JWKS) and it allows specifying two sources for the keyset. The sources are consulted in the following order for validation:

A local file on the file system

This file can be deployed through ZTP. It is recommended to deploy a local file on the file system. If it is an empty key set file, there is a default pre-configured file on the system that is used.

Remote file URLs through the config.json

You can provide the JWKS remote file URLs through the config.json file. Whenever a token needs to be verified, a JWKS file gets downloaded.

Whenever an access token needs to be verified, the API Gateway queries the server for the current JWKS file using the HTTP caching directives (as described in RFC 7234) to avoid unnecessary downloads.

Note An RFC 7234-compliant cache is used for downloading the configuration file.

JSON Web Key Set

The JSON Web Key Set contains the public keys used to verify any JSON Web Token issued by the authorization system.

The access_secret_jwks.json file can be updated on the file system.

API Gateway automatically reloads the tls.pem file whenever it gets changed or replaced.

/etc/rtbrick/apigwd/access_secret_jwks.json example
{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "access",
      "alg": "RS256",
      "n": "NOT A REAL KEY"
    }
  ]
}

These keys authenticate external requests coming to the API Gateway. The right key is selected by the kid (key id) attribute. With this key, the access tokens are verified and converted into an RtBrick token.

3.1.3. config.json File

The config.json is the configuration file of the API Gateway. API Gateway automatically reloads the file whenever it gets changed or replaced.

/etc/rtbrick/apigwd/config.json example
{
  "access_token_jwks_urls": [
    "http://192.168.202.56:8080/primaryJWKS",
    "http://192.168.202.56:8080/secondaryJWKS"
  ],

  "request_rate": 5,
  "request_burst": 10,
  "report_rejects_every": 10
}

The following table presents the various attributes and the description of the config.json file.

Table 1. /etc/rtbrick/apigwd/config.json format

Name

Type

Description

access_token_jwks_urls

[]string

Allows to specify multiple JWKS remote URLs.

Remote PEM file

pem_urls

[]string

Allows to specify multiple PEM remote URLs. Empty list disables the download.

pem_reload_time

int

Allows to specify the time after a new reload is triggered. 0 disables the download.

Request rate limit

request_rate

float

The allowed requests per second per client.

request_burst

int

Is the maximum number of tokens that can be consumed at once, without respect to the rate.

report_rejects_every

int

Report rejects only every x seconds to avoid massive logging to a GELF endpoint.

3.2. Control Daemon (CtrlD)

The CtrlD service is called rtbrick-ctrld and the CtrlD contains some default parameters.

  • To know the installed CtrlD version, run the ctrld -version command.

  • To display the default settings and the location of configuration files, run the ctrld -help command.

The CtrlD configuration files include:

  • The CtrlD configuration file: /etc/rtbrick/ctrld/config.json

  • The Role-Based Access Control policy file: /etc/rtbrick/ctrld/policy.json

  • The element configuration file for the container: /var/lib/lxc/<container-name>/element.config

3.2.1. config.json file

The config.json file can be changed using API. If the file is updated on the file system, CtrlD must be restarted.

Note Changes to the config.json file will come into effect only after CtrlD gets restarted. Use the CtrlD API to apply in-service configuration changes at runtime. CtrlD updates the config.json file to get the changes applied through the API persistent.
/etc/rtbrick/ctrld/config.json example
{
  "element_name": "element_name",
  "pod_name": "pod_name",
  "rbms_enable": true,
  "rbms_host": "http://198.51.100.48",
  "rbms_authorization_header": "Bearer THIS IS NOT A REAL KEY",
  "rbms_heartbeat_interval": 10,
   "logging": {
    "heartbeat_interval": 60,
    "aliases": {
      "default": {
        "endpoints": [
          {
            "type": "gelf",
            "max_log_level": 5,
            "buffer_size": 500,
            "network": "http",
            "address": "http://10.200.32.49:12201/gelf"
          },
          {
            "type": "syslog",
            "max_log_level": 5,
            "buffer_size": 30,
            "network": "udp",
            "address": "10.200.32.49:516"
          }
        ]
      },
      "ztp": {
        "endpoints": [
          {
            "type": "gelf",
            "max_log_level": 4,
            "buffer_size": 20,
            "network": "http",
            "address": "http://10.200.32.49:12201/gelf"
          }
        ]
      }
    }
  },
  "auth_enabled": false
}

The following table presents the various attributes and descriptions for CtrlD config.json file.

Table 2. /etc/rtbrick/ctrld/config.json format

Name

Type

Description

element_name

string

The name of the element (container).

pod_name

string

The pod name. Pod stands for point (zone) of deployment. A pod can contain a group of elements.

rbms_enable

bool

To enable all RBMS outgoing messages rbms_host.

rbms_host

string

RBMS base URL. For example, http://198.51.100.144:9009

rbms_authorization_header

string

RBMS Authorization Header is set to all calls which are outgoing to RBMS.

rbms_heartbeat_interval

int

RBMS heartbeat interval in seconds (⇐0 means deactivated)

auth_enabled

bool

To enable the authorization and authentication.

logging

Log configuration for the host personality of the switch. The routing instances (elements) can configure the logging in the RBFS configuration, and that is forwarded, for the routing instance, to CtrlD. The alias (also known as external log server or Plugin Alias) default acts as the default alias if a specific alias is not defined.

Name

Type

Description

alias

string

Logical name of the endpoints. For example, ztp for ztp messages.

Each alias can have multiple endpoints. If an alias does not define any endpoint, the alias is disabled and the message is not sent and to the default alias.

Name

Type

Description

type

string

Type could be syslog or gelf.

max_log_level

string

MaxLogLevel that will be forwarded (default "Notice: 5)"

network

string

Network get network either tcp, udp or http. Consider the support matrix: * gelf: http * syslog: udp, tcp

buffer_size

string

BufferSize that will be used for the fanout, if the buffer is full, the newer messages that arrive are thrown away.

address

string

Address where to send the message

formatter

string

The formatter that should be used. Consider the support matrix:

  • gelf: none

  • syslog: rfc5424

3.2.2. policy.json file

The policy.json file is used to configure role-based access control (RBAC) for CtrlD. This file can be changed using API. If it is changed on the file system, CtrlD must be restarted.

/etc/rtbrick/ctrld/policy.json example
{
  "permissions": [
    {"sub": "system", "obj": "/*", "act": ".*" },
    {"sub": "supervisor", "obj": "/*", "act": ".*" },
    {"sub": "operator", "obj": "/*", "act": ".*"},
    {"sub": "reader", "obj": "/*", "act": "GET"},
    {"sub": "reader", "obj": "/api/v1/rbfs/elements/{element_name}/services/{service_name}/proxy/bds/table/walk", "act": ".*"},
    {"sub": "reader", "obj": "/api/v1/rbfs/elements/{element_name}/services/{service_name}/proxy/bds/object/get", "act": ".*"}
  ]
}
Table 3. /etc/rtbrick/ctrld/policy.json format
Name Type Description

sub

string

Subjects means the role which has the permission. Here RegexMatch Function is used: a regular expression pattern matcher.

obj

string

Object is the REST endpoint. Here KeyMatch4 Function is used: KeyMatch4 determines whether key1 matches the pattern of key2 (similar to RESTful path), key2 can contain a * and other patterns:

  • "/foo/bar" matches "/foo/"

  • "/resource1" matches "/{resource}"

  • "/parent/123/child/123" matches "/parent/{id}/child/{id}"

  • "/parent/123/child/456" does not match "/parent/{id}/child/{id}"

act

string

And Action is the HTTP Method. Here RegexMatch Function is used: a regular expression pattern matcher.

The rules are:

  • The user with the role 'system' can access all the rest endpoints and act on them with all HTTP methods.

  • The user with the role 'reader' can access all rest endpoints; but can only call the HTTP GET method.

  • All authenticated users are allowed to access the proxy endpoint with all HTTP methods.

3.2.3. element.config file

The element.config file allows to rename the default element name. By default, the element name and the container name are the same. You can use the file to rename the default element name so that the element name and the container name are differentiated.

/var/lib/lxc/<container-name>/element.config example
Table 4. /var/lib/lxc/<container-name>/element.config format
Name Type Description

element_name

string

Name of the element (By default, it is the container name).

pod_name

string

Name of the PoD.

ztp_enabled

bool

If enabled, the ZTP post process starts when the switch is moved to the operational state "up". It is recommended to set this to 'false'. In that case, only the initial installation or reinstallation triggers that process.

4. Events

RBFS REST APIs play important roles in fetching event logs. Event logs are records of events that occur in the different functional areas of the RBFS ecosystem. In RBFS, there are different types of logs. Almost every daemon or module in RBFS generates a variety of logs. All these logs, which are generated from different components, can be exported to the log management server, where you can view and analyze the real-time data.

Log events originate from the RBFS log facility and form a structured log record. If logging is disabled, then no logs are produced. For more information about RBFS Logging, see Logging User Guide.

4.1. Alerts

Alerts are event logs that originate from alert configurations. Alerts either report an issue or notify that an issue has been resolved. Alerts are fully under the control of a customer. Users can implement alert rules to produce an alert that triggers automated action in the management system. An alert event is also a business event when it triggers automated actions.

4.2. Business Events

A business event is a record of events that originate from the control daemon, irrespective of the logging configuration. Business events notify the management system about significant state changes for triggering automated actions.

Business events are recorded by CtrlD and these events are static without any changes release after release.

APIGwD and CtrlD send different GELF and Syslog messages about status changes or the progress of processes to a GELF or Syslog endpoint.

The following table presents the business event message format:

Table 5. GELF message format
Name Type Mandatory Description

Default Message Fields

version

String

Yes

The GELF message format version. Default value: 1.1

host

String

Yes

The hostname is assigned via DHCP to the management interface. Defaults to the management IP address if no hostname is assigned.

level

int

Yes

Message Severity. See Table-1.

timestamp

float

Yes

Unix epoch time in seconds with an optional fraction of milliseconds.

short_message

String

Yes

Problem message.

full_message

String

No

Detailed problem description.

_daemon

String

Yes

Name of the daemon.

_log_module

String

Yes

The module name identifies the component that created the log record. It allows segregating log records into different streams. Each stream can apply different processing rules and also be processed by different organizational units of the network operator.

_log_event

String

Yes

The log event identifies the log message template in the log configuration. The log event simplifies finding where in the system the log record was created. The log event should be succinct and typically conveys a unique reason code. In addition, the log event should be a reference that can be looked up in the product troubleshooting guide.

_serial_number

String

Yes

The serial number of the switch. This allows tracking hardware replacements, even if the element name remains the same. Empty if not available.

_rtb_image_version

String

No

ONL Image Version that is installed on the switch that reports this message.

_origin

String

No

host or container, defines the origin of a message. This is only set for events that are ambiguous.

ZTP Message Fields

_config_name

String

No

Exposes the loaded configuration name. Only set when a configuration file was processed or an attempt to process the file failed (e.g., 404 Not Found response from the HTTP server while attempting to load the configuration)

_config_sha1

String

No

Exposes the SHA1 checksum of the loaded configuration. Only set when the HTTP server returns a configuration.

_operational_state

String

No

Exposes the operational state of the element.

Request Message Fields

_rid

String

No

Request ID, either X-Request-ID or new generated

_user_name

String

No

User name out of the access token

_user_subject

String

No

User subject out of the access token

_received_time

String

No

Time when the requested arrived

_method

String

No

HTTP method

_url

String

No

HTTP url

proto

String

No

HTTP protocol

_remote_ip

String

No

HTTP remote ip address

Service State Message Fields

_service_name

String

No

Service name

_service_operational_state

String

No

Operational Service

_service_startup_time

Number

No

Service startup time in unix epoch time, the number of seconds elapsed since January 1, 1970 UTC.

_service_down_flap_time

Number

No

Last down flap time in unix epoch time, the number of seconds elapsed since January 1, 1970 UTC.

_service_down_flap_counter

Number

No

Last down flap time in unix epoch time, the number of seconds elapsed since January 1, 1970 UTC.

_service_restarted

String

No

Restart is set to true if service_startup_time was changed.

Table 6. Level Descriptions as in RFC 5424
Level Name Comment

0

Emergency

System is unusable

1

Alert

Action must be taken immediately

2

Critical

Critical conditions

3

Error

Error conditions

4

Warning

Warning conditions

5

Notice

Normal but significant condition

6

Informational

Informational messages

7

Debug

Debug-level messages

GELF sample message
{
  "_config_name": "ctrld",
  "_config_sha1": "f1e06ef1e53becde6f8baf2b2fafe7dc9c36f6f0",
  "_daemon": "ctrld",
  "_element_name": "leaf01",
  "_log_event": "ZTP0011I",
  "_log_module": "ztp",
  "_serial_number": "591654XK1902037",
  "host": "leaf01",
  "level": 6,
  "short_message": "ztp ctrld config set",
  "timestamp": 1588382356.000511,
  "version": "1.1"
}
Table 7. Event Types

Instance

severity

log_module

log_event

log config

description

ztp

Notice

ztp

ZTP0011I

ctrld

ztp ctrld config set

ztp

Warn

ztp

ZTP0012W

ctrld

ztp ctrld config not provided

ztp

Alert

ztp

ZTP0013E

ctrld

ztp ctrld config not set

ztp

Notice

ztp

ZTP0021I

ctrld

ztp startup config set

ztp

Warn

ztp

ZTP0022W

ctrld

ztp startup config not provided

ztp

Alert

ztp

ZTP0023E

ctrld

ztp startup config not set

ztp

Notice

ztp

ZTP0041I

ctrld

ztp ctrld rbac config set

ztp

Warn

ztp

ZTP0042W

ctrld

ztp ctrld rbac config not provided

ztp

Alert

ztp

ZTP0043E

ctrld

ztp ctrld rbac config not set

ztp

Notice

ztp

ZTP0051I

ctrld

ztp tls config set

ztp

Warn

ztp

ZTP0052W

ctrld

ztp tls config not provided

ztp

Alert

ztp

ZTP0053E

ctrld

ztp tls config not set

ztp

Notice

ztp

ZTP0061I

ctrld

ztp accessjwks config set

ztp

Warn

ztp

ZTP0062W

ctrld

ztp accessjwks config not provided

ztp

Alert

ztp

ZTP0063E

ctrld

ztp accessjwks config not set

ztp

Notice

ztp

ZTP0071I

ctrld

ztp apigwd config set

ztp

Warn

ztp

ZTP0072W

ctrld

ztp apigwd config not provided

ztp

Alert

ztp

ZTP0073E

ctrld

ztp apigwd config not set

ztp

Notice

ztp

ZTP1000I

ctrld

ztp process finished

security

Warn

security

SEC0001W

ctrld

access forbidden

security

Warn

security

SEC0002W

ctrld

access invalid rtb token

security

Warn

security

SEC0003W

ctrld

access invalid access token

security

Warn

security

SEC0004W

ctrld

not able to download remote keys

security

Warn

security

SEC0005W

ctrld

not able to download remote pem

security

Warn

security

SEC0006W

ctrld

request rate limited (this message is also rate limited, and can be controlled in the apiwd config)

element

Notice

element

HTB0001

ctrld

heartbeat with the operational_state

element

Notice

element

STA0001

ctrld

element state change

element

Notice

element

STA0021

ctrld

service up

element

Error

element

STA0022

ctrld

service unexpected down

element

Notice

element

STA0023

ctrld

service expected down

element

Notice

element

STA0003

ctrld

ready for service

element

Notice

element

STA0031

ctrld

module new (one of the modules is newly discovered e.g. fan, SFP …​, this event will be fired after every reboot of ctrld)

element

Notice

element

STA0032

ctrld

module changed (one of the modules got changed e.g. fan, SFP …​)

element

Notice

element

STA0033

ctrld

module removed (one of the modules got removed e.g. fan, SFP …​)

ALL

Notice

element

STA0040

all

messages could have been dropped

prometheus

?

?

?

element

messages generated by prometheus alerts

5. Appendix: Use case Scenario and Examples for RBFS REST APIs

5.1. 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.

Note 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.

5.1.1. 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:19091

5.1.2. Triggering 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:19091

5.1.3. Using 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.

Note 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)

/api/v1/rbfs/elements/cnbg-1/services/opsd/proxy

RESTCONF Daemon (restcondf)

/api/v1/rbfs/elements/cnbg-1/services/restconfd/proxy

Prometheus

/api/v1/rbfs/elements/cnbg-1/services/prometheus/proxy

5.2. RESTCONF API: Use Cases and Examples

5.2.1. 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:19091

5.2.2. Reading 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"
    ]
}

5.2.3. 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.

Note 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.

5.2.4. 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:19091

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

5.3. 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.

Note The operational state API is accessed through the CtrlD proxy endpoint.
Tip Use Prometheus for operational state monitoring and metric sampling.

5.3.1. 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:19091

The 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.

Note 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.

5.3.2. 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:19091

The switch returns a 202 Accepted status code to acknowledge that the session is going to be terminated.

5.4. Prometheus: Use Cases and Examples

5.4.1. 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
Note The match condition is required to select all BDS metrics that is metrics collected from brick daemons and the brick data store (BDS).

/ONIE/

The ONIE documentation outlines the DHCP options supported for image discovery.
https://opencomputeproject.github.io/onie/design-spec/discovery.html

/ZTP/

The Zero-Touch Provisioning Guide outlines the current configuration discovery process.
https://documents.rtbrick.com/current/ztp/ztp_guide_online.html

/SEC/

The Secure the Management Plane guide gives a detailed insight on this topic.
https://documents.rtbrick.com/current/secmgmt/secmgmt_guide_online.html

/RADIUS/

The RADIUS attribute matrix provides an overview of the supported RADIUS attributes including a reference to the RFC that defines the message attribute.
To obtain this document, contact your customer support team.

/CTRLD/

The CTRLD API describes all CTRLD REST API endpoints in detail.
https://documents.rtbrick.com/index_api.html

/RESTCONF/

The RESTCONF API reference describes all configuration API endpoints.
https://documents.rtbrick.com/index_api.html

/GELF/

The Graylog Extended Log Format (GELF) is a log format, this document outlines the fundamentals.
To obtain this document, contact your customer support team.


©Copyright 2023 RtBrick, Inc. All rights reserved. The information contained herein is subject to change without notice. The trademarks, logos and service marks ("Marks") displayed in this documentation are the property of RtBrick in the United States and other countries. Use of the Marks are subject to RtBrickā€™s Term of Use Policy, available at https://www.rtbrick.com/privacy. Use of marks belonging to other parties is for informational purposes only.