SSH

Introduction

The SSH integration in XPipe is a core component as most remote connections to your servers are probably going to use SSH.

When establishing connections, XPipe delegates any form of connection and shell handling to your existing command-line SSH client available in the PATH, which is most likely the OpenSSH client. XPipe does not come with its own SSH implementation or other connection handling. Everything is fully realized on top of your installed CLI programs.

Adding connections

There are multiple different ways of adding SSH connections.

If you are already using an SSH config, you can use the connection entry is defined in it in XPipe by searching for available connections on the local machine.

If you are using PuTTY, see the PuTTY section on how to import connections from there.

If you are using something like tailscale or netbird, see the tailscale docs or netbird docs on how to list all systems automatically.

If most of your servers are hosted at a supported cloud provider like aws or Hetzner, see the respective docs.

If you want to add devices in your network, see the network scan feature at New -> Network scan.

In any other case, you can add new SSH connections at New -> Remote host.

Configuration

The configuration starts with supplying the address. For various types of connections, this is already automatically filled, e.g. when using a cloud provider. On the right of the address field, you can add multiple different addresses to be able to quickly switch between later on.

The next part is the identity, which consists out of the username, optional password, and an optional key. You can either specify these authentication details for this connection only in-place, or also create a new reusable identity with the button to the right of the username field. These identities can then be assigned to other connections as well.

Password authentication

To supply a password for the SSH authentication, you can choose out of multiple different password types:

Selecting none will disable password authentication. You can choose to specify a password in-place, it is then stored in the XPipe vault. Alternatively, you can choose to supply the password at runtime, meaning that XPipe will ask you for the password on the first login. For a more managed approach, you can also retrieve passwords from your password manager. See the password manager documentation on how to configure this. The last option gives you the ability to run a custom command to retrieve the password, which can be useful if you have a self-built system for passwords.

Key-based authentication

XPipe supports all established key-based authentication methods for SSH:

By default, your selection will override any external sources. If you have a local SSH agent running, XPipe will prevent it from supplying its keys unless you select the agent option here. This is to guarantee reliability when authenticating.

Many key selections also support passphrases. For passphrases, you have the same retrieval options as for passwords.

XPipe supports all types of keys, including FIDO2.

Key

With this option, you can store a private key in text form in the XPipe vault. With the keygen button at the right, you can also create new keys to store here.

Local key file

You can also specify a key file. This option is the equivalent of ssh -i <file>.

OpenSSH agent

In case your identities are stored in the OpenSSH agent, XPipe can automatically use them if the agent is correctly configured in the environment. The agent socket location is retrieved from the environment variables passed to XPipe or set in the local shell init files.

On Windows, XPipe will automatically start the agent process if it is not running yet. On other operating systems, you have to ensure that the agent is running.

If you are using any other agent, for example from a password manager, you can use the custom SSH agent option instead.

Custom agent

On Linux and macOS, you will also have access to the custom agent option as on these systems, any custom agent will use a different location for the socket. The custom socket location can be configured in the settings menu:

If you are using a password manager with an SSH agent functionality, you can choose to use it here. XPipe will verify that it doesn't conflict with any other agent configuration. XPipe, however, can't start this agent by itself, you have to ensure that it is running.

For more information, see password manager page.

GPG Agent

If you have configured GPG keys that support authentication, you can choose to provide them to the SSH client via the gpg-agent.

This option requires gpg to be installed on your local system. XPipe will automatically enable SSH support for the gpg agent if not enabled yet and restart the gpg agent daemon with the correct settings.

This option will only show up if you have the GPG agent installed on your local system.

Pageant

Pageant is the agent of PuTTY. If you have a lot of keys stored in the .ppk format, this option might bridge the incompatibilities between .ppk keys and OpenSSH. For more details, see the PuTTY section.

On Windows, due to the nature of pageant, it is your responsibility to have it running correctly as you manually have to specify all keys you would like to add every time it starts. If it is running, XPipe will pass the proper named pipe via -oIdentityAgent=... to ssh, you don't have to include any custom config files.

On Linux and macOS, in case your identities are stored in pageant, the ssh executable can use them if the agent is started. XPipe will automatically start the agent process if it is not running yet and pass the socket to SSH.

This option will only show up if you have pageant installed on your local system.

Yubikey PIV

If your identities are stored with the PIV smartcard function of the Yubikey, you can retreive them with Yubico's YKCS11 library, which comes bundled with Yubico PIV Tool.

