3. Software Installation

3.1. Prerequisites

3.1.1. Operation System

suSSHi software ships in form of Docker containers and should potentially run on all Linux systems that support Docker containers. We recommend installing the latest version of your preferred Linux distribution 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 Docker Swarm, 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 20.04 LTS with Docker installed.

3.1.3. Database

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;

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 registry.susshi.io, specifying the individual Installation ID and a provided password.

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 registry.susshi.io are named according to the following conventions:

Content	Path
suSSHi Chef	`registry.susshi.io/susshi-chef:<version>`
suSSHi Gateway	`registry.susshi.io/susshi:<version>`
suSSHi Proxy	`registry.susshi.io/susshi-proxy:<version>`

Additionally, suSSHi Proxy is available from our public registry hub.susshi.io.

3.3.2. Registry Login

Before we can pull the images, you first have to login into the private registry registry.susshi.io with your Installation ID and password provided by Wasabi Elements GmbH:

$ docker login -u <Installation ID> registry.susshi.io

But now we are finally ready to start the engines!

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 20.04 LTS server image on a virtual server or hardware with sufficient disk space and CPU / RAM resources and install Docker and Docker Compose.

Note

You may know that there are different Docker packages:

docker.io is provided by Debian/Ubuntu for the Docker releases of their official repos.
docker-ce is a certified release provided by docker.com and can also be built from source.

For this tutorial, however, we have chosen to install docker.io for the sake of simplicity.

$ apt-get update
$ apt-get dist-upgrade
$ apt-get install docker.io
$ docker login -u <Installation ID> registry.susshi.io
$ apt-get install docker-compose

Note

We found out that there are occasional problems with the docker login when the package golang-docker-credential-helpers is installed, that comes along with the docker-compose package. For that reason we perform the login to registry.susshi.io before installing Docker Compose.

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.susshi.io
            optional: true
    version: 2

/etc/hosts

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

Please reboot the server now 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 restart the container. Therefore, it is important to store all data that should survive a restart 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.

Please create a base directory where we will create some subdirectories later:

$ mkdir -p /opt/wasabi
$ cd /opt/wasabi

We will utilize the following directory structure:

Path	Description
/opt/wasabi/docker	Location of the `docker-compose.yml` file.
/opt/wasabi/susshi-chef/log	Location of the suSSHi Chef Logs.
/opt/wasabi/susshi-chef-db/data	suSSHi Chef Database (PostgreSQL) data directory.
/opt/wasabi/susshi/config	suSSHi Gateway configuration file and registration data.
/var/log/susshi	Location of the suSSHi Gateway Loggings.

3.4.3. Docker Compose

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

$ mkdir docker
$ cd 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>

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 docker-compose.yml file with the following content:

docker-compose.yml

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 docker-compose.yml file:

docker-compose.yml (add)

  susshi-chef:
    container_name: 'susshi-chef'
    image: "registry.susshi.io/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 docker-compose.yml:

docker-compose.yml (add)

  susshi:
    container_name: 'susshi'
    image: "registry.susshi.io/susshi:${RELEASE_GATEWAY}"
    restart: unless-stopped
    depends_on:
      - susshi-chef
    ports:
      - "${IP_GATEWAY}:22:22"
    volumes:
      - ${BASEDIR}/susshi/config:/opt/wasabi/susshi/config
      - ${BASEDIR}/susshi/logs:/var/log/susshi

Do not start the container at this stage, we will prepare suSSHi Chef for gateway registration first.

So 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). Please also add an SIC IP Address, suSSHi Chef later uses to communicate with the gateway - this is the IP address the suSSHi Gateway is reachable on the network (in our example it is 192.168.20.53).

Please ensure that the SIC Port is 22 and press Create.

From the following overview page, please note the fields Identifier under “Information” and PSK under “Secure Internal Communication”.

Please copy the displayed values for the next steps (or come back to this page for step 5).

Note

You can also download a prepared version of susshid.json needed in step 4 from here.
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.
Configure the suSSHi Gateway

Please create a new directory and add a file named susshid.json with the content listed below. Of course you can also copy the previously downloaded file into this directory.
```
$ mkdir -p /opt/wasabi/susshi/config
```
/opt/wasabi/susshi/config/susshid.json
```
{
  "ChefServerUrls": {
    "default": [ "https://susshi-chef:8443" ]
  },
  "InstallationId": "<Installation ID>",
  "SusshidId": "<suSSHi ID>"
}
```
Note

The Installation ID is available under Dashboards > License in Section License Information.

Register the suSSHi Gateway

In this step, we finally register the first gateway to suSSHi Chef and hereby initialize the secure internal communication based on mutual public/private key authentication. Please run the following command providing the PSK you have copied in step 2:

$ docker-compose run --rm susshi -s <PSK from step 2>

This should register the suSSHi Gateway to suSSHi Chef. The --rm option removes the temporary container after the registration.

Register the suSSHi Gateway

$ docker-compose run --rm susshi -s f58bc7b2c3d73ea546429383ee0dd91b
...
info  : [00001] (system)  suSSHi2 - susshid version 21.10.0 (Release build) started.
info  : [00001] (system)  Initializing Secure Internal Communication (SIC). Gathering gateway information ...
info  : [00001] (system)  SIC initialization completed successfully. You are now ready to run susshid in normal daemon operation.

Run the suSSHi Gateway

Now we are ready to run the suSSHi Gateway in its suggested daemon mode. Please just execute another …
```
$ docker-compose up -d
```
… and we should finally be done!

Navigate to Partiton > Gateways in order to verify the status of the suSSHi Gateway.

The status should be Running and No Changes Pending.

Tip

Download docker-compose.yml 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.