SSH

Introduction

The SSH integration in XPipe is a core component as most remote connections to your servers are probably going to use SSH. The SSH integration in XPipe basically supports all the functionality of your command-line OpenSSH client, and you don't have to get used to anything new.

Your SSH client

When establishing connections, XPipe delegates any form of connection and shell handling to your existing command-line SSH client available in the PATH. XPipe does not come with any remote handling capabilities of its own. Therefore, the capabilities and security of the established SSH connection depend on your installed SSH client.

If, for example, your ssh command-line client is outdated and does not support certain features, then XPipe can't support these as well. This can concern newly introduced SSH config options or new key exchange methods that are only available in the latest SSH versions. If you want to make use of such features, make sure to upgrade your installed OpenSSH client on your local system.

If your client is outdated and susceptible to newly discovered exploits or vulnerable in any other way, there is no way for XPipe to guarantee that data can be transferred securely. It is your responsibility to use external programs that XPipe interacts with in a secure environment and keep them up to date with security patches and more. Connections established with XPipe can only be as secure as your underlying command-line SSH client itself. Always make sure to upgrade your installed packages.

Key-based authentication

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

None

If selected, XPipe will not supply any identities. This will also prevent any external sources like agents from providing keys.

Key file

You can also specify a key file with an optional passphrase. This option is the equivalent of ssh -i <file>. All kinds of keys, including FIDO2, are supported.

Note that you should select the private key, not the public one. If you mix that up, ssh will only give you cryptic error messages.

You also have to specify any potential passphrase the key has. If you want to enter the passphrase manually, you can choose the prompt option for the passphrase.

OpenSSH agent

In case your identities are stored in the SSH-Agent, the ssh executable can use them if the agent is started. The agent socket 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.

Note that XPipe attempts to use the OpenSSH agent if it can find it. 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 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 a smartcard with 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 and will automatically enable SSH support of the 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

In case you are using pageant on Windows, XPipe will check whether pageant is running first. Due to the nature of pageant, it is your responsibility to have it running as you manually have to specify all keys you would like to add every time. 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.

Note that you also need an up-to-date build of OpenSSH in order to use this feature as this is a relatively recent feature not supported in older versions.

Custom PKCS#11 library

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

Note that you need an up-to-date build of OpenSSH in order to use this feature.

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.

Gateways and jump servers

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

By default, when a gateway is used, 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.

This functionality is different from jump servers with ProxyJump by default. You can, however, use proper jump server behavior as well by designating the gateway system as a jump server in its configuration:

This might be required in case the jump server is a restricted system where no port forwarding or system shell is available.

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.

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.

The older Windows 10 OpenSSH server has some issues, which might make the initial connection fail. The server on Windows 11 doesn't have these issues. You might run into errors like client_loop: send disconnect: Connection reset or client_loop: send disconnect: Broken pipe when establishing a connection for Windows 10 servers.

With older installations, Microsoft ships an old version of SSH as well. This server version, however, has a few bugs which commonly cause issues with SSH clients in general, so also with XPipe. If you are planning on setting up an SSH server on Windows, make sure that your SSH version is relatively recent. Any SSH version of v9.x should work fine. If you have an older version installed, you can install the latest version from here.

Administrator keys

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.