Custom PKCS#11 library

This will instruct the OpenSSH client to load the specified shared library file, which will handle the authentication.

Other external agent

This option will permit any external running identity provider to supply its keys to the SSH client. You should use this option if you are using a password manager agent on Windows or any other agent to manage your SSH keys. XPipe will not interact with any external agent in this case, it will just allow any program to supply keys to the SSH client. You will have to make sure that the agent you want to use is running beforehand and configured correctly.

Generating keys

If you don't have an existing key at hand and instead want to configure a new key for a system to authenticate with, you can create one in the keygen menu, which you can find at the keygen button:

This will open a dialog where you can configure the generation parameters for a new key. The keys are generated via the installed OpenSSH ssh-keygen CLI tool, so you can be assured that the keys are generated in a cryptographically secure manner. This also support FIDO2 smartcard-based keys:

Once the key is generated, it will be automatically placed in the open connection configuration.

Public key handling

While you only need a private key for authentication, keeping track of the associated public keys is important as well. Especially when you want to add this keypair as an authorized key to another system. You can automatically generate and store the public key for any supplied private key automatically with the generate button in the public key field:

This might prompt you for your passphrase if the key has one.

Applying identities

When you create an identity entry that includes your keys, you can apply this identity automatically to a system:

This allows you to quickly perform a key rotation or configure new systems with key authentication.

The process of changing the authentication configuration of a system is not always one simple step. So the dialog is a comprehensive overview of what is needed to apply a certain identity to a remote system, with various quick-action buttons and notes. This gives you still full manual control of what should be done and an overview of what is required prior to doing so.

Gateways and jump servers

If you are planning to establish connections over another intermediate host, you can use XPipe's gateway feature:

In the dropdown below, you have the choice between using the gateway via a gateway tunnel or as jump server with ProxyJump.

Gateway tunnels

This is the default setting. XPipe will tunnel the host address and port over the gateway host to localhost. This requires the gateway SSH server to have port forwarding enabled with AllowTcpForwarding=yes.

The advantage of not using the usual jump server usage setting is that any eventual connection errors are much clearer than with jump servers as XPipe will connect to the gateway system and the target system separately.

Furthermore, this setting enables you to resolve any DNS names via the gateway system, not from your local machine. In case any address can only be resolved from the gateway system, this setting is required for it to connect successfully.

Jump servers

This will use the system as a jump server with ProxyJump. This option is required if your gateway system is a more restricted system or specially built to only function as a jump server. These kinds of systems often only work with ProxyJump as that is usually the standard way of using jump servers. If gateway tunnels do not work, a jump server gateway should.

Chaining

This gateway system also supports chained gateways and jump servers. This means that if you set a system as a gateway, which already itself has configured a gateway (and so on), the connection will effectively go through 2 intermediate systems before reaching your target system.

To properly make use of chained gateways, make sure that you don't mix between gateways configured as jump servers vs non-jump servers. Either set all gateways to be jump servers or none of them, depending on which gateway type you want to use.

Limited / embedded systems

XPipe works by detecting the shell type of the connection and then interacting with the active shell. This approach only works, however, when the shell type is known and supports a certain number of actions and commands. All common shells like bash, cmd, powershell, and more, are supported. If you are connecting to a system that does not run a known command shell, e.g., a router, link, or some other embedded device, XPipe will be unable to detect the shell type and error out after some time.

To work around these cases, you can explicitly designate a system as such:

When this setting is enabled, XPipe will not attempt to identify the shell type and launch the shell as-is. This allows you to open the connection without errors, but many features, e.g., the file browser, scripting, subconnections, and more, will not be supported for this connection.

X11 Forwarding

XPipe supports X11 forwarding for SSH connections. You can enable this in the advanced SSH configuration for a connection:

When this option is enabled, the SSH connection will be started with X11 forwarding set up. On Linux, this will usually work out of the box and does not require any setup. On macOS, you need an X11 server like XQuartz to be running on your local machine.

X11 on Windows

XPipe allows you to use the WSL2 X11 capabilities for your SSH connection. The only thing you need for this is a WSL2 distribution installed on your local system. XPipe will automatically choose a compatible installed distribution if possible, but you can also use another one in the settings menu:

This means that you don't need to install a separate X11 server on Windows. However, if you are using one already, XPipe will detect and use the currently running X11 server.

X11 connections as desktops

