3. Software Installation

3.1. Prerequisites

3.1.1. Operation System

suSSHi software ships in form of multi-arch (X86_64, ARM64) Docker containers and should potentially run on all Systems that support Docker containers. We recommend to update your system to the latest version along with the latest Docker version to ensure full support of all features bundled in the containers.

3.1.2. Docker Runtime

Docker containers can operate in a variety of different installations, from simple, manual Docker commands enriched with Docker Compose, to highly integrated container platforms like Kubernetes and others.

In this manual, we would like to focus on an installation with Docker Compose and explain step by step the installation of the individual suSSHi components based on Ubuntu Server 26.04 LTS with Docker installed.

3.1.3. Database

The suSSHi Suite requires a PostgreSQL database to store all configuration data, user accounts, access rules and so on.

While suSSHi Chef, the suSSHi Gateway and suSSHi Proxy are delivered only as Docker containers, the database can be installed as a standard software package on any supported system or also as a Docker container.

In the following installation examples, we use a PostgreSQL database container. The container is prepared for easy deployment and grants the specified user full access by default, including the permission to create extensions.

So in case you plan to install a database in a classic package deployment, please use the following steps to prepare the database for suSSHi Chef:

postgres=# CREATE USER chef_production PASSWORD "secret" VALID UNTIL "infinity";
postgres=# CREATE DATABASE chef_production OWNER=chef_production;
postgres=# \c chef_production;
chef_production=# CREATE EXTENSION plpgsql;
chef_production=# CREATE EXTENSION hstore;
chef_production=# CREATE EXTENSION btree_gin;
chef_production=# CREATE EXTENSION pg_trgm;
chef_production=# GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO chef_production;

3.2. Docker Containers

For hosting the suSSHi Docker containers, persistent volumes are required to store some small sized configuration files, the deep inspection session logs and audit trails.

All libraries and dependent software packages required for the suSSHi software are included in the Docker containers, resulting in minimal dependency on the hosting OS.

3.3. suSSHi Docker Registry

suSSHi Docker images can be downloaded from the suSSHi software registry hub.docker.com/wasabi-elements.

When you are not allowed to directly connect to the internet hosted registry from the servers where you want to install suSSHi, you can configure Docker to use a proxy server. Learn now to configure Docker to use a proxy server here.

If using a proxy server is not an option due to security policies or other restrictions, you can to download the suSSHi software from the official suSSHi software registry and copy it into your company’s internal private registry to use it from there.

3.3.1. Docker Images

The Docker images on our private registry hub.docker.com/wasabi-elements are named according to the following conventions:

Content	Path
suSSHi Chef	`hub.docker.com/wasabi-elements/susshi-chef:<version>`
suSSHi Gateway	`hub.docker.com/wasabi-elements/susshi:<version>`
suSSHi Proxy	`hub.docker.com/wasabi-elements/susshi-proxy:<version>`

3.4. Installation

3.4.1. Preparation

Linux Preparation

For the sake of simplicity, we use the superuser (root) for all steps of this example installation. In a productive setup, you would perform some steps with an unprivileged user, depending on your requirements.

Please install the latest Ubuntu 26.04 LTS server image on a virtual server or hardware with sufficient disk space and CPU / RAM resources and install Docker.

Note

In this tutorial we install docker-ce, the certified release provided by docker.com. It includes Docker Compose as a built-in plugin (docker compose).

$ apt-get update && apt-get upgrade
$ curl -fsSL https://get.docker.com | sh

For detailed installation instructions see the Docker documentation.

In our example, we use netplan to configure two additional IP addresses used for suSSHi Chef and suSSHi Gateway:

192.168.20.51 docker-host
192.168.20.52 susshi-chef
192.168.20.53 susshi-gateway

Additionally we use the following local DNS servers:

192.168.15.11
192.168.15.12

It is not necessary to run the services on different IP addresses, but please note that other services (such as the SSH daemon server) may already bound to the server. At the time of writing, OpenSSH server shipped with Ubuntu listens on all local addresses per default. Therefore, you might want to change this setting in /etc/ssh/sshd_config:

/etc/ssh/sshd_config

ListenAddress 192.168.20.51

Please prepare /etc/netplan/50-cloud-init.yaml and /etc/hosts and adjust all IP addresses and the interface name according to your setup. In the Docker Compose configuration, we will reference to this IP addresses later.

/etc/netplan/50-cloud-init.yaml

