7. Client Configuration

7.1. Compatibility

suSSHi is RFC-compliant to the highest degree and therefore requires no special SSH client. All SSH clients that are RFC-compliant should work with suSSHi without any problems.

While the suSSHi Gateway is “just” an SSH server from the client’s point of view, we only make the special demand that the gateway user, the target user and the actual target are encoded in the SSH username using a separator (different ones are possible, default is @).

All SSH connections from a client to a target are established by connecting to the gateway and provide some information about the gateway user, the target server and the target user within the SSH username.

7.2. Common Client Usage

The syntax of the “username” part has one of the following forms:

7.2.1. Standard Form

<gw_user>@<target_user>@<target_host>[:<target_host_port>][@<proxy_realm>]

Examples

johndoe@johndoe@server-01
johndoe@root@server-01:777
johndoe@root@server-01@proxy-realm1
johndoe@admin@1.2.3.4:2222@proxy-realm1

7.2.2. Short Form

If <gw_user> and <target_user> are identical, a short form can be used as follows:

<gw_user>@<target_host>[:<target_host_port>][@<proxy_realm>]

Examples

johndoe@server-01
johndoe@server-01:777
johndoe@server-01@proxy-realm1
johndoe@1.2.3.4:2222@proxy-realm1

7.2.3. Example Session

The gateway itself is specified as the target server for each client, rather than the actual target. In addition, the login user contains the gateway user, the target user and the actual target. The suSSHi Gateway then extracts this information accordingly and establishes a connection to the specified destination, depending on whether a corresponding access rule exists or not.

$ ssh -l johndoe@root@server-01 susshi-gateway.corporate.net

In this example, user John Doe has a gateway user named johndoe and wants to login to target server-01 with the target user root. This information is provided to the SSH client using the login_name option (-l). Alternatively, this information can be passed to the SSH client using a connection string.

$ ssh johndoe@root@server-01@susshi-gateway.corporate.net

The host the SSH client connects to is the suSSHi Gateway itself, susshi-gateway.corporate.net in this example.

7.2.4. Username Separator

As a default separator, you will find the @ character in many of our examples. It is the most catchy character to represent the separation. However, there are situations where this does not work since an @ character is already included in the target username, for example - think of a situation where the e-mail address is used as the login username. This is the case with some cloud providers, for example.

The following separators are therefore permitted, whereby the gateway always searches for the first occurrence of such a separator in the string and then presupposes this for the entire string!

Note

Please make sure that you always use the same separator within a username string.

Separator	Example 1	Example 2
@	johndoe@root@server-01	johndoe@root@server-01@susshi‐gateway
,	johndoe,root,server-01	johndoe,root,server-01@susshi‐gateway
+	johndoe+root+server-01	johndoe+root+server-01@susshi‐gateway
/	johndoe/root/server-01	johndoe/root/server-01@susshi‐gateway
?	johndoe?root?server-01	johndoe?root?server-01@susshi‐gateway
%	johndoe%root%server-01	johndoe%root%server-01@susshi‐gateway

7.3. SSH Agent

An SSH agent is a private key storage program used for authentication with public keys (RSA, DSA, ECDSA, ED25519) and is usually started at the beginning of a desktop or login session. By using environment variables, SSH clients can detect and use the agent automatically.

See also

For more information about the SSH agent, please see e.g. man ssh-agent.

Depending on the authentication method used towards the target server, it is recommended that your client provides an SSH agent that can be requested by the gateway (via the SSH session from client to gateway) for further authentication information towards the target.

With OpenSSH, for example, such an SSH agent exists as an independent process and has to be started by the user, depending on the operating system. For other clients, this is often integrated and handled by the client itself.

7.4. File Transfer Clients

For file transfer between client and server via SSH, the much more powerful and modern SFTP protocol has established itself alongside the older SCP protocol. While SCP simply represents a remote call of an SCP binary via an Exec session, SFTP is a real protocol extension of the SSH protocol via its so-called subsystems.

SFTP can be used not only to transfer files, but also to read directories, display and modify attributes and create directories, for example. This very powerful file transfer protocol is fully understood by suSSHi in version 3 (latest version) and can be logged in detail.

