SSH endpoints

Mutagen provides support for synchronizing files and forwarding network traffic via SSH.

Requirements

Mutagen requires an OpenSSH client installation to be available on your system. This is the default for almost all POSIX operating systems, so you probably don’t need to do anything if you’re on macOS, Linux^®, or one of the BSDs. Windows is supported as well, but please see the section on Windows support for more detailed information.

Mutagen should support most SSH server implementations, so long as they support OpenSSH’s ssh and scp implementations. If you run into trouble with a particular SSH server implementation, please file an issue.

Synchronization

SSH synchronization endpoints can be specified to the mutagen sync create command using an SCP-like URL syntax of the form:

[<user>@]<host>[:<port>]:<path>

The <user> component is optional and will be passed to OpenSSH to override the default username.

The <host> component can be any IP address, hostname, or alias understood by OpenSSH. It is required and must not be empty.

The <port> component is also optional and is an extension to the standard SCP URL syntax. If specified, it will be passed to OpenSSH to override the default port.

The <path> component is interpreted in the same way as an SCP path. It is required and must not be empty.

• example.org:/var/www

  Connect to example.org and target an absolute path.

• example.org:23:relative/path

  Connect to example.org on a custom SSH port (23) and target a relative path. The path will be resolved relative to the default SSH working directory (typically the user's home directory).

• hostalias:~/path/in/home/directory

  Connect to the server indicated by the alias hostalias and target a path relative to the user's home directory.

• [email protected]:~otheruser/path/in/their/home/directory

  Connect to example.org as the user george and target a path relative to a specific user's home directory.

Forwarding

SSH forwarding endpoints can be specified to the mutagen forward create command using URLs of the form:

[<user>@]<host>[:<port>]:<network-endpoint>

The <user>, <host>, and <port> components of this URL are the same those in the synchronization URL format described above, while the <network-endpoint> component is described in the forwarding documentation. As before, the <host> component is required and must not be empty, and the same applies to the <network-endpoint>. In the case of relative Unix domain socket paths in the <network-endpoint> component, path resolution will be performed relative to the default SSH working directory (typically the user’s home directory).

• example.org:tcp::8080

  Connect to example.org and bind to all network interfaces on port 8080.

• [email protected]:24:tcp:localhost:8080

  Connect to example.org on a custom SSH port (24) as the user george and bind to or target the loopback interface on port 8080.

• hostalias:tcp6:localhost:8080

  Connect to server indicated by the alias hostalias and bind to or target the IPv6 loopback interface on port 8080.

• [email protected]:tcp:10.0.1.25:6060

  Connect to example.org as the user george and bind to or target 10.0.1.25 on port 6060.

• example.org:unix:/path/to/socket.sock

  Connect to example.org and bind to or target a Unix domain socket using an absolute path.

• example.org:unix:path/to/socket.sock

  Connect to example.org and bind to or target a Unix domain socket using a relative path. Path resolution in this case is relative to the default SSH working directory (typically the user's home directory).

• example.org:unix:~/path/to/socket.sock

  Connect to example.org and bind to or target a Unix domain socket relative to the user's home directory.

• example.org:unix:~otheruser/path/to/socket.sock

  Connect to example.org and bind to or target a Unix domain socket relative to a specific user's home directory.

Implementation

Mutagen’s SSH support is provided by the OpenSSH installation on your system. Mutagen uses the OpenSSH suite’s scp command to copy agent binaries to remote systems and the ssh command to run and communicate with the agent binaries over standard input/output streams.

Mutagen redirects SSH prompts to its create, resume, and reset commands via the SSH_ASKPASS environment variable.

This design has a number of advantages:

• OpenSSH installations are nearly universal in the POSIX world, and OpenSSH is now making its way to Windows.
• Mutagen automatically uses all existing SSH configuration, keys, and aliases.
• There’s no risk of baking in an SSH library that might be found to have security vulnerabilities.
• With OpenSSH being the de facto SSH implementation, other SSH server implementations are far more likely to aim for compatibility with OpenSSH clients.
• OpenSSH has a much longer develoment and security track record than any SSH library implementation.

Mutagen may eventually support other SSH clients or embed the Go SSH library, but these will always be fallback options.

OpenSSH search path

On POSIX systems, Mutagen uses the first OpenSSH ssh and scp executables that are found in the user’s path. On Windows systems, Mutagen uses a different approach described below. Both of these search strategies can be overridden by setting the MUTAGEN_SSH_PATH environment variable (for the Mutagen daemon) to a path containing the desired OpenSSH executables.

OpenSSH connection timeout

Mutagen uses a default value of 5 seconds for the OpenSSH ConnectTimeout configuration parameter. This can be overridden by setting the MUTAGEN_SSH_CONNECT_TIMEOUT environment variable (for the Mutagen daemon) to an integer value specifying a timeout in seconds.

Windows

Mutagen fully supports SSH on Windows, though you’ll need to bring your own OpenSSH client. Unfortunately the official Windows OpenSSH client is still in beta and has a few blocking issues, primarily PowerShell/Win32-OpenSSH#1152,¹ that disallow its use by Mutagen at the moment. As soon as these issues are resolved, this will become Mutagen’s recommended client (though others will continue to be supported).

Mutagen has a hardcoded set of OpenSSH clients that it will look for and use at the moment, including those from Git for Windows (recommended), MSYS2, and Cygwin. You can see the full list of search paths here.

One thing to be aware of is that the MSYS2 and Cygwin OpenSSH clients will, by default, look for SSH configuration (~/.ssh) in the “virtual” home directory provided by the underlying Cygwin environment. This is not a problem, though be aware that Mutagen will continue to store its data (~/.mutagen) and look for its configuration (~/.mutagen.yml) in the user’s actual home directory (i.e. that specified by %USERPROFILE%). The Git for Windows OpenSSH implementation will look for SSH configuration in the actual home directory as well.

SSH servers

Mutagen is currently only known to work reliably with Bitvise SSH Server on Windows.

The official Windows OpenSSH server is still in beta and has a few performance issues and other kinks that need to be ironed out before Mutagen can reliably support it. Mutagen will connect to this server and mostly work, but the performance is not great at the moment due to the server’s stream handling. Issues have also been experienced with stalled data streams.

Mutagen should also work with other Windows SSH servers (for example, Cygwin’s OpenSSH server), though please open an issue if you run into problems.

PuTTY

Mutagen does not support PuTTY.