SSH
Accessing systems via 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.
SSH-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.
Password manager agent
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.
Pageant (Windows)
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.
Pageant (Linux & 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.
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 source
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 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.
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 for worthy 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.
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.
In any case, you can always try out the verbose SSH output troubleshooting option you can find in the settings menu:
This option will give additional information for connection attempts. You should only use it when troubleshooting though as it can break other functionality. If you identify the issue, make sure to disable it again.
Key permissions too open
By default, OpenSSH requires that all key files should only be accessible by your current user. This behavior can't be changed, so you will have the same permission requirements with XPipe.
On Windows, since file-based permissions are rather untypical, so OpenSSH requires your key file to be located somewhere in your user home director at C:\Users\User. If your key is not located there, there is still the option to modify file-based permissions to make the file only accessible by your current user. XPipe will offer you the option to attempt to do this, however, this might not always work due to the complexities of Windows file permissions and how strict OpenSSH is. If the automatic permission change in XPipe doesn't work, which happens for keys located on some external flash drive, the best option is to just copy the file into your user directory.
On Unix-based operating systems, this is enforced by requiring a key file to have no permissions for anything other than the current user, e.g. 400 or 600 permissions. XPipe will automatically attempt to adjust permissions on these platforms if the permissions are too open. This might fail if the key is stored on a different file system that prevents these kinds of modifications, like a formatted flash drive. In that case, you have to make sure that the permissions are correct.
Permission denied
If you get a generic permission denied error, there are multiple possibilities on what went wrong.
First, you have to make sure that you have the right credentials and also the right hostname.
Publickey
If you get Permission denied (publickey), you will have to check the key and whether it is the correct one.
If you are using something like an agent, make sure that the agent is running and contains the necessary key. As the agent does not know which key to supply, it will try every key it has without knowing which one is the correct one.
If you have configured the keys in the local SSH config file, XPipe might not apply these for all connections. So you can also try setting them explicitly for a connection in XPipe.
For Windows servers, also see the Administrator keys section for necessary Windows-specific configuration.
Password
If you get Permission denied (password), there are not that many possible causes other than the password being wrong.
If you are connecting to a Windows server, the user account password might be expired. This will cause the same error until the password is changed, even though the password is theoretically correct.
If you are using a password manager, make sure that you have the correct entry name specified in XPipe.
No route to host
The error message no route to host indicates a DNS resolution failure. It is recommended to check your local DNS configuration and maybe restart your system to takes any issues where any DNS service doesn't work correctly.
On macOS, this issue might also occur if you don't allow XPipe network access. You can explicitly allow network access for XPipe in the system settings -> Security and privacy -> Local network.
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.
Versions
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.
No matching host key type found
If your SSH server only offers outdated host key algorithms that are not enabled by default in your local SSH client, you can manually add those to a specific connection via the additional SSH config options for SSH. For example, to support the algorithm ssh-dss, add the following additional option:
XPipe is able to automatically configure this for simple SSH connections. For other types of SSH connections, you have to add this option by yourself.
No matching key exchange method
If your SSH server only offers outdated key exchange algorithms that are not enabled by default in your local SSH client, you can manually add those to a specific connection via the additional SSH config options for SSH. For example, to support the algorithm diffie-hellman-group14-sha1, add the following additional option:
XPipe is able to automatically configure this for simple SSH connections. For other types of SSH connections, you have to add this option by yourself.
No matching MAC found
If your SSH server only offers outdated MACs that are not enabled by default in your local SSH client, you can manually add those to a specific connection via the additional SSH config options for SSH. For example, to support the MAC hmac-sha1, add the following additional option:
XPipe is able to automatically configure this for simple SSH connections. For other types of SSH connections, you have to add this option by yourself.
Connection closed by remote host
If you get a message like kex_exchange_identification: Connection closed by remote host, the SSH server explicitly disconnected your connection attempt. This can happen if, for example, rate limits are exceeded and too many users connect.
For example, if you find the output debug1: kex_exchange_identification: banner line 0: Exceeded MaxStartups in the debug output, this indicates that too many connection attempts were made in parallel. In practice, this is caused by bots probing SSH servers all the time. You can either increase the MaxStartups in the sshd config, improve your firewall, or just use another port for SSH to reduce bot spam.