7. Client Configuration
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
johndoe@johndoe@server-01 johndoe@root@server-01:777 johndoe@root@server-01@proxy-realm1 johndoe@email@example.com:2222@proxy-realm1
7.2.2. Short Form
<target_user> are identical, a short form can be used as follows:
johndoe@server-01 johndoe@server-01:777 johndoe@server-01@proxy-realm1 firstname.lastname@example.org: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
the target user
This information is provided to the SSH client using the
login_name option (
Alternatively, this information can be passed to the SSH client using a connection string.
$ ssh johndoe@root@email@example.com
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!
Please make sure that you always use the same separator within a username string.
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.
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
These clients are also supported by suSSHi.
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
$ ssh ‐l gateway_user@target_user@target susshi‐gateway
$ 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
$ 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
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
~/.ssh/config as well:
Host my-frequent-target User gateway_user@firstname.lastname@example.org 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:
user’s configuration file (
system-wide configuration file (
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.
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
While most default settings for ciphers etc. have acceptable defaults,
HostKeyAlgorithmsshould include only the most secure algorithms.
Any value greater than
0activates 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.
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).
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
-o or in
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
Please note that other client software also uses the
~/.ssh/config user configuration file and syntax errors may
occur when adding the
Therefore, starting with the patch for OpenSSH 8.8 and later, you can alternatively include all hosts/options with special
suSSHi* options in a newly introduced configuration file
~/.ssh/susshi_config, which is
loaded before the default user configuration file
This file is ignored by all other clients.
Another pretty cool thing is that for SFTP and SCP we have removed the restriction that these programs ignore or
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.
The patches can be downloaded here for the respective common OpenSSH versions.
188.8.131.52. Using the patched version
From the man page coming with the patch:
Specifies the name or IP address of a suSSHi Gateway. This option allows to continue using the normal ssh syntax for login_name (
<login_name> @destination) and destination and still pass the name or IP address of a suSSHi Gateway.
Specifies a proxy realm used in conjunction with a suSSHi Gateway. This option allows to continue using the normal ssh syntax for login_name (
<login_name>@destination) and destination and still pass a suSSHi Proxy realm.
Specifies the name of a suSSHi Gateway user. This option allows to continue using the normal ssh syntax for login_name (
<login_name>@destination) and destination and still pass a suSSHi login name.
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
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
By using the suSSHi OpenSSH patch, Ansible can easily reach its installation targets behind a suSSHi Gateway:
[ssh_connection] ssh_args = -o SusshiGateway=susshi.corporate.net -o SusshiUser=ansible -o ControlMaster=auto -o ControlPersist=60s
The values for
ControlPersist are defaults for
ssh_args and can be kept.
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
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:
Host git.domain ForwardAgent yes User gwuser@email@example.com HostName susshi.corporate.net
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.
See sshfs.c (round about line 3938):
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.
$ sshfs gateway_user@target_user@target@susshi-gateway:/ ./root