sidebar: font-family: Serif background-color: #EEEEEE sidebar-title: font-family: Helvetica
Download PDF

1. RBMS Installation Guide

This document guides you through the installation and initial setup of RBMS.

1.1. Before you start

1.1.1. Prerequisites

RBMS is shipped in docker container images which are made available on RBMS requires docker and docker-compose to be installed on your system. docker-compose simplifies the setup process by running all containers from a provided manifest file with a single command. Please follow the instructions in Get docker and Install docker-compose of the official docker documentation to install docker and docker-compose.

There is no advanced knowledge of docker needed to follow the installation instructions in the RBMS installation guide. All important commands to run the RBMS docker containers from the provided RBMS docker images are outlined in this installation guide.

Important sudo privileges are needed to install RBMS.

1.1.2. Preparing your user account to work with docker

Add your user to the docker group to not have to prepend all docker commands with sudo any longer.

Run the following command to add your user to the docker group.

~$ sudo usermod -aG docker $(whoami)

Exit the terminal and connect again to make the changes taking effect.

1.2. Overview

The installation process consists of the following phases:

  1. RBMS setup

  2. Grafana and Prometheus setup

  3. Graylog setup

The RBMS setup addresses the installation of RBMS itself, including the RBMS database, applications and web user interface.

Prometheus, an open-source monitoring tool, samples metrics from the switches and stores them in a time series database. Grafana, an open-source visualization platform, provides means to visualize and inspect the metrics gathered by Prometheus. The Grafana and Prometheus setup installs both tools with pre-provisioned dashboards for a quick start.

Graylog is an open-source log management system. It stores data in an Elasticsearch database and provides means to automate log processing. The switches send log messages to Graylog. RBMS queries Elasticsearch to show the received log messages. The Graylog setup guides you through the steps to make Graylog ready for receiving log messages from RBFS.

1.3. Prepare Installation

Create the /opt/rbms folder and change to this directory.

~$ sudo mkdir -p /opt/rbms && cd "$_"

Extract the rbms.tar ball.

/opt/rbms$ sudo tar -xvf rbms.tar && rm rbms.tar

The following files and folders have been added to the /opt/rbms directory:

/opt/rbms$ tree -L 4 .
|-- docker-compose.yaml
|-- postgres
|   |-- data
|-- rbms.env
|-- telemetry
|   |-- docker-compose.yaml
|   |-- grafana.env
|   |-- grafana.ini
|   |-- prometheus
|   |   |-- etc
|   |       |--
|   |       |-- prometheus.yml
|   |-- provisioning
|       |-- dashboards
|       |   |-- basic
|       |   |-- default.yml
|       |   |-- fibd
|       |-- datasources
|           |-- default.
|-- templates
|-- wildfly
|   |-- logs
|-- ztp
    |-- configs

15 directories, 9 files
  • The docker-compose.yaml file contains the instructions to run the RBMS docker containers.

  • The postgres directory contains the data of the RBMS database.

  • The rbms.env file contains the environment-specific settings. More details about the environment variables can be found in the next section.

  • The telemetry directory contains the configuration for Prometheus and Grafana to gather and visualize metrics from switches. More details about configuring Prometheus and Grafana can be found later in this document.

  • The templates folder contains templates for configuration generation.

  • The wildfly directory contains the logs of the RBMS applications. Wildfly is an open-source application server hosting the RBMS application.

  • The ztp directory contains the startup-configuraton for the switches in the network. More details about ZTP configuration can be found in post installation tasks section in this document.

1.4. RBMS Setup

The first step is to install the RBMS application, database and user interface. All services are started via docker-compose in a single command. However, before running this command, the RBMS environment variables need to be set for your environment.

1.4.1. Configuring RBMS Environment variables

The rbms.env file contains all RBMS environment variables.

Caution The <RBMS_IP_OR_HOST> placeholder needs to be replaced by the actual IP address or host name.

Detailed information about the existing environment variables can be taken from the tables below:

Environment Variable Description


The name of the RBMS database (Default: leitstand)


The postgres user name (Default: leitstand)


The postgres user password. RBMS uses the provided credentials to connect to the database (Default: changeit)


The JDBC connections string to establish a database connection to the created database (Default: jdbc:postgresql://rbms-db:5432/leitstand)


The user name to authenticate Leitstand for establishing a database connection (Default: leitstand)


The password for the specified LEITSTAND_DB_USER (Default: changeit)


The external URL to access the RBMS terminal emulator (Default: http://<RBMS_IP_OR_HOST>/ssh/host, where <RBMS_IP_OR_HOST> needs to be replaced by the actual IP address or DNS name)


Sets the origins from which RBMS UI is allowed to embedd content from (Default: *).


Sets the endpoint URL of the Elasticsearch API


Sets the endpoint URL of the template engine rendering RBFS configurations (Default: http://rbms-fabric-template-engine)


Sets the enpoint URL of the ZTP service to publish new device configurations.


The URL to access the Grafana user interface.

In addition, the following environment variable exist to connect RBMS with an OAuth2/OpenID Connect-compliant authorization service.

Environment Variable Description


URL to auto-discover the authorization settings.


Client identifier to authenticate RBMS against the authorization service.


The shared secret to authenticate RBMS against the authorization service.


Connect timeout in milliseconds to establish a connection to the authorization service. Defaults to 10 seconds.


Read timeout in milliseconds to wait for response from the authorization service. Defaults to 10 seconds.

Add the following environment variables if your authorization service does not support automatic configuration discovery.

Environment variable Description


Authorization service URL to prompt an unauthenticated user for credentials.


Token service endpoint URL to obtain an access token from.


User info endpoint URL to query the user profile of the authenticated user.


Base64 URL-encoded X509 certificate chain to verify JWS tokens signed with asymmetric keys.


Token secret to verify JWS tokens signed with symmetric key.


The token signature algorithm (e.g. HS256)

In case you prefer the RBMS built-in user repostory, you have to provide a secret to sign all issued access tokens.

Environment variable Description


The secret for signing the issued access tokens. RBMS uses HS256 to sign access tokens and the provided secret must have a minimum length of 256 bits.

1.4.2. Setting File System Permissions

Important root group requires write access to the postgres/data and wildfly/logs directories.

This can be acchieved by transferring ownership to root and modifying the file permissions accordingly:

/opt/rbms$ sudo chown root:root  postgres/data
/opt/rbms$ sudo cmod 775  postgres/data
/opt/rbms$ sudo chown root:root  wildfy/logs
/opt/rbms$ sudo cmod 775  wildfly/data

1.4.3. Starting RBMS Containers

Run docker-compose up -d to start RBMS.

This command pulls all docker images from and starts the following containers:

Container Description


Nginx reverse proxy as ingress node for all incoming HTTP traffic


RBMS application and web user interface


Postgresql database to store the RBMS data


Terminal emulator to access a switch terminal from the browser


Template engine to render switch configurations from templates.


ZTP service providing access to the startup configuration and installer images.

1.5. Grafana and Prometheus Setup

Change to the /opt/rbms/telemetry directory.

~$ cd /opt/rbms/telemetry/

This directory contains the following artefacts: - docker-compose.yaml file to create the Grafana and Prometheus docker containers. - grafana.env file to configure the Grafana environment. - prometheus/etc directory to configure Prometheus.

1.5.1. Configuring Prometheus

Change to the /opt/rbms/telemetry/prometheus/etc directory:

~$ cd /opt/rbms/telemetry/prometheus/etc

Edit the file and add the CTRLD endpoint for all switches to the list of targets.

Say you run four switches in your fabric:

Switch IP Address





then the following targets need to be added to the file:

# l1.pod1
- targets: ['']
    __metrics_path__: "/api/v1/rbfs/elements/l1.pod1/services/prometheus/proxy/federate"
# l2.pod1
- targets: ['']
    __metrics_path__: "/api/v1/rbfs/elements/l2.pod1/services/prometheus/proxy/federate"
# s1.pod1
- targets: ['']
    __metrics_path__: "/api/v1/rbfs/elements/s1.pod1/services/prometheus/proxy/federate"
# s2.pod1
- targets: ['']
    __metrics_path__: "/api/v1/rbfs/elements/s2.pod1/services/prometheus/proxy/federate"

The targets attribute specifies the CTRLD endpoint. The metrics_path label sets the path to pull the metrics from the configured CTRLD endpoint. Prometheus reloads the file periodically. See the Prometheus configuration guide for more information about Prometheus configurations.

Tip Run docker restart rbms-prometheus to apply changes immediately.

1.5.2. Configuring Grafana environment

Change to the /opt/rbms/telemetry directory:

~$ cd /opt/rbms/telemetry

Edit the grafana.env file to configure Grafana and enable Single Sign-On (SSO) using OAuth2/OpenID Connect.

Important Single Sign-On is key to embed Grafana dasbhoard panels seamlessly in the RBMS UI.

The following environment variables exist:

Environment Variable Description


The URL to access the Grafana user interface.


The URL to prompt a user for credentials.


The URL to obtain the access token from.


The URL to obtain the user profile information of the authenticated user.


The client identifier to authenticate Grafana against the authorization service.


The client secret to authenticate Grafana against the authorization service.


The email address of the Grafana admin account that is allowed to configure Grafana.

Important The ADMIN_USER_EMAIL environment is mandatory to create an administrator account that can then nominate additional administrators in Grafana.
Tip The RBMS built-in user repository also includes a minimal authorization flow implementation to enable Single Sign-On for Grafana if no authorization service is available.

Use the following settings to connect Grafana to the built-in authorization flow shipped with RBMS:


Replace <RBMS_IP_OR_HOST> with the IP address or DNS name of your RBMS installation.

1.5.3. Starting Grafana and Prometheus

Run docker-compose up -d to run Grafana and Prometheus

This command pulls the Grafana and Prometheus images runs the following containers from them:

Container Description


Grafana to visualize RBFS time series data


Prometheus to scrape metrics from the switches

1.6. Graylog Setup

Graylog is an open-source enterprise log management system. It stores data in an Elasticsearch database and provides means to query and process log files.

The RBMS distribution includes a dockerized Graylog allowing you to setup Graylog quickly for a first try.

Important RBMS can be connected to other log management systems by providing a connector that translates the RBMS log queries to queries of the underlying log managment system.
Change to the `log` directory.
~$ cd /opt/rbms/log/

Edit graylog.env and provide the IP address or hostname of your graylog server.

Run sudo sysctl -w vm.max_map_count=262144 to grant sufficient virtual memory for Elasticsearch.

Run docker-compose up -d to start Graylog. This commands pulls the Graylog, MongoDB and Elasticsearch images and runs the following three containers:

Container Description


The graylog log management application.


The mongo database to store the graylog configuration and metadata


The elastcisearch database to store the log data.

Log in to Graylog UI using default credentials (admin/admin).

Click System and select Inputs.

graylog system input

Select GELF HTTP from the drop down list.

Click Launch new input

graylog http gelf input

Check the Global option.

In Title add a descriptive name (e.g. RBFS)

Click Save. A new GELF input is displayed.

graylog rbfs gelf input

1.7. Post Installation Tasks

1.7.1. User and Group Management

Create the users and groups with RBMS access privileges.

1.7.2. Network Inventory Management

Start population the inventory with information about your network, including network facilities, pods and elements.

Use rtb-image to register software images in RBMS.

Create configuration templates to generate switch configurations.

Issue an accesskey for CTRLD to grant RBMS access for CTRLD. This is required to allow CTRLD to maintain switch information in the RBMS inventory. The accesskey should include the ivt.element and job.task scopes.

1.7.3. Zero-Touch Provisioning (ZTP)

Configure the DHCP server to convey the DHCP options required by ONIE to discover the ONL installer image.

©Copyright 2024 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 Use of marks belonging to other parties is for informational purposes only.