SSH Connector

ConnId/MidPoint connector for running provisioning scripts over SSH.

This connector has script execution capabilities only. It is not a complete stand-alone connector. It is designed to used together with other connectors, such as LDAP or Active Directory connectors.

Status

This connector is supportable. However, the connector is not feature-complete. Some functionality may be missing.

Configuration

Please see the source code of SshConfiguration.java for list of configuration properties. Configure host, username, the authentication credentials, and knownHosts.

The knownHosts property is required and contains trusted SSH server public keys in OpenSSH known_hosts format. It accepts multiple values or one value containing multiple lines; it is not a file path. Blank or whitespace-only lines and comments starting with # after optional indentation are ignored. At least one SSH host key entry is still required; malformed key entries are rejected. For port 22, use the hostname or IP address used in host. The server must present a matching key for the configured host and port. Missing, empty, comment-only, or invalid configuration is rejected before connecting. Verify the server key or its fingerprint through a trusted channel before configuring it; collecting a key from the network alone does not establish trust.

Upgrade note: Earlier versions accepted any server key when knownHosts was empty. Existing configurations relying on that behavior must supply verified host keys before upgrading. There is no automatic trust-on-first-use or accept-all fallback.

The argumentStyle configuration property can take following values:

argumentStyle	Example command	Description
dash	command -f foo -b bar -c	Ordinary UNIX-like command switches.
dashdash	command --fu=foo --bar=baz	The "long" argument style used by newer UNIX tools. This option is not implemented yet.
slash	command /foo /bar	Old Windows argument style.
variables-bash	fu='foo'; bar='baz'; command $foo $bar	Bash variable definition before the command.
variables-powershell	$fu='foo'; $bar='baz'; command $foo $bar	PowerShell variable definition before the command.

The handleNullValues configuration property can take the following values:

handleNullValues	Description	Combination with argumentStyle	Example where foo is null
asEmptyString	Arguments that contain a null value will be interpreted as an empty string.	dash	command -foo -bar baz
		slash	command /foo /bar baz
		variables-bash	foo=''; bar='baz'; command $foo $bar
		variables-powershell	$foo=''; $bar='baz'; command $foo $bar
asGone	Arguments that contain a null value removed from the argument list.	dash	command -bar baz
		slash	command /bar baz
		variables-bash	bar='baz'; command $foo $bar
		variables-powershell	$bar='baz'; command $foo $bar

Tests

Run the local regression tests with mvn test, or build the connector with mvn verify. These tests do not require an SSH server.

The existing SshUnixTest and SshWindowsTest tests require a specially configured live server and are excluded from the default test run. Configure the host, account and credentials in the selected test class, and provide a UTF-8 known_hosts file containing independently verified keys for that server. Select a live test explicitly, for example in PowerShell:

mvn.cmd '-Dtest=SshUnixTest' '-Dssh.test.knownHostsFile=C:\ssh-test\known_hosts' test

Use SshWindowsTest instead for a Windows server configured with PowerShell as its default shell. The live tests fail before connecting if the known-hosts file is missing or invalid.

Public SSH integration tests

Run mvn -Pintegration-tests verify to include and execute also integration SSH tests using the bundled src/test/resources/known_hosts/github.known_hosts fixture. No credentials or additional parameters are needed.

Limitations

• Only "execution mode" of SSH is supported. The connector will create SSH connection, authenticate, execute the command and tear down the connection. This is slow, but it is reliable. The "session mode" would allow to set up a session and keep it open. This is supposed to be much faster, as we would avoid connection overhead. However, that would also mean that we will have problems of detecting where command execution ends, the commands may influence session state, this may be shell-specific (different method for bash and powershell), etc.

• Script language parameter is ignored. However, for future compatibility, we recommend using following values:

  Script language value	Description
  sh	Generic UNIX shell. No specific shell is assumed.
  bash	Bourne Again Shell, the GNU classic.
  cmd	Windows cmd.exe shell.
  powershell	Windows PowerShell.

  Setting of script language does not influence the shell will be executed when SSH connection is opened. That is influenced by server or account setting, the client (connector) will not change that. This setting may influence how the connector interprets the command-line or script output.

• The connector returns the output (stdout) of the script. The error stream (stderr) is not processed by the connector yet.

• The connector cannot process script exit code. SSH provides the exit code, but there is no good way how to pass the exit code through the ConnId layer.

If you do not like the limitations, we will be more than happy to accept a contribution.