Any SSH connection that has X11 forwarding enabled can be used as a desktop host. This means that you can launch desktop applications and desktop environments through this connection. When any desktop application is launched, this connection will automatically be started in the background to start the X11 tunnel.

For more information, see the desktop applications page.

Config files

XPipe fully supports using connections defined in SSH config files. In contrast to many other tools, this is not an import functionality where the config data is converted to internal data. Instead, the config file stays the backing store of the connection information. Any changes you make later on will be reflected in XPipe upon refresh.

Your local SSH configs apply to all SSH connections in XPipe, even if your config file is not added to XPipe or you created SSH connections within XPipe itself. This is important to keep in mind in case any wildcard options defined in your local config file affect other unrelated SSH connections in XPipe.

Adding files

XPipe can load all hosts and apply all settings that you have configured in the selected file. By specifying a configuration option on either a global or host-specific basis, it will automatically be applied to the connection established by XPipe.

Searching for available connections on a system will automatically add the default SSH config file at ~/.ssh/config if it exists. You can also add configs from other locations at New -> Remote Host -> SSH config file. XPipe supports wildcard definitions and include statements of other files as well, meaning that you will get a one-to-one application of your entire config in XPipe. It is exactly applied as it would if you use the ssh command-line client.

If you want to learn more about how to use SSH configs, you can use man ssh_config or read this guide.

Text-based connections

If you want to create a fully customized SSH connection with more options than you can find in the simple SSH connection creation dialog, you can take a look at customized SSH connections. These allow you to specify an SSH connection in-place using the SSH config syntax you know. It is essentially a way to create SSH config connections without having to go through dealing with creating config files. This is recommended if you are an advanced user and know what you're doing.

Note that most features can be realized through simple SSH connections already. Things like ProxyJump chains, additional SSH options, and more can already be used with simple SSH connection entries. Custom SSH connections are only really necessary for very specific use cases.

Format

You can specify connection details just as in an SSH config. The main difference is that you don't need to include an explicit host declaration. For example, the following definitions are semantically equivalent:

User user
HostName example.com

Host myhost
    User user
    HostName example.com

Identities

Note that you can also specify an IdentityFile option in here. If any identity is specified in here, any otherwise specified identity later down below will be ignored.

X11 forwarding

If any options for X11 forwarding are specified here like ForwardX11, XPipe will automatically attempt to set up X11 forwarding. For more information. see TODO.

Jump hosts

You can also define multiple hosts if you need additional hosts to be used for certain options like ProxyJump. For example, you can also define the following 2 hosts for a custom SSH connection:

Host myhost
    User user
    HostName example.com
    ProxyJump jump

Host jump
    User jumpuser
    HostName jump.example.com

In the case of multiple host definitions, XPipe will always choose the first one as the target host. Therefore, you have to take care of providing the hosts in the correct order, otherwise it will try to connect to an intermediate host. In this case, the ProxyJump option does not need the hosts to be defined in order.

Note that it is recommended to use a proper SSH config file for ProxyJump chains like this as it is not possible for custom SSH connections to specify multiple different authentication credentials. Custom SSH connections are therefore mostly intended for simpler types of hosts and not complex jump chains.

Adding SSH options

Simple SSH connections can be augmented with SSH config options if needed. This bridges the gap between basic SSH connections and fully custom SSH connections, which might be overkill for some cases. If you are just looking to add a simple option for a connection, like accepting a deprecated host key algorithm, you can add this in the advanced configuration:

Similar to custom SSH connections, you don't need to specify a Host header, only the raw options itself.

One common case for this is to, for example, allow deprecated SSH algorithms that are still used by older servers but not accepted by newer clients. To add the old ssh-rsa algorithm for a server, you can add the HostKeyAlgorithms +ssh-rsa option.

Tunnels

You have full access to SSH tunnel capabilities in XPipe. You are able to create local, remote, and dynamic tunnels that can be toggled on/off at any time. Tunnels can be created for any SSH-based connections. This includes VM connections, tailscale connections, teleport connections, and more.

Local tunnels

If you are looking for a more user-friendly experience for tunnels, check out services instead. Raw SSH local tunnels it only makes sense to use instead of services if you want to use more advanced tunnel bindings.

The binding information you provide is passed straight to the ssh client as follows: -L [origin_address:]origin_port:remote_address:remote_port. By default, the origin will bind to the loopback interface if not specified otherwise. You can also make use of any address wildcards, e.g. setting the address to 0.0.0.0 in order to bind to all network interfaces accessible via IPv4. When you completely omit the address, the wildcard *, which allows connections on all network interfaces, will be used. Note that some network interfaces notation might not be supported on all operating systems. Windows servers for example don't support the wildcard *.

