Configurations

This section describes the configuration files of the APIGWD and CTRLD.

APIGWD

In a production environment, the APIGWD binary starts with default parameters. This service of APIGWD is called rtbrick-apigwd.

To see the default parameters and the files where configurations are stored, the easiest way to figure out is to do a apigwd -help.

To see the actual installed APIGWD version we can use apigwd -version.

APIGWD has in essence 3 important configuration files:

  • /etc/rtbrick/apigwd/config.json: Configuration for the apigwd

  • /etc/rtbrick/apigwd/access_secret_jwks.json: JWKS file for external communication

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

SSL certificate

Every call to the APIGWD is secured by TLS. If there is no TLS certificate provided, it is one generated and signed by a self-signed root CA.

To specify a TLS certificate, there are the following possibilities to achieve this:

  • Provide the TLS file via ZTP

  • Provide the TLS remote file URLs via the config.js:
    Therefore you can also specify a reload time. Every x seconds APIGWD tries to download a new TLS file. But for downloading, an RFC 7234-compliant cache is used.

JWKS File

The APIGWD validates the access token against a JSON Web Key Set (JWKS) (https://tools.ietf.org/html/rfc7517).

APIGWD allows to specify 2 sources for keyset, and for validation, the sets are consulted in the following order:

  • A local file on the filesystem:
    This file can be provided via ZTP. It is recommended to provide one file, even if it is an empty key set file. Otherwise, there is a preconfigured file on the system that will be used.

  • Provide the JWKS remote file URLs via the config.js:
    Every time a token has to be verified the JWKS file will be downloaded, but for the download an RFC 7234-compliant cache is used.

  • Provide the OpenIDConnect configuration via the config.js:
    Every time a token has to be verified the Issuer is consulted to get the link to the JWKS file, and the file will be downloaded, but for the download, an RFC 7234 compliant cache is used.

Caching

As stated above, for configuration file downloads an RFC 7234 compliant cache is used. The cache directives should be used wisely; otherwise, a lot of traffic could be generated.

config.json

This section describes the main configuration file of APIGWD. This file can be changed on the file system, APIGWD has a file watcher on the file and does a reload when the file changes.

/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
}
/etc/rtbrick/apigwd/config.json format

Name

Type

Description

access_token_jwks_urls

[]string

Allows to specify multipe 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.

access_secret_jwks.json

This section describes the access_secret_jwks.json file. This file can be changed on the file system; APIGWD has a file watcher on the file and does a reload when the file changes.

JSON Web Key Set (JKWS) is described in the RFC 7517.

/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 are for the authentication of external calls towards the APIGWD.

The right key is selected by the kid (key id). With this key, the access tokens are verified and converted to a RtBrick token.

tls.pem

This section describes the tls.pem file. This file contains the TLS certificate (public and private key) used to serve the TLS endpoint.

If the file is not specified, a new self-signed certificate is created.

This file can be changed on the file system, APIGWD has a file watcher on the file and does a reload when the file changes.

This file is an X509 public/private key file in PEM format specified in the RFC7468.

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

CTRLD

In a production environment, the CTRLD binary starts with default parameters. The CTRLD service is called rtbrick-ctrld.

To see the default parameters and the files where configurations are stored, the easiest way to figure out is to do a ctrld -help.

To see the actual installed CTRLD version, use ctrld -version.

CRTLD has three important configuration files:

  • /etc/rtbrick/ctrld/config.json: Configuration for CTRLD

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

  • /var/lib/lxc/<container-name>/element.config: Element configuration file per container.

config.json

This section describes the main configuration file of CTRLD. This file can be changed via API; if it is changed on the file system, CTRLD has to be restarted.

/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,
            "network": "http",
            "address": "http://10.200.32.49:12201/gelf"
          },
          {
            "type": "syslog",
            "max_log_level": 5,
            "network": "udp",
            "address": "10.200.32.49:516"
          }
        ]
      },
      "ztp": {
        "endpoints": [
          {
            "type": "gelf",
            "max_log_level": 4,
            "network": "http",
            "address": "http://10.200.32.49:12201/gelf"
          }
        ]
      }
    }
  },
  "auth_enabled": false
}
/etc/rtbrick/ctrld/config.json format

Name

Type

Description

element_name

string

The element name of the host personality of the switch.

pod_name

string

The pod name of the host personality of the switch.

rbms_enable

bool

To enable all RBMS outgoing messages rbms_host

rbms_host

string

RBMS base URL e.g.: 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 per routing instance to CTRLD. The alias default, acts as the default alias if the specific one is not set.

Name

Type

Description

alias

string

Logical name of the endpoints e.g.: ztp for ztp messages.

Each alias can have multiple endpoints. Consider the following constellations.

If an alias does not define any endpoint, the alias is disabled, that means the message is not sent and will also not be sent to the default alias. This allows disabling the default alias, which means no message is sent as long as no specific alias gets defined.

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

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

This section shows the role based access control (RBAC) configuration for CTRLD. This file can be changed via API; if it is changed on the file system CTRLD has to 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.

So the example rules mean:

  • The user with the role system is allowed to access all 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. The user with the role system can access all rest endpoints and act on them with all HTTP methods.

element.config

This section shows the element.config, which can be created per container. This file allows redefining the element name so that the name can defer from the container name.

/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 (Default container name)

pod_name

string

Name of the POD

ztp_enabled

bool

If enabled, the ZTP post process starts after the switch changes to an operational state "up". It’s recommended to set this to false. In that case, only the initial installation or reinstallation will trigger that process.