network:
    ethernets:
        ens160:
            addresses:
              - 192.168.20.51/24
              - 192.168.20.52/24
              - 192.168.20.53/24
            gateway4: 192.168.20.1
            nameservers:
                addresses:
                  - 192.168.15.11
                  - 192.168.15.12
                search:
                  - lab.example.org
            optional: true
    version: 2

/etc/hosts

168.20.51      <server-name>
168.20.52      susshi-chef
168.20.53      susshi-gateway

Please run netplan apply or reboot the server to apply the changes in the cloud-init configuration.

3.4.2. Persistent Data

All data inside a container is non-persistent and will be lost if you recreate the container. Therefore, it is important to store all data that should survive a recreate outside of the container. This is what persistent volumes are for.

There are several ways to provide persistent volumes to Docker containers running on a Docker host. One simple option is to use bind mappings from directories that exist on the Docker host into containers. Another option is to create named volumes and map them into the containers.

In this sample installation, we use bind mappings to simplify the example a bit.

Directory Structure

We will utilize the following directory structure:

Path

Description

/opt/wasabi/docker

Location of the compose.yaml file.

/opt/wasabi/susshi-chef/log

Location of the suSSHi Chef Logs.

/opt/wasabi/susshi-chef-db/data

suSSHi Chef Database (PostgreSQL) data directory.

/var/log/susshi

Location of the suSSHi Gateway Loggings.

Please create a base directory where we will create some subdirectories later:
$ mkdir -p /opt/wasabi
$ mkdir -p /var/log/susshi

3.4.3. Docker Compose

All Docker Compose configuration is stored in one single file named compose.yaml. To make the installation a bit clearer, we use environment variables set in a second file named .env in the same directory with compose.yaml.

$ cd /opt/wasabi
$ mkdir docker

Please prepare the .env file with the corresponding values and adjust the placeholders with your preferred / currently available version:

.env

BASEDIR=/opt/wasabi
IP_CHEF=192.168.20.52
IP_GATEWAY=192.168.20.53
DB_SERVER=susshi-chef-db
DB_DATABASE=chef_production
DB_USERNAME=chef_production
DB_PASSWORD=<secure_password>
RELEASE_DB=<release_db>
RELEASE_CHEF=<release_chef>
RELEASE_GATEWAY=<release_gateway>
SUSSHI_CHEF_URL=<susshi_chef_url>

Next, we will see how we can spin up the required containers one by another.

3.4.3.1. suSSHi Chef Database

In the first step we will use docker compose to create a Postgres database container. Please fill the file compose.yaml file with the following content:

compose.yaml

version: '3.5'
services:

  susshi-chef-db:
    container_name: 'susshi-chef-db'
    image: 'postgres:${RELEASE_DB}'
    command: 'postgres'
    restart: unless-stopped
    environment:
      - POSTGRES_DB=${DB_DATABASE}
      - POSTGRES_USER=${DB_USERNAME}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - ${BASEDIR}/susshi-chef-db/data:/var/lib/postgresql/data
      - /dev/log:/dev/log

Let’s see if this works:

$ docker compose up

This should initiate the download and start a shiny new and unused PostgreSQL database container from hub.docker.com. If all goes well, you should see some log messages and not return to the console.

If you have checked all the logs and nothing looks weird, you can stop the container for now by pressing CTRL + C and proceed with the next step.

3.4.3.2. suSSHi Chef

In this step, we will add the susshi-chef service to our compose.yaml file:

compose.yaml (add)

  susshi-chef:
    container_name: 'susshi-chef'
    image: "hub.docker.com/wasabi-elements/susshi-chef:${RELEASE_CHEF}"
    restart: unless-stopped
    environment:
      - DB_SERVER=${DB_SERVER}
      - DB_DATABASE=${DB_DATABASE}
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}
    ports:
      - "${IP_CHEF}:443:443"
      - "${IP_CHEF}:6514:6514"
      - "${IP_CHEF}:8443:8443"
      # This is optional if you like to do suSSHi Chef a redirect to HTTPS when accessed on HTTP:
      - "${IP_CHEF}:80:80"
    depends_on:
      - susshi-chef-db
    volumes:
      - ${BASEDIR}/susshi-chef/logs/nginx:/opt/wasabi/susshi-chef/log/nginx

Next, you can run docker compose up again to see what happens:

$ docker compose up

You should see how suSSHi Chef initializes the database and starts the suSSHi Chef WebUI.

