5.1. Running the Gateway Container

5.1.1. Command Line Options

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

docker run registry.susshi.io/susshi:21.05 -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 send to stderr only.
         -f  Specify alternative configuration file. Default is /opt/wasabi/susshi/config/susshid.json.
         -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  Initialize secure internal communication (sic) with sic_psk.
         -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.2. Unprivileged User

Starting with version 20.05, all processes of the suSSHi Gateway container are changed switched to an unprivileged user named susshi a 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	Allowed range
SUSSHI_UID	UID of the unprivileged user	900	103 - 65533
SUSSHI_GID	GID of the unprivileged user	900	103 - 65533

5.1.3. 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 on 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
/opt/wasabi/susshi/config	suSSHi Gateway configuration file and registration data
/var/log/susshi	suSSHi Gateway loggings

Configuration Directory

The suSSHi Gateway container reads all its configuration from /opt/wasabi/susshi/config. This includes the configuration file described below.

When a gateway is registerd with suSSHi Chef, two additional files are written to this directory, namely ca.pem and cert-<id>.p12. These contain the secure internal communication (SIC) information for all communication between suSSHi Gateway and suSSHi Chef.

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.

5.1.4. Configuration

The suSSHi container reads configuration data from /opt/wasabi/susshi/config/susshid.json (or the file specified with -f on the command line) from the container file system, so it is important to map the configuration file into the container. 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

{
  "ChefServerUrls": {
    "default": [ "https://<susshi_chef_hostname>:8443" ]
  },
  "InstallationId": "<the installation ID>",
  "SusshidId": "<the SusshidId>"
}

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.

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.

InstallationId

The installation identifier is provided with the corresponding suSSHi installation license in the form of 1234-1234-1234-1234-1234. For the actual suSSHi identifier of your installation, see Dashboards > License.

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 4-digit string with numbers and digits as allowed characters.

5.1.5. Health Monitoring

Starting with Version 19.12, 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 http://<susshi-gateway>/susshi-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).

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