5.1. Running the Gateway Container

5.1.1. Add a New Gateway

Before running an instance of a suSSHi Gateway container, you need to add it as a new gateway in suSSHi Chef and copy the provided SUSSHI_CHEF_URL for the new gateway, which is needed to configure the suSSHi Gateway container.

Please check here for detailed instructions on how to add a new gateway in suSSHi Chef.

Each suSSHi Gateway container instance must be registered as a new gateway in suSSHi Chef, because the suSSHi Gateway container needs to register itself with suSSHi Chef on startup and download the configuration from there. And each gateway needs to have its own unique identifier (SusshidId) to guarantee correct communication and reporting (e.g. unique session IDs).

5.1.2. Command Line Options

The container’s default entry-point is the suSSHi Gateway daemon, which can be configured with a number of command line options.

To display the available command line options and a short usage help, run the container with the -h option:

docker run –rm hub.docker.com/wasabi-elements/susshi:26.05.0 -h

Usage: susshid [-dDFe] [-f config_file.json] [-i susshid-identifier] [-p port] [-w sec] [-r retries] [-W sec]
       susshid [-d]    [-f config_file.json] [-i susshid-identifier] -s sic_psk

         -d  Debug level, multiple -d (up to 3) increases the debug level.
         -D  Don't fork main process or sessions into background. This should be used for debugging only.
             Only one single client connection is handled before quitting.
         -e  Output system messages on stderr as well. All other messages are sent to stderr only.
         -f  Specify configuration file in JSON format. This is normally not required, use option -s instead.
         -F  Fork into background. Main process forks into background. Default is to stay in foreground.
         -h  This help.
         -i  Overwrites the susshid-identifier found in configuration file.
         -p  Overwrites the listen port in configuration file.
         -P  Overwrites default listen port (80) for HTTP health probe interface.
         -r  On startup, retry n times to connect to susshi-chef. Default is 3 retries.
         -s  Provide suSSHi Chef URL for secure internal communication (sic). You may use SUSSHI_CHEF_URL instead.
         -w  On startup, wait n seconds before trying to connect to susshi-chef. Default is 15 seconds.
         -W  On startup, wait n seconds between retries. Default is 5 seconds.

         --suspend    Suspend monitoring   - return 423 on monitor-server URL.
         --unsuspend  Unsuspend monitoring - return to normal monitor operation.

5.1.3. Configuration

5.1.3.1. SUSSHI_CHEF_URL Environment Variable

The suSSHi Gateway container can be configured with the SUSSHI_CHEF_URL environment variable, which contains all information to connect to suSSHi Chef.

The suSSHi Gateway connects to the specified suSSHi Chef server on startup, initializes the secure internal communication (SIC), registers itself and downloads the configuration from suSSHi Chef.

This is the recommended way to configure the suSSHi Gateway, because it is simple and does not require any configuration file to be created and mapped into the container.

The SUSSHI_CHEF_URL environment variable is displayed in suSSHi Chef after creating a new gateway and can be copied from there.

In the container configuration (e.g. in a Docker Compose file), the environment variable can be set like this or in any other way to set environment variables in a container:

compose.yaml

services:
  susshi-gateway:
    image:  hub.docker.com/wasabi-elements/susshi:26.05.0
    environment:
      - SUSSHI_CHEF_URL=https://susshi-chef.example.org/...

5.1.3.2. Configuration File

If you want to use a configuration file instead of providing the SUSSHI_CHEF_URL environment variable, you can create a JSON file with the necessary configuration information for the suSSHi Gateway and map it into the container and specify the path with the -f option.

The file is in standard JSON format, so it is a bit picky during syntax checking.

Syntax

There are only a few keywords that are important for configuring the suSSHi Gateway daemon, since most of the configuration is downloaded from suSSHi Chef and should not be configured in the local configuration file during normal setup.

A regular configuration file looks like this:

susshid.json

{
  "SusshidId": "0001",
  "SicPsk": "6bdaf9cdb3c80bf9f51fa7f52aa7f84e",
  "SicSpki": "sha256::6SVkS3+wigHWxDK8EaGL3sBND9h5PHRwzfj0Bl6oYZA=",
  "ChefServerUrls": {
    "default": [ "https://susshi-chef.example.org" ]
  }
}

The following keywords must be provided in the configuration file if you do not provide the SUSSHI_CHEF_URL environment variable and can be obtained from the suSSHi Chef gateway page:

