Configurations

This sections 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 therefore also 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 a RFC 7234 compliant cache is used.

RFC and draft compliance are partial except as specified.

JWKS File

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

APIGWD allows to specify 2 source for keyset, and for a 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 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 a RFC 7234 compliant cache is used.

RFC and draft compliance are partial except as specified.

Caching

As stated above, for configuration file downloads a RFC 7234 compliant cache is used. The cache directives should be used wise, 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
Remote PEM file
Name	Type	Description
access_token_jwks_urls	[]string	Allows to specify multipe jwks remote urls.
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 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"
    }
  ]
}

This keys are for authentication of external call towards to 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. This service of CTRLD is called rtbrick-ctrld.

To see the default parameters and therefore also 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 we can use ctrld -version.

CRTLD has in essence 3 important configuration files:

/etc/rtbrick/ctrld/config.json: Configuration for the 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

{
  "rbms_enable": true,
  "rbms_host": "http://198.51.100.48",
  "rbms_authorization_header": "Bearer THIS IS NOT A REAL KEY",
  "rbms_heart_beat_interval": 10,

  "graylog_enable": true,
  "graylog_url": "http://198.51.100.49:12201/gelf",
  "graylog_heart_beat_interval": 10,
  "graylog_endpoints": [
    {
      "name": "ztp",
      "url": "http://198.51.100.146:12201/gelf"
    }
  ],

  "syslog_enable": false ,
  "syslog_network": "udp",
  "syslog_urls": [
    "198.51.100.49:516"
  ],

  "auth_enabled": false
}

/etc/rtbrick/ctrld/config.json format

Name

Type

Description

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_heart_beat_interval

int

RBMS heartbeat Interval in seconds (⇐0 means deactivated)

log_heart_beat_interval

string

Graylog heartbeat Interval in seconds (⇐0 means deactivated)

graylog_enable

bool

To Enable all Graylog outgoing messages

graylog_url

string

Graylog url e.g. http://198.51.100.127:12201/gelf

graylog_severity_level

int

Graylog min LogLevel that will be forwarded (default Notice: 5)

graylog_endpoints

Graylog Endpoints allows to specify multiple graylog endpoints by name. If a log to a specific endpoint is requested and the endpoint is not available, the log is send to the default graylog endpoint.

Name

Type

Description

name

string

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

url

string

Graylog url e.g. http://198.51.100.127:12201/gelf

disable

string

Disables this endpoint.

severity_level

string

Graylog min LogLevel that will be forwarded (default Notice: 5)

If the default endpoint is disabled, but the specific one is enabled than no message will be sent.

If the default endpoint is enabled, but the specific one is disabled than the message to the specific endpoint will not be sent.

syslog_enable

bool

To enable all Syslog outgoing messages

syslog_network

string

Network either tcp or udp

syslog_urls

[]string

URL e.g. ["localhost:516"], multiple endpoints are allowed, but more than 3 is not recommended.

syslog_severity_level

int

Syslog min LogLevel that will be forwarded (default Notice: 5)

auth_enabled

bool

To Enable the authorization and authentication

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 is allowed to 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 is allowed to 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 files allows to redefine the element name, so the name can defer from the container name.

/var/lib/lxc/<container-name>/element.config example

{
  "element_name": "l1.pod1.blr",
  "pod_name": "blr",
  "ztp_enabled": false
}

/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 operational state up. It’s recommended to set this to false. In that case only the initial installation or reinstallation will trigger that process.