If everything goes well so far, we should be able to run suSSHi Chef and the database in background from now on. So please stop Docker Compose by hitting CTRL + C and restart Docker Compose with the detach mode flag -d:

$ docker compose up -d

You should now be able to access suSSHi Chef with your browser on https://192.168.20.52 (or the corresponding DNS entry you’ve already made). suSSHi Chef installs a self-signed certificate to provide HTTPS access. A certificate signed by your own or an official CA can be installed later.

Try to login with the default user admin and the initial password ChangeMe&1234.

You should see the web interface and a warning message that the license is missing.

Please move ahead to System > Preferences and paste the license blob into the License Data field and click Update.

Afterwards, the error should disappear. For details about the license, see Dashboards > License.

3.4.3.3. suSSHi Gateway

In the last step we fire up a gateway and register it to suSSHi Chef.

Please append the following content to compose.yaml:

compose.yaml (add)

  susshi:
    container_name: 'susshi'
    image: "hub.docker.com/wasabi-elements/susshi:${RELEASE_GATEWAY}"
    restart: unless-stopped
    depends_on:
      - susshi-chef
    ports:
      - "${IP_GATEWAY}:22:22"
    environment:
      - SUSSHI_CHEF_URL=${SUSSHI_CHEF_URL}
    volumes:
      - ${BASEDIR}/susshi/logs:/var/log/susshi

Please switch to suSSHi Chef UI and perform the following steps:

Create a Partition

Navigate to System > Partitions > New, enter a name (it can be changed at any time later) and assign at least one administrator (in our case “Administrator”) to the list of assigned admin users on the second tab.

Finally press Create.
Add a suSSHi Gateway to the Partition

Navigate to Partition > Gateways > New and enter a hostname (for now we name it susshi-gateway-01) and press Create.

From the following overview page, copy the SUSSHI_CHEF_URL displayed under “Configuration”.

Paste the copied value into the .env file as the value for SUSSHI_CHEF_URL.
Activate the configuration

You may have noticed the orange xx pending changes sign at the top of the navigation menu. Please press it and click Activate on the following page.
Run the suSSHi Gateway

Now we are ready to start the suSSHi Gateway. The gateway will automatically connect to suSSHi Chef using the SUSSHI_CHEF_URL, initialize the secure internal communication and download the configuration.
```
$ docker compose up -d
```
Navigate to Partition > Gateways in order to verify the status of the suSSHi Gateway.

The status should be Running and No Changes Pending.

Tip

Download compose.yaml for reference.

3.5. Updates

Updating the software is quite easy due to the container architecture, because basically only the existing container image reference has to be replaced by a newer version. Please always refer to the Release Notes to find out from which previous container versions an upgrade path exists.

In general, the different versions of suSSHi Chef, suSSHi Gateway and suSSHi Proxy are downward compatible with each other, so that an update can be done step-by-step and possible redundancies can be considered.

Note

Unfortunately, we found that some Linux systems (e.g. SLES12) have a problem with the update via docker compose up -d and do not correctly release the bound resources (especially the IP address) of the running container. As a result, when starting the new container, it is not possible to allocate exactly these resources. In this case it helps to shut down and remove the container with docker compose stop susshi-chef and docker compose kill susshi-chef.

3.5.1. suSSHi Chef

It is generally recommended to always upgrade the suSSHi Chef container first. Please note that when upgrading the version of the suSSHi Chef container, changes are often made to the database, so-called database migrations. As a consequence, additional suSSHi Chef instances accessing the same database running older versions may not work correctly. If there are several suSSHi Chef instances, it is recommended to update them together.

It is also recommended to make regular backups of the database. If there are problems updating the suSSHi Chef container, the system will try to automatically rollback the database migrations to the original state, but if this fails for some reason, it is good to have a backup!

Updating to a newer version can easily be done by rewriting the referenced image in the .env file (RELEASE_CHEF) to a newer version and calling docker compose up -d, which loads the new image and recreates the container with that image.

3.5.2. suSSHi Gateway

Updating suSSHi Gateway is the easiest due to the low dependencies. Again, updating to a newer version can easily be done by updating the referenced image in the .env file (RELEASE_GATEWAY) to a newer version and calling docker compose up -d, which loads the new image and recreates the container with that image.

3.5.3. suSSHi Proxy

Updating the suSSHi Proxy is also very simple because there are no direct dependencies on other services. Just replace the referenced image with a newer version or, if you used the latest tag, run a docker pull <image>:latest to get an updated image with the same tag.