5.3 Network

mtn serve [--bind=[address][:port]]

mtn pull [--[no-]set-default] [uri]

mtn push [--[no-]set-default] [--keys-to-push=key] [uri]

mtn sync [--[no-]set-default] [--keys-to-push=key] [uri]

mtn pull [--[no-]set-default] [address] [glob [...] [--exclude=exclude-glob]]] deprecated

mtn push [--[no-]set-default] [--keys-to-push=key] [address] [glob [...] [--exclude=exclude-glob]]] deprecated

mtn sync [--[no-]set-default] [--keys-to-push=key] [address] [glob [...] [--exclude=exclude-glob]]] deprecated

These commands operate the “netsync” protocol built into monotone. This is a custom protocol for rapidly synchronizing two monotone databases using a hash tree index. The protocol is “peer to peer”, but requires one peer to listen for incoming connections (the server) and the other peer (the client) to connect to the server. When run with --stdio, the server listens for a single connection then terminates. When run with --bind, or with neither option, the server listens for TCP connections and serves them continuously, until it is shut down.

The network address given to serve as an argument to --bind should be a host name to listen on, optionally followed by a colon and a port number. The default port number is 4691. If no --bind option is given, the server listens on port 4691 of every network interface.

If serve is run with --stdio, a single netsync session is served over the stdin and stdout file descriptors. If --no-transport-auth is provided along with --stdio, transport authentication and access control mechanisms are disabled. Only use --no-transport-auth if you are certain that the transport channel in use already provides sufficient authentication and authorization facilities.

The uri-or-address arguments given to push, pull, and sync can be of two possible forms.

If the argument is an URI, the Lua hook get_netsync_connect_command may transform it into a connection command, which is later executed as transport channel for netsync. The URI itself consists of a connection scheme (defaults to mtn), an optional user (only used for ssh-related transports), a host with an optional port (which both might be optional as well, f.e. for the file scheme), a path and a query part, which denotes one or more branches and optionally also exclude patterns for the exchange:

     <scheme>://[[<user>@]<host>[:<port>]][/<path>][?<pattern>[;-<exclude-pattern>[...]]]

Valid examples of URIs monotone accepts are:

     mtn://my.server:4690?my.branch
     mtn://my.server/project?my.other.branch*;-my.other.branch.test
     file:///path/to/database.mtn?my.branch
     ssh://joe@my.server/~/db.mtn?joes.branch

If the server has a multi-host setup, the path component of the URI might be used to distinguish between different databases (please ask the provider of the setup for details).

If the argument is a simple hostname (with optional port number), monotone will fall back to the mtn URI scheme, i.e. use a TCP socket to the specified host and port. The glob parameters then indicate a set of branches to exchange. Multiple glob and --exclude options can be specified. Important notice: This call syntax is deprecated and subject of removal in future versions of monotone!

For both syntaxes, every branch which matches a glob or branch pattern exactly, and does not match an exclude-glob or exclude pattern, will be indexed and made available for synchronization.

For example, perhaps Bob and Alice wish to synchronize their net.venge.monotone.win32 and net.venge.monotone.i18n branches. Supposing Alice's computer has hostname alice.someisp.com, then Alice might run:

     $ mtn --bind=alice.someisp.com serve

And Bob might run

     $ mtn sync "mtn://alice.someisp.com?net.venge.monotone*"

When the operation completes, all branches matching net.venge.monotone* will be synchronized between Alice and Bob's databases.

The pull, push, and sync commands only require you pass uri (or address and glob) the first time you use one of them; monotone will memorize this use and in the future default to the same URI (or server and glob). For instance, if Bob wants to sync with Alice again, he can simply run:

     $ mtn sync

Of course, he can still sync with other people and other branches by passing an URI, address or address plus globs on the command line; this will not affect his default affinity for Alice. If you ever do want to change your defaults, simply pass the --set-default option when connecting to the server and branch pattern that you want to make the new default.

In the server, different permissions can be applied to each branch; see the hooks get_netsync_read_permitted and get_netsync_write_permitted (see Lua Reference).

If a --pid-file option is specified, the command serve will create the specified file and record the process identifier of the server in the file. This file can then be read to identify specific monotone server processes.

The syntax for patterns, both in globs as well as URIs, is very simple. * matches 0 or more arbitrary characters. ? matches exactly 1 arbitrary character (you need to escape that with %3F in an URI). {foo,bar,baz} matches “foo”, or “bar”, or “baz”. These can be combined arbitrarily. A backslash, \, can be prefixed to any character, to match exactly that character — this might be useful in case someone, for some odd reason, decides to put a “*” into their branch name.