Mutagen provides support for synchronizing files and forwarding network traffic via SSH. This support extends to SSH clients and servers found on both POSIX and Windows systems.
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
ssh implementations. If you run into trouble with a
particular SSH server implementation, please file an issue.
SSH-accessible 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
<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 can be
an absolute path, e.g.
a relative path (which will be resolved relative to the default SSH working directory (usually the user’s home directory)), e.g.
a home-directory-relative path, e.g.
or an alternate user home-directory-relative path, e.g.
<path> component is not allowed to be empty.
SSH-accessible network 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. In the case of
relative Unix domain socket paths, path resolution will be performed relative to
the default SSH working directory (usually the user’s home directory).
Mechanism of action
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
resume 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
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.
Windows is fully supported by Mutagen, 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 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 totally fine, though
Mutagen will continue to store its data (
~/.mutagen) and look for its
~/.mutagen.yml) in the user’s actual home directory (i.e. that
%USERPROFILE%). The Git for Windows OpenSSH implementation will
look for SSH configuration in the actual home directory as well, which is why
Mutagen will give it priority if found.
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.
There is no reason that Mutagen won’t work with other Windows SSH servers (e.g. Cygwin’s OpenSSH server), so please report your findings if you try them out.
Mutagen does not support PuTTY.