4.1. Running the Chef Container

4.1.1. Docker Container

Like all components of the suSSHi Suite, suSSHi Chef ships as a Docker container image.

suSSHi Chef Database

suSSHi Chef stores all data in a PostgreSQL database, which is not shipped with the suSSHi Chef software. The database can run in any redundancy setup. Currently, PostgreSQL version 11 and 12 are supported.

4.1.2. Environment Variables

The suSSHi Chef container requires a list of environment variables to run correctly. It is strongly recommended to provide a full configuration with Docker Compose or other container runtimes when setting up the container.

The following environment variables are supported by the container:

Environment variable

Description

Type / allowed values

Default

Required

DB_SERVER

Hostname / IP address of the DB server

String / Any reachable hostname or IP address

n/a

Yes

DB_PORT

TCP port of the Database

Integer / 1 - 65534

5432

No

DB_DATABASE

Name of the Database

String

chef_production

No

DB_USERNAME

Username of the Database

String

n/a

Yes

DB_PASSWORD

Password for given username

String

n/a

No

SECRET_KEY_BASE

Secret used for Cookie encryption etc.

String of min. 128 characters

If empty, generated on every startup

No

SECRET_KEY_OTP

Secret used for OTP encryption

String of min. 64 characters

If empty, OTP feature is disabled

No

API_REQUESTS_PER_MIN

Number of API Requests allowed per Minute

Integer

600

No

4.1.3. Command Line Options

Some special functions can be triggered by starting the suSSHi Chef container with an additional command. Currently the following commands are available:

Command

Description

backup

Creates a database backup.

list-backups

List backups found for the running version.

restore-backup

Restore a backup.

reset-admin-user

Resets the admin-user.

ssl-client-cert-off

Switch off SSL Client Certificate verification.

4.1.3.1. Backup Commands

The suSSHi Chef container provides a build-in backup and restore method for the database content, if no other backup of the PostgreSQL database exists. To use this you have to map a persistent volume to the container directory /opt/wasabi/susshi-chef/backup. Otherwise, the backups will remain inside the container and will be lost when the container is updated or killed.

backup

Creates a database backup

list-backups

List backups found for the running version

restore-backup

Restore a backup

Refer to the Backup & Restore section for more details.

4.1.3.2. Administrative Commands

reset-admin-user

Resets the admin user named admin with default password ChangeMe&1234. If no admin user named admin exists, it is created with the default password with role Super-Admin.

ssl-client-cert-off

Turn off the SSL Client Certificate verification. This can be used if the SSL Client Authentication configuration went wrong for some reason.

4.1.3.3. Unprivileged User

Starting with version 20.08, all processes of the suSSHi Chef container are automatically switched to an unprivileged user named susshi after startup. This “privilege dropping” increases the security of the container, because in case of a possible security problem an attacker would only inherit the limited rights of the susshi user.

If you prefer to use different UID/GID for the unprivileged user in the container, you can change the UID/GID by using the following environment variables, which are applied when the container starts:

Name

Description

Default

Allowed range

SUSSHI_UID

The UID of the unprivileged user

900

103 - 65533

SUSSHI_GID

The GID of the unprivileged user

900

103 - 65533

4.1.3.4. Volume Mappings

All data inside a container is non-persistent and therefore will be lost if you restart the container. Thus, it is important to store all data that should survive a restart outside of the container. A simple way to provide persistent volumes is to use bind mappings from directories existing on the Docker host into containers. Another option is to create named volumes and map them to containers.

Note

Please be aware, that all processes of the suSSHi Chef container are switched to an unprivileged user named susshi after startup (default UID 900, GID 900). So please ensure, that this UID has the correct read and write permissions on the mapped volumes.

If you upgrade an existing installation from a version earlier than 20.08, you may have to change the file permissions of the mapped volumes.

The suSSHi Chef container uses the following directory structure:

Path

Description

/opt/wasabi/susshi-chef/backup

suSSHi Chef Database Backups

/opt/wasabi/susshi-chef/log

suSSHi Chef Loggings

4.1.3.5. Health Monitor Server

As of Version 19.12, the suSSHi Chef container provides an HTTP monitor server on port 80, which can be used to query the container health status, e.g. by an external load balancer. Therefore, the container additionally exposes port 80, which has to be mapped to your external IP.

Note

The URI of the health check is http://<susshi-chef>/susshi-health{.json|.xml}.

Response Codes

A request to the health check will respond with one of the following HTTP return codes:

HTTP Return Code

State

Description

200

OK

Container is Healthy

500

FAIL

Bad health, the container is in trouble

any other error code

FAIL

Bad health, the container is in trouble

4.1.3.6. Health Recovery

Unfortunately, Docker does not provide a build-in function to restart unhealthy containers. This can be achieved by deploying the publicly available container willfarrell/autoheal beside the suSSHi Chef container on the same host.

For this, please add the following service to your docker-compose.yml:

docker-compose.yml
autoheal:
 container_name: 'autoheal'
 restart: always
 image: willfarrell/autoheal
 environment:
   - AUTOHEAL_CONTAINER_LABEL=all
 volumes:
   - /var/run/docker.sock:/var/run/docker.sock

Afterwards, start it up with docker-compose up -d.