3.1 Other Transports

Monotone’s database synchronization system is based on a protocol called netsync. By default, monotone transports this protocol over a plain TCP connection, but this is not the only transport monotone can use. It can also transport netsync through SSH, or any program which can provide a full-duplex connection over stdio.

When a monotone client initiates a push, pull, or sync operation, it parses the first command-line argument as a URI and calls a Lua hook to convert that URI into a connection command. If the Lua hook returns a connection command, monotone spawns the command locally and speaks netsync over a pipe connected to the command’s standard I/O handles.

If the Lua hook does not return a connection command, monotone attempts to parse the command-line argument as a TCP address – a hostname with an optional port number – connects a TCP socket the host and port, and speaks netsync over the socket.

By default, monotone understands two URI schemes:

1. SSH URIs, of the form ssh://[user@]hostname[:port]/path/to/db.mtn, to synchronize between private databases on hosts accessible only through SSH. (These paths are absolute; to refer to a path relative to a home directory, use ssh://host-part/~/relative/path.mtn or ssh://host-part/~user/relative/path.mtn.)
2. File URIs, of the form file:/path/to/db.mtn, to synchronize between local databases.

ssh: and file: are currently not supported on the native Win32 platform; they are supported on Cygwin and all other platforms.

In the case of SSH URIs, the ssh program must be in your command execution path, either $PATH on Unix-like systems or %PATH% on Windows systems. Monotone will execute ssh as a subprocess, running mtn serve on the other end of the SSH connection. You will need mtn to be in the command execution path of the remote shell environment.

In the case of File URIs, mtn is run locally, so must be in your command execution path.

In both cases, the database specified in the URI needs to exist already, and will be locked for the duration of the synchronization operation. Therefore, it must also be writable, even when monotone isn’t going to modify it, as it is the case for pull. Also note that monotone’s default transport authentication is disabled over these transports, to reduce the complexity of configuration and eliminate redundant protocol cost.

Additional URI schemes can be supported by customization of the Lua hooks get_netsync_connect_command and use_transport_auth. For details on these hooks, see Netsync Transport Hooks.