Next: , Previous: Workspace, Up: Command Reference


5.3 Network

mtn serve [--bind=[address][:port]]
mtn serve --stdio [--no-transport-auth]
mtn pull [--set-default] [uri-or-address] [glob [...] [--exclude=exclude-glob]]]
mtn push [--set-default] [uri-or-address] [glob [...] [--exclude=exclude-glob]]]
mtn sync [--set-default] [uri-or-address] [glob [...] [--exclude=exclude-glob]]]
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 a URI, a Lua hook may transform the URI into a connection command, and execute the command as a transport channel for netsync. If the argument is a simple hostname (with optional port number), monotone will use a TCP socket to the specified host and port as a transport channel for netsync.

The glob parameters indicate a set of branches to exchange. Multiple glob and --exclude options can be specified; every branch which matches a glob exactly, and does not match an exclude-glob, 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 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 address and glob the first time you use one of them; monotone will memorize this use and in the future default to the same 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 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 Hook 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 is very simple. * matches 0 or more arbitrary characters. ? matches exactly 1 arbitrary character. {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.