For SFTP there are several very practical and nicely designed clients with graphical user interfaces for common client operating systems such as macOS, Windows or Linux, which are of course also supported by suSSHi.

Besides SCP and SFTP, there are also clients that use SSH only as a secure tunnel like rsync or rdist. These clients are also supported by suSSHi.

7.5. OpenSSH

Just as OpenSSH holds its own as the leading SSH server, the SSH, SCP and SFTP clients of the OpenSSH suite are certainly the most frequently used clients. We have therefore given a separate section to these clients.

7.5.1. Standard OpenSSH Usage

When OpenSSH is used in conjunction with suSSHi, the destination points to the name or IP of a suSSHi Gateway and the actual SSH target is encoded in the login_name, which is specified as <gateway_user>@<target_user>@<target>:

$ ssh ‐l gateway_user@target_user@target susshi‐gateway

or simply:

$ ssh gateway_user@target_user@target@susshi‐gateway

With suSSHi Proxy

If a suSSHi Proxy is used, a proxy realm has to be added to the login_name so that suSSHi knows which configured proxy has to be used to connect to the target:

$ ssh ‐l gateway_user@target_user@target@proxyrealm susshi‐gateway

or simply:

$ ssh gateway_user@target_user@target@proxyrealm@susshi_gateway

See suSSHi Proxy for more details and examples.

7.5.2. Recommended Standard Configuration

We recommend to use at least the following settings in your /etc/ssh/ssh_config or ~/.ssh/config file:

Host *
    HostKeyAlgorithms ecdsa-sha2-nistp521,rsa-sha2-512,rsa-sha2-256
    Compression yes
    ServerAliveInterval 30

7.5.3. Simplify Access with ssh_config

For frequently accessed targets, it may be a good idea to put them in /etc/ssh/ssh_config or ~/.ssh/config as well:

Host my-frequent-target
    User gateway_user@target_user@my-frequent-target.domain
    HostName susshi.corporate.net

This way you can easily connect to the target without specifying the suSSHi Gateway and the gateway user every time:

$ ssh my-frequent-target
$ scp file my-frequent-target:/path
$ sftp my-frequent-target

Since this is not really a very flexible way, you are welcome to take a look at our special suSSHi OpenSSH client patch.

7.5.4. Recommended Settings

The OpenSSH clients receive configuration data from the following sources in the following order:

• command-line options

• user’s configuration file (~/.ssh/config)

• system-wide configuration file (/etc/ssh/ssh_config)

You can configure global and host-specific options as well. Please refer to man ssh_config for more details. Here we will discuss only a few parameters as an example of a configuration file.

Tip

The wildcard (*) ensures that the configuration is applied to all targets.

Host *
    HostKeyAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256,ssh-rsa
    ServerAliveInterval 120
    ServerAliveCountMax 5
    ForwardAgent yes

HostKeyAlgorithms

While most default settings for ciphers etc. have acceptable defaults, HostKeyAlgorithms should include only the most secure algorithms.

ServerAliveInterval

Any value greater than 0 activates a function that sends keep-alive messages to the server every <interval> second(s) within the SSH protocol. This allows to not turn off connections on network devices such as firewalls that maintain the active state of the connections, but with sometimes very short idle times.

ServerAliveCountMax

Using this option depends on your setup and network connectivity, but may help to terminate a session if the server does not respond to <count> alive messages (see above).

ForwardAgent

This parameter also depends very much on whether you have implemented rules in suSSHi whose profiles require authentication at the target server with user keys. However, since in suSSHi the permission to use agent forwarding can be blocked again by an active session, this setting does not contradict it.

7.5.5. OpenSSH Client Patch

To get a universal solution, we have implemented a patched variant of an OpenSSH client which adds three new options SusshiHost, SusshiUser and SusshiProxy (via -o or in ssh_config). With these parameters it is possible to use OpenSSH in such a way that the mostly same parameters like the suSSHi Gateway, the suSSHi Gateway user and the suSSHi Proxy realm do not always have to be specified, but can be brought in with these parameters.

