Before you can run ContainerSSH, you will need to create a configuration file. In this page you will find some quick-start configuration snippets that will work for the most common use-cases but does not give a full overview of all the features and possible configuration combinations. For more a more in-depth configuration guide you can consult reference manual.
In order to have a working ContainerSSH installation you need to define at a minimum 3 sections in your configuration file.
<SSH Configuration options>
ssh: Details about your ssh server
auth: How the users will authenticate to your server
backend+ the associated backend configuration: How the backing container that will be used by the user will be created and with what configuration (mounts etc)
The config file must end in
.json. You can dump the entire configuration file using
SSH Server configuration¶
ssh section the only mandatory field is
hostkeys which defines the private keys to be used for the server to authenticate itself to the clients.
The webhook authentication backend authenticates users by consulting an external authentication server implementing the ContainerSSH authentication API.
OAuth2 support is considered as a feature preview as it doesn't have adequate test coverate
The OAuth2 authentication backend authenticates users using any OIDC-compliant OAuth2 servers for authentication (such as KeyCloak, Microsoft Active Directory Federation Services, etc) and features explicit support for GitHub and GitHub Enterprise.
The Kerberos authentication backend authenticates users using any authentication server that implements the Kerberos protocol (such as Microsoft Active-Directory, FreeIPA etc). It supports the GSSAPI authentication method which allows users to log in without providing a password provided that a valid kerberos ticket is available on the users device. It additionally supports password authentication in case the user does not have or cannot provide a valid ticket.
All users will be logged in separate, but identical, containers (equivalent of
docker exec and
kubectl exec for the respective backend), in order to customize the resulting container on a per-user basis you'll need to use a configuration server
The Docker backend creates containers on the specified docker daemon. You can consult the Docker guide for more examples.
The Kubernetes backend creates pods inside a Kubernetes cluster. Please note the following configuration snippet assumes that ContainerSSH is running in the same Kubernetes cluster under a service account with all the required privileges. You can consult the Kubernetes guide for more examples.
- name: containerssh-user
The SSH proxy backend does not launch containers, instead it connects to a second SSH server and forwards the connections to that backend. This allows for using the audit log to inspect SSH traffic, or to dynamically forwarding connections using the configuration server.
# Add the backend server here
# Set the following option to true to reuse the connecting user's username.
# Or specify a username manually
# Specify the password
# Or the private key. This can reference a file or be added directly.
-----BEGIN OPENSSH PRIVATE KEY-----
# Provide all fingerprints of the backing SSH server's host keys: