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 built-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 built-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.