SSH channel plugin¶
This channel plugin manages communications with execution environments that are accessed via SSH.
This plugin has a configuration file (
sshee.yaml by default) that describes
the host, port, ssl_context, trusted_authorities, and logfile to use.
It can also enable insecure logins.
The configuration file also specifies pools.
If no configuration file is found it will default to the following values:
apiVersion: opentestfactory.org/v1alpha1 kind: SSHServiceConfig current-context: default contexts: - name: default context: port: 443 host: 127.0.0.1 ssl_context: adhoc eventbus: endpoint: https://127.0.0.1:38368 token: invalid-token targets:  pools:
contexts lists the available contexts. Contexts have a
name and a
context. Each context is described by the following items:
host(required): the host the service will bind to (a hostname or an IP address).
port(required): the port the service will listen to (a number).
adhoc, a list of two items (certificate file path and private key file path), or
disabled(not recommended, will switch to plain HTTP).
trusted_authorities(optional): a list of public key files and/or directories containing public key files, used for token validation.
enable_insecure_login(optional): allow for insecure (token-less) logins, if set to
true(by default, insecure logins are disabled).
insecure_bind_address(optional, only used if
enable_insecure_loginis set to
true): insecure logins, if enabled, are only allowed from a given address (
eventbus(required): the event bus to use. A dictionary with two required entries,
token, and an optional entry,
targets(required): a list of targets which are groups specified in
current-context specifies which context entry to use. There can be any number of
contexts specified in the configuration file, but there must be one and only one
The current context must be in the list of contexts.
pools lists the available groups of execution environments. Each group (a pool)
describes one or more execution environment.
Each execution environment is described by the following (possibly optional) items:
hosts: a host name (a string) or a list of host names (a list of strings), required.
username: a username on the execution environment (a string), required.
tags: what capabilities it provides (a list of strings), required. Amongst those capabilities, there must be one and only one of
windows. If that is not the case, the execution environment will be ignored.
port: a port (a number), 22 by default.
script_path: where to put temporary scripts (a string),
'/tmp'by default for
key_filename: a file path (a string), required if using key authentication.
passphrase: a passphrase (a string), required if using key authentication and key has a passphrase.
password: a password (a string), required if using password authentication.
ssh_host_keys: a file path (a string), required if there is a list of allowed incoming hosts (typically specified if using the default missing host key policy, which is to reject unknown incoming connections).
missing_host_key_policy: a string, either
namespaces: a string, a comma-separated list of namespaces (
You cannot specify both
password at the same time. Execution
environments with an incorrect specification are ignored.
namespaces specifies the namespace(s) the execution environment is accessible from.
It is a comma-separated list of namespace names or
'*', in which case the execution
environment will be accessible from all namespaces.
A SSH channel requires
pools entries in order to prepare and dispatch execution commands.
In the following example the current context,
default, can handle execution
requests with a
runs-on statement that is either
[ssh, linux], or
[linux, ssh]. It cannot handle execution requests with other tags.
It cannot handle
runs-on statements that are either
[ssh, windows], or
[windows, ssh] due to the fact that the
demo_target group is not specified in the
apiVersion: opentestfactory.org/v1alpha1 kind: SSHServiceConfig current-context: default contexts: - name: default context: port: 443 host: 127.0.0.1 ssl_context: adhoc logfile: sshee.log eventbus: endpoint: https://127.0.0.1:38368 token: invalid-token targets: [ssh_targets, ssh2_targets] pools: demo_target: - host: demo.example.com username: demo password: 1234 tags: [ssh, windows] ssh_targets: - host: dummy.example.com username: user password: secret tags: [ssh, linux] namespaces: '*' ssh2_targets: - host: host.example.com port: 22 username: alice ssh_host_keys: /data/ssh/known_hosts key_filename: /data/ssh/example.pem missing_host_key_policy: reject tags: [ssh, linux] namespaces: ns1,ns2 - hosts: [foo.example.com, bar.example.com] port: 22 username: bob ssh_host_keys: /data/ssh/known_hosts key_filename: /data/ssh/secret.pem passphrase: secret missing_host_key_policy: auto-add tags: [ssh, linux]
The ssh channel uses non-interactive sessions. By default,
sshd only exposes a basic set of environment variables.
There are two ways to overcome this:
SetEnvstatements in your
/etc/ssh/sshd_configconfiguration file (for example
- Enable the
PermitUserEnvironment(set it to
yes, and restart your ssh server). That way, in the account you connect to with ssh, you can add a
~/.ssh/environmentwith your variables (or
BASH_ENV, as above)
python3 -m opentf.plugins.sshee [--context context] [--config configfile]
This module exposes one endpoint:
Whenever calling this endpoint, a signed token must be specified
This header will be of form:
Authorization: Bearer xxxxxxxx
It must be signed with one of the trusted authorities specified in the current context.