SusshidId The suSSHi Gateway identifier (SusshidId) identifies each single gateway with its own unique ID. This is very important to guarantee correct communication and reporting (e.g. unique session IDs). Normally, suSSHi Chef provides a new unique gateway ID when a new gateway is configured, but this can also be set manually if desired. The ID is a string of exactly 4 characters.

SicPsk The secure internal communication (sic) pre-shared key (PSK) is used for authentication and encryption of the communication between the suSSHi Gateway and suSSHi Chef. The PSK is a string of exactly 32 hexadecimal characters (128 bit key).

SicSpki The SPKI is used for validation of the suSSHi Chef server certificate in the communication between the suSSHi Gateway and suSSHi Chef and prevents a man-in-the-middle attack. The SPKI is a string in the format sha256::<base64-encoded SPKI hash>, where the SPKI hash is the SHA-256 hash of the SPKI of the suSSHi Chef server certificate, encoded in base64.

ChefServerUrls

suSSHi Gateway connects to one or multiple endpoints to

register with suSSHi Chef and download the configuration on startup,
authenticate, authorise and obtain all session related configuration during the session setup,
send reports to suSSHi Chef at the beginning, on a regular basis and at the end of a session.

The ChefServerUrls option supports different sub-keywords for the different use-cases and one default keyword to use the same URL for all three purposes:

default

Sets the default URL for suSSHi Chef. The array can contain multiple entries so that the gateway iterates over the specified list until one of the entries is reachable.

This default URL is used for all three purposes (registration, session management and reporting) if the specific sub-keywords are not specified.

gateway: Configure the suSSHi Chef URL for registration and configuration download. Array can contain multiple entries, so the gateway iterates over the specified list until one of the entries is reachable. If not specified, the default entries are used.

session: Configure the suSSHi Chef URL for session authentication, authorisation and all session related configurations. The array can contain multiple entries so that the gateway iterates over the specified list until one of the entries is reachable. If not specified, the default entries are used.

report: Configure the suSSHi Chef URL for session reports. The array can contain multiple entries, so the gateway iterates over the specified list until one of the entries is reachable. If not specified, the default entries are used.

5.1.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 Gateway 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 for the mapped volumes.

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

The suSSHi Gateway container uses the following directory structure, which should be mapped to a persistent volume:

Path	Description
`/var/log/susshi`	suSSHi Gateway loggings
`<path>/susshid.json`	(optional) suSSHi Gateway configuration file

Logging Directory

The suSSHi Gateway creates a lot of logging information depending on the settings in the access profiles that you apply to the access rules. These logging files should not remain in the container, but instead be written to a persistent volume. Please make sure that the mapped volume is large enough to hold a bunch of logs over days and months.

Configuration Directory

The suSSHi Gateway container normally does not require any configuration file to be mapped into the container, because the suSSHi Gateway automatically registers with suSSHi Chef on startup with the provided SUSSHI_CHEF_URL.

As an alternative to providing the SUSSHI_CHEF_URL, you can also provide a configuration file with the necessary information for the suSSHi Gateway to register with suSSHi Chef. In this case, the suSSHi Gateway container must be started with the -f option to specify the configuration file with the path it is mapped in to the container.

5.1.5. Unprivileged User

All processes of the suSSHi Gateway container are 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 user susshi.

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

Name	Description	Default
SUSSHI_UID	UID of the unprivileged user	900
SUSSHI_GID	GID of the unprivileged user	900

5.1.6. Health Monitoring

5.1.6.1. Container Health Status

The suSSHi Gateway container has a built-in health monitoring mechanism, which regularly checks the health status of the container and reports it to Docker.

5.1.6.2. External Health Monitor Status

The suSSHi Gateway 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 health status can be shown with docker ps under the STATUS column. The URI of the health check is :substitution-code:https://susshi.example.org/health.

Response Codes

HTTP Return Code	State	Description
200	OK	Container is Healthy
423	-	Monitor is suspend via UI or command line
503	FAIL	Bad health, the container is in trouble
any other error code	FAIL	Bad health, the container is in trouble

Monitor Sources

By default, the monitor URI can be accessed from any source, which you can further secure by allowing only trusted IP addresses. For this purpose, the MONITOR_CLIENTS container environment variable can be used to restrict access to IP addresses or networks specified in CIDR notation. Multiple entries can be separated by space or , (comma).