SSH hook
Sarus also includes the source code for a hook capable of enabling SSH connections inside containers. The SSH hook is an executable binary that performs different ssh-related operations depending on the argument it receives from the runtime. For the full details about the implementation and inner workings, please refer to the related developer documentation.
Hook installation
The hook is written in C++ and it will be compiled along with Sarus if the
ENABLE_SSH=TRUE
CMake option has been used when configuring the build (the
option is enabled by default). The Sarus installation scripts will also
automatically install the hook in the <CMAKE_INSTALL_PREFIX>/bin
directory.
A custom SSH software (statically linked Dropbear) will also be built and installed in the
<CMAKE_INSTALL_PREFIX>/dropbear
directory. This directory must satisfy the
security requirements for critical
files and directories.
Sarus configuration
The SSH hook must be configured to run as a prestart hook. It expects to
receive its own name/location as the first argument, and the string
start-ssh-daemon
as positional argument. In addition, the following
environment variables must be defined:
HOOK_BASE_DIR
: Absolute base path to the directory where the hook will create and access the SSH keys. The keys directory will be located in<HOOK_BASE_DIR>/<username>/.oci-hooks/ssh/keys
.PASSWD_FILE
: Absolute path to a password file (PASSWD(5)). The file is used by the hook to retrieve the username of the user.DROPBEAR_DIR
: Absolute path to the location of the custom SSH software."SERVER_PORT
: TCP port on which the SSH daemon will listen. This must be an unused port and is tipically set to a value different than 22 in order to avoid clashes with an SSH daemon that could be running on the host.
The following is an example of OCI hook JSON configuration file enabling the SSH hook:
{
"version": "1.0.0",
"hook": {
"path": "/opt/sarus/bin/ssh_hook",
"env": [
"HOOK_BASE_DIR=/home",
"PASSWD_FILE=/opt/sarus/etc/passwd",
"DROPBEAR_DIR=/opt/sarus/dropbear",
"SERVER_PORT=15263"
],
"args": [
"ssh_hook",
"start-ssh-daemon"
]
},
"when": {
"annotations": {
"^com.hooks.ssh.enabled$": "^true$"
}
},
"stages": ["prestart"]
}
Sarus support at runtime
The command sarus ssh-keygen
will call the hook without creating a
container, passing the appropriate arguments to generate dedicated keys to be
used by containers.
The com.hooks.ssh.enabled=true
annotation that enables the hook is automatically
generated by Sarus if the --ssh
command line option is passed to sarus run.
Important
The SSH hook currently does not implement a poststop functionality and
requires the use of a private PID namespace to cleanup the Dropbear daemon.
Thus, the hook currently requires the use of a private PID namespace
for the container. Thus, the --ssh
option of sarus run implies
--pid=private
, and is incompatible with the use of --pid=host
.