Initial Configuration

Introduction

This section assumes that Stream is running in a confined environment: nobody but the person performing the configuration operation and the key ceremony stakeholders should have access to Stream yet, and they should do so under the supervision of a security officer.

Selinux should be disabled during the initial configuration and bootstrapping operations. It will be re-enabled following the security guidelines.

# setenforce Permissive

To ensure that it is permissive, run the following command

# getenforce

This should return Permissive

Configuring the firewall

In order for Stream to work properly, the following ports are used:

Exposed: 443 for HTTPS access to the product (through the web interface or through the API);
Exposed: 80 for HTTP access to the product only to retrieve CRLs (the only allowed endpoint must be /crls/*, this is the case for the default NGINX configuration);
Internal: 25520 and 8558 for high-availability configurations through the AKKA framework.
Internal: 9000 for the Stream API.

Connect to the server with an account with administrative privileges;

Open port TCP/443 on the local firewall with the following command:

# firewall-cmd --permanent --add-service=https

Stream also needs HTTP traffic allowed since it is required to set up the CRLDPs :

# firewall-cmd --permanent --add-service=http

To make the change effective, you need to restart the firewall service:

# systemctl restart firewalld

Enable the service at startup with the following command:

# systemctl enable firewalld

Generating a Tink keyset

To protect its secrets, Stream relies on Tink. A Tink keyset can be issued as:

A plaintext keyset (stored as a file, protected by the filesystem rights and SELinux);
A GCP keyset (protected by a master key in a GCP KMS);
An AWS keyset (protected by a master key in an AWS KMS).

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the main menu, select 'Stream':

In the Stream menu, select 'STREAM_TINK_KEYSET':

Generating a plaintext keyset

In the Tink Keyset Generation menu, select 'PLAINTEXT':

The keyset will be generated automatically. For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Generating a GCP protected keyset

In the Tink Keyset Generation menu, select 'GCP':

The URL of the GCP master key must be typed in the menu.

After pressing OK, the keyset will be generated automatically. For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Generating an AWS protected keyset

In the Tink Keyset Generation menu, select 'GCP':

The URL of the AWS master key must be typed in the menu.

After pressing OK, the keyset will be generated automatically. For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Generating a Play secret

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the main menu, select 'Akka_Play':

In the Akka_Play menu, select 'SECRET':

Validate the new Stream Application Secret:

The Stream configuration is updated:

For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

JVM Configuration

Stream allows you to configure the Xms (minimum memory allocation pool) and Xmx (maximum memory allocation pool) parameters of the JVM running Stream using the configuration tool.

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the configuration menu, select Stream:

In the Stream configuration menu, Select JVM:

Specify the 2048 for xms and 3072 for xmx parameters and select 'OK':

The new JVM parameters are configured.

For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

MongoDB URI Configuration

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the main menu, select Stream:

In the Stream configuration menu, Select MONGODB_URI:

Specify the MongoDB URI to target your MongoDB instance:

Stream is installed to target a local MongoDB instance by default.

If you use an external MongoDB (such as MongoDB Atlas Database or dedicated On-premises database) instance:

Create a user with "read/write" permissions on your MongoDB instance;
Create a replicaSet if using a MongoDB cluster;
Specify a MongoDB URI that does match your context.

External MongoDB database URI syntax

mongodb+srv://<user>:<password>@<hostname>:<port>/stream

External MongoDB cluster of databases URI syntax

mongodb+srv://<user>:<password>@<hostname1>:<port1>,<hostname-2>:<port2>/stream?replicatSet=<replicaset>&authSource=admin

The MongoURI is configured.

For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Stream Hostname Configuration

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the main menu, select Stream:

In the Stream configuration menu, Select STREAM_HOSTNAME:

Specify the DNS FQDN by which Stream will be accessed:

The Stream Hostname is configured:

For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Generating an event seal secret

Stream will generate functional events when using the software.

These events are typically signed and chained to ensure their integrity. Therefore, you must specify a sealing secret for this feature to work properly.

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the main menu, select 'Stream':

In the Stream menu, select 'STREAM_SEAL_SECRET':

Validate the new event seal secret:

The even seal secret is now configured:

For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Installing the Stream license

You should have been provided with a stream.lic file. This file is a license file and indicates an end of support date.

Upload the stream.lic file (using SCP or other means) under /tmp/stream.lic;

Connect to the server with an account with administrative privileges;

Start the Stream configuration utility by running:

# /opt/stream/sbin/stream-config

In the main menu, select Stream:

In the Stream configuration menu, Select STREAM_LICENSE:

Specify the path /tmp/stream.lic and validate:

The Stream License is configured:

For the changes to take effect, you must restart the Stream service by running:

# systemctl restart stream

Installing Stream on a cluster of servers

This section must not be followed if you plan on deploying Stream in standalone mode (vs cluster mode). WARNING: This section does not explain how to install Stream on a Kubernetes cluster. Please refer to the dedicated section.

In the main menu, select 'Akka_Play':

In the Akka_Play menu, select 'AKKA_HA':

In this menu, specify either the IP address or the DNS name for each server that will be running Stream on this cluster with akka management port, as well as the local node index (the number of the node that you are configuring at that moment).

Note that the local node index must match the current node hostname or ip parameter:

Save your changes from the menu.

The High Availability mode is now configured on the current node:

You must now configure your other nodes, but because they belong to the same cluster they need to share the same akka play secret, the same stream licence, the same stream seal secret, the same stream hostname, the same mongo database, the same x509 enforcing and the same stream tink keyset. In order to be able to do that, you need to copy the configuration file that was generated by the stream-config app, named /etc/default/stream and paste it on each one of your nodes;

Then on each other node, run the Stream Configuration utility with the following command:

$ /opt/stream/sbin/stream-config

In the Akka_Play menu, select 'AKKA_HA':

Here, you need to change the local node index to match the hostname of the node that you are configuring:

You will need to import the Stream licence file on each node manually, following the guidelines of section Installing the Stream license.

Additionally, on each node, you will need to open the ports used for Akka_HA and Akka_MGMT, which are by default 25520 and 8558:

$ firewall-cmd --permanent --add-port=25520/tcp
$ firewall-cmd --permanent --add-port=8558/tcp

Reload the firewall configuration with:

$ systemctl restart firewalld

Restart the Stream service on each one of the nodes:

$ systemctl restart stream