Deprecating the DockerRun backend (since 0.4)¶
0.4 ContainerSSH received a generalized Docker backend and we are deprecating the
dockerrun backend from version
0.3.1 and earlier. We are adding this new backend because we are changing several default values to options which could cause security problems if the old configuration was used. Version
0.4 still includes support for the
dockerrun backend, but log a warning when used:
You are using the dockerrun backend deprecated since ContainerSSH 0.4. This backend will be removed in the future. Please switch to the new docker backend as soon as possible. See https://containerssh.io/deprecations/dockerrun for details.
This page explains how to switch to the new backend.
Changing the configuration structure¶
The new configuration is structured into 3 components:
docker: connection: # These options were on the root level of the dockerrun configuration. host: cacert: cert: key: execution: # These options are moved here from the old dockerrun -> config option. container: # ... host: # ... network: # ... platform: # ... containername: "" # Subsystems that can be requested. subsystems: sftp: /usr/lib/openssh/sftp-server # the "disableCommand" option has been removed and is configured in the # "security" option. # Pick an image pull policy from "Always", "IfNotPresent" or "Never". See below. imagePullPolicy: "IfNotPresent" # Execution mode, see below. mode: connection # Idle command for the new "connection" mode, see below. idleCommand: - "/bin/sh" - "-c" - "sleep infinity & PID=$!; trap \"kill $PID\" INT TERM; wait" # Shell command for the new "connection" mode, see below. shellCommand: - "/bin/bash" # Path to the new ContainerSSH Guest Agent. agentPath: "/usr/bin/containerssh-agent" # Disable the ContainerSSH guest agent. disableAgent: true timeouts: # This section replaces the dockerrun -> config -> timeout option. # Timeout for a container to start. containerStart: 60s # Timeout for a container to stop. containerStop: 60s # Timeout for a shell or command to start. commandStart: 60s # Timeout for HTTP calls http: 15s # Timeout for signal requests signal: 60s # Timeout for window change requests window: 60s
The new execution modes¶
docker backend supports two execution modes:
session. The old
dockerrun backend worked identical to the
session mode, where each command execution within an SSH connection would cause a new container to be started.
connection mode, on the other hand, starts a container with an idle command from the configuration and then uses the
docker exec facility to launch commands.
connection mode the pods are launched with the command specified in
idleCommand as a command. The purpose of this command is to keep the pod alive and wait for a
TERM signal. Any commands (shell, etc.) will be launched similar to how you would use
docker exec to run an additional command in the pod. When a shell is requested the
shellCommand parameter is used.
connection execution mode means that the
ENTRYPOINT settings from the container image or the configuration are ignored. If you are switching from the
dockerrun backend and used the
CMD as a security measure it is strongly recommended that you configure the
shellCommand options properly.
The guest agent¶
ContainerSSH 0.4 also includes support for the new ContainerSSH Guest Agent that enables support for various features the Docker API does not provide, such as sending signals to processes.
The agent must be included into the guest image in order to work. When the agent is included it can be configured as follows:
docker: execution: # Path to the new ContainerSSH Guest Agent. agentPath: "/usr/bin/containerssh-agent" # Disable the ContainerSSH guest agent. disableAgent: true
The agent is enabled by default, you should explicitly disable it if you want to run an image that doesn't have an integrated agent.
Image pull policy¶
Docker has added ContainerSSH as an Open Source Community Application. Pulls to
containerssh/containerssh and the default guest image
containerssh/containerssh-guest-image are excluded from the rate limits.
docker: execution: # Pick an image pull policy from "Always", "IfNotPresent" or "Never". See below. imagePullPolicy: "IfNotPresent"
The following options are supported:
- Always pulls images. This is the same behavior as the
- Pull image if it is not locally present, has no image tag, or has the
- Never pulls the image. If the image is not locally present the execution will fail.
disableCommand option was added to ContainerSSH to prevent connecting users to run a custom application. This filled a similar role to the
ForceCommand option in OpenSSH: it prevented connecting users to launch custom commands.
However, this command was separately implemented in the
kuberun and in the
dockerrun backend. This was not maintainable, so it was moved into the
security module and can be configured as follows:
security: command: mode: disable