Please note that other client software also uses the ~/.ssh/config user configuration file and syntax errors may occur when adding the suSSHi* options. Therefore, starting with the patch for OpenSSH 8.8 and later, you can alternatively include all hosts/options with special (and conflicting) suSSHi* options in a newly introduced configuration file ~/.ssh/susshi_config, which is loaded before the default user configuration file ~/.ssh/config. This file is ignored by all other clients.

Note

Another pretty cool thing is that for SFTP and SCP we have removed the restriction that these programs ignore or overwrite the ForwardAgent=yes option. This means that SFTP and SCP can be used even if a profile with “SSH Public Key Authentication with User Keys via Agent Forwarding” is used.

See also

The patches can be downloaded here for the respective common OpenSSH versions.

7.5.5.1. Using the patched version

From the man page coming with the patch:

SusshiGateway

Specifies the name or IP address of a suSSHi Gateway. This option allows to continue using the normal ssh syntax for login_name (‐l or <login_name> @destination) and destination and still pass the name or IP address of a suSSHi Gateway.

SusshiProxy

Specifies a proxy realm used in conjunction with a suSSHi Gateway. This option allows to continue using the normal ssh syntax for login_name (‐l or <login_name>@destination) and destination and still pass a suSSHi Proxy realm.

SusshiUser

Specifies the name of a suSSHi Gateway user. This option allows to continue using the normal ssh syntax for login_name (‐l or <login_name>@destination) and destination and still pass a suSSHi login name.

7.5.5.2. Examples

Command line

These options are now available to all SSH client programs (ssh, scp and sftp), so they can be used with -o, for example:

$ ssh -o SusshiGateway=susshi.corporate.net -o SusshiUser=gateway_user root@target
$ sftp -o SusshiGateway=susshi.corporate.net -o SusshiUser=gateway_user root@target
$ scp -o SusshiGateway=susshi.corporate.net -o SusshiUser=gateway_user file root@target:/path

Configuration file

/etc/ssh/ssh_config or ~/.ssh/config

Host *.secured.corporate.net
    SusshiGateway susshi.corporate.net
    SusshiUser gateway_user

After adding the options, SSH commands can be used as usual:

$ ssh root@target
$ sftp root@target
$ scp file root@target:/path

7.6. Other Clients

7.6.1. Ansible

By using the suSSHi OpenSSH patch, Ansible can easily reach its installation targets behind a suSSHi Gateway:

ansible.cfg

[ssh_connection]
ssh_args = -o SusshiGateway=susshi.corporate.net -o SusshiUser=ansible -o ControlMaster=auto -o ControlPersist=60s

The values for ControlMaster and ControlPersist are defaults for ssh_args and can be kept.

7.6.2. Git

Option 1 - Using the suSSHi OpenSSH patch

Using the suSSHi OpenSSH patch, Git can be run in the most flexible way by allowing a more general configuration with patterns:

.ssh/config

Host git*
   ForwardAgent yes
   SusshiGateway susshi.corporate.net
   SusshiUser gwuser

Option 2 - Per-target configuration

Without the suSSHi OpenSSH patch, you may configure the suSSHi Gateway information per target:

.ssh/config

Host git.domain
   ForwardAgent yes
   User gwuser@git@git.domain
   HostName susshi.corporate.net

7.6.3. SSHFS

SSHFS allows you to mount a remote filesystem using SFTP and works with suSSHi out of the box, as long as you don’t require to login to the target via Auth Agent Forwarding. This is because Auth Agent Forwarding is explicitly disabled, just as OpenSSH’s SFTP and SCP do without our patch.

Tip

See sshfs.c (round about line 3938):

sshfs.c

ssh_add_arg("-a");

If you simply comment out this line and compile SSHFS yourself, everything will also work with Auth Agent Forwarding.

However, another option is to specify an alternate ssh executable, that is just a script that ignores the -a option set by sshfs and sets -A when the original ssh command is explicitly called.

Example usage

$ sshfs gateway_user@target_user@target@susshi-gateway:/ ./root