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.

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

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

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.

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.

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.

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

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

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.

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.

/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

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": ".*"}
  ]
}
/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.

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