Remote tunnels

Remote tunnels cannot be instantiated via any other means like services, so if you're looking to create one, you will have to use the remote tunnels.

The binding information you provide is passed straight to the ssh client as follows: -R [remote_source_address:]remote_source_port:origin_destination_address:origin_destination_port. By default, the remote source address will bind to the loopback interface. You can also make use of any address wildcards, e.g. setting the address to 0.0.0.0 in order to bind to all network interfaces accessible via IPv4. When you completely omit the address, the wildcard *, which allows connections on all network interfaces, will be used. Note that some network interfaces notation might not be supported on all operating systems. Windows servers for example don't support the wildcard *.

Dynamic tunnels

Dynamic tunnels set up a connection that will forward traffic to a remote server, irrespective of the destination port. You can effectively use it as a SOCKS5 proxy server.

The binding information you provide is passed straight to the ssh client as follows: -D [address:]port. By default, the address will bind to the loopback interface. You can also make use of any address wildcards, e.g. setting the address to 0.0.0.0 in order to bind to all network interfaces accessible via IPv4. When you completely omit the address, the wildcard *, which allows connections on all network interfaces, will be used. Note that some network interfaces notation might not be supported on all operating systems. Windows servers for example don't support the wildcard *.

SFTP sessions

By default, any session opened in the file browser will use an SSH shell-based session to allow for more flexibility by running commands. However, a side effect of this is that transfer speeds are a bit slower and some connections might fail if the target system only allows for pure SFTP and no SSH shells.

To open an SFTP session to a system in the file browser, you can either mark the system as limited/embedded. This will automatically attempt to open an SFTP session as these kinds of systems often do not support shells. Alternatively, you can switch to pure SFTP in any SSH-based file browser session in the context menu for a directory:

You can see in the tab name whether you are using an SFTP session or not:

Note that SFTP sessions are limited compared to shell-based sessions in terms of features as no commands can be executed.

PuTTY

If you are using PuTTY (or KiTTY) and are now moving to XPipe, there are a few things to look out for.

Existing connections/sessions saved in PuTTY can be imported somewhat into XPipe on Windows by searching for available connections on the local machine:

This will import connections from the registry. If your connections are not saved to the registry, e.g., when using a portable version of PuTTY/KiTTY, you can still import them by explicitly saving all session data to the registry as shown here.

The imported data is not fully complete though. Passwords aren't imported and ppk keys can't be imported due to the format incompatibility.

.ppk keys

PuTTY has its own non-standard SSH key file format with .ppk files. This poses a challenge as these are not supported by OpenSSH, nor can they be automatically converted to the standardized .pem format. The best that you can do is manually export them into the correct format from PuTTY as shown in the documentation.

If you only have a few keys added to PuTTY, this manual convert option should work fine. For more keys, it might make sense to keep them in PuTTY's pageant, which is the PuTTY equivalent to the SSH agent. You can configure a connection in XPipe to use pageant for keys:

VSCode

If you have VSCode installed on your system, you can also use XPipe to launch the SSH remote development feature of VSCode from XPipe.

This option will show up if VSCode is installed and the SSH connection can be launched with VSCode. All SSH config connections can be launched in VSCode. For other connections defined in XPipe itself, the VSCode feature only supports password authentication. If you are using normal SSH connections with key-based authentication, this option will not show up by default. As a workaround, you can define the connection in your local SSH config and then add that config to XPipe.

Windows SSH servers

Since Windows 10, Microsoft has been shipping an OpenSSH client and server with Windows that you can use. You just have to enable the OpenSSH server feature for your Windows installation as shown here. On the latest Windows 11 systems, it might already be preinstalled.

If you are planning on configuring key-based authentication for your SSH server instead of just password authentication, note that Windows SSHD has an additional layer of complexity involved when adding authorized keys for users which have administrator privileges. You have to add public keys for these users into a separate administrators_authorized_keys file as explained here.

Troubleshooting

With SSH, a lot can go wrong. And since many OpenSSH error messages are very vague, troubleshooting might not be straightforward. This section compiles a few common issues. Note that since XPipe just uses your OpenSSH client, many resources and solutions you find online will also apply to XPipe.

See the SSH troubleshooting page for details.