Skip to content

About

MidPoint connector for running provisioning scripts over SSH

Resources

Stars

1 star

Watchers

15 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

Build and tests

The connector requires JDK 17 or later. Compilation uses --release 17 to preserve Java 17 API and bytecode compatibility on newer JDKs. Run mvn verify to compile, test, and package it. Local regression tests run by default. The legacy SshUnixTest and SshWindowsTest require external servers and are excluded from the default run. After configuring the corresponding server and test credentials, select a legacy test explicitly, for example mvn -Dtest=SshUnixTest test. To execute generated commands in a real Bash shell, also set -Dssh.test.bash=/path/to/bash. For PowerShell execution tests, set -Dssh.test.powershell=/path/to/pwsh or the path to powershell.exe for Windows PowerShell 5.1. Shell execution tests are skipped when their executable property is absent; command-generation tests always run.

Configuration

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

The knownHostsVerification switch is enabled by default and appears immediately before knownHosts in the configuration form. When enabled, knownHosts 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. 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.

Setting knownHostsVerification to false disables server host key verification and ignores knownHosts, even if it is missing or invalid. Any server key is then accepted. This removes protection against server impersonation; user authentication is still required.

Upgrade note: Earlier versions accepted any server key when knownHosts was empty. Existing configurations relying on that behavior must supply verified host keys or explicitly disable knownHostsVerification. 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

The variableTransport configuration property can take the following values:

variableTransport Description Combination with argumentStyle Example with variableTransportEnvPrefix set to CONNID_ARG_

inplace

Arguments will be moved inplace quoted in single quotes. If arguments contain secrets, consider using transport env. Single quotes in the value will be escaped by doubling them.

variables-bash

foo='value1'; bar='valueWithQuotes''Inplace'; command $foo $bar

variables-powershell

$foo='value1'; $bar='valueWithQuotes''Inplace'; command $foo $bar

env

Arguments will be set as ssh envs with the variableTransportEnvPrefix as prefix. Make sure that the server allows env passing.

variables-bash

foo=$CONNID_ARG_foo; bar=$CONNID_ARG_bar; command $foo $bar

variables-powershell

$foo=$env:CONNID_ARG_foo; $bar=$env:CONNID_ARG_bar; command $foo $bar

The variableTransportEnvPrefix configuration property sets the prefix for environment variable transport. The default value is CONNID_ARG_. For env transport, the prefix and each transported argument name must match [A-Za-z_][A-Za-z0-9_]*; the prefix cannot be empty. Bash argument names must not equal the generated transport name of another argument. For example, foo and CONNID_ARG_foo cannot be transported together with the default prefix; CONNID_ARG_foo alone is allowed. These checks exclude null-valued arguments omitted by handleNullValues=asGone and run before command generation.

With PowerShell environment transport, empty strings are assigned directly as $name='' without creating a transport environment variable. This also applies to null arguments handled as asEmptyString and preserves empty strings on Windows PowerShell 5.1. Nonempty values continue to use SSH environment transport; asGone arguments remain omitted.

Tests

Run the unit tests with mvn test, or build the connector with mvn verify. Surefire runs the unit tests; SSH integration tests require the integration-tests profile described below.

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.

Local SSH integration tests

Run mvn -Pintegration-tests verify to execute both unit tests and local SSH integration tests. Maven Failsafe runs classes named *IT in the integration-test phase and checks their results in the verify phase. SshVerificationIT starts an embedded SSH server on the loopback interface with generated keys held in memory. It requires no external SSH service, credentials, or known-hosts file.

Limitations

  • Only "execution mode" of SSH is supported. The connector will create SSH connection, authenticate, (maybe) set envs, 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), the envs may leak into other commands, 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.

  • Passing arguments as envs is only supported for variables-bash and variables-powershell argument styles. The value length is limited by the maximum env size on the server side. Windows is more restrictive than Linux.

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

About

MidPoint connector for running provisioning scripts over SSH

Resources

Stars

1 star

Watchers

15 watching

Forks

Releases

Packages

Contributors

Languages