Mutagen provides support for synchronizing files and forwarding network traffic via SSH.
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
scp implementations. If you run into trouble with a
particular SSH server implementation, please
file an issue.
SSH synchronization endpoints can be specified to the
mutagen sync create
command using an SCP-like URL syntax of the form:
<user> component is optional and will be passed to OpenSSH to override the
<host> component can be any IP address, hostname, or alias understood by
OpenSSH. It is required and must not be empty.
<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
<path> component is interpreted in the same way as an SCP path. It is
required and must not be empty.
example.organd target an absolute path.
example.orgon 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).
Connect to the server indicated by the alias
hostaliasand target a path relative to the user's home directory.
example.orgas the user
georgeand target a path relative to a specific user's home directory.
SSH forwarding endpoints can be specified to the
mutagen forward create
command using URLs of the form:
<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,
<host> component is required and must not be empty, and the same applies
<network-endpoint>. In the case of relative Unix domain socket paths in
<network-endpoint> component, path resolution will be performed relative
to the default SSH working directory (typically the user’s home directory).
example.organd bind to all network interfaces on port
example.orgon a custom SSH port (
24) as the user
georgeand bind to or target the loopback interface on port
Connect to server indicated by the alias
hostaliasand bind to or target the IPv6 loopback interface on port
example.orgas the user
georgeand bind to or target
example.organd bind to or target a Unix domain socket using an absolute path.
example.organd 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.organd bind to or target a Unix domain socket relative to the user's home directory.
example.organd bind to or target a Unix domain socket relative to a specific user's home directory.
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
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
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
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.
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,1 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.
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.
Mutagen does not support PuTTY.
Issue 1152 has been resolved, but the fix hasn’t yet shipped as part of a Windows release. ↩︎