Documentation file for usher 0.99

Usher Documentation

Introduction

This is an 'usher' to allow multiple monotone servers to work from the same port. It asks the client what branch glob it want to sync, and what server name it used to connect, and then looks up which server to forward the connection to. All servers using the same hostname (so if you support pre-0.48 clients, probably all servers behind the same usher) need to have the same server key.

This is mostly useful if you want to serve several completely unrelated projects from the same machine.

At present, only IPv4 is supported.

Usage

Config file syntax

The configuration file for usher approximately follows monotone's "basic_io" format. A sample config file is:

userpass    "username" "password"
monotone   "mtn" "-k" "my_key"
listenaddr   "0.0.0.0:4691"
adminaddr     "127.0.0.1:12345"
logdir         "/var/log/usher/"
script     "name" "exe" "arg" "arg"

server      "monotone"
host      "localhost"
pattern  "net.venge.monotone"
remote      "66.96.28.3:4691"

server         "local"
host         "127.0.0.1"
pattern  "*"
local        "-d" "/usr/local/src/managed/my.db"

There is an initial section for global settings, followed by any number of sections each starting with a "server" line.

Global directives

userpass "username" "password"

This defines a username/password combination used to access the administrative interface (see below). You can have any number of userpass lines.

monotone "executable" "arg1" "arg2"

Gives the first part of the command line used when spawning local servers.
The default is monotone "mtn".

adminaddr "address:port"

The address and port for the administrative interface to listen on.

listenaddr "address:port"

The address and port on which to listen for incoming connections.
The default is listenaddr "0.0.0.0:4691".

logdir "/path/for/log/files/"

A path (ending with a slash) where per-server logfiles for local servers should be stored.
The default is logdir "./".

script "name" "exe" "arg" "arg"

A script that can be executed by given the "RUN" command on the administrative interface. Any arguments specified in the config file will be given before any arguments given to the "RUN" command.

Per-server directives

server "name"

Define a new server with the given name. Clients that are version 0.48 or later can connect to a specific server with mtn://host.com/servername . If you only expect clients 0.48 or newer, this is the preferred dispatch mechanism.

host "hostname-prefix"

This server will match connections made to a hostname with the given prefix. If you expect clients older than 0.48 and control  your DNS, this is the preferred dispatch mechanism.

pattern "pattern-prefix"

This server will match connections where the user's include pattern has the given prefix. If you don't control your DNS, this is the only dispatch mechanism that you can use with clients older than 0.48.

remote "address:port"

Specifies a remote server to forward connections to.

local "arg1" "arg2" ...

Specifies arguments to append to the command line in the monotone directive, to spawn a local server to forward connections to.

Administrative interface

If the adminaddr directive is given in the config file, the usher will listen for administrative connections on the specified address:port. The connecting client can give commands of the form

After any command except USERPASS the usher will send a reply and close the connection. The reply will end with a newline.

Administrative commands

USERPASS username password

Required before any other command, so random people can't do bad things. If the given username and password don't match any of the userpass lines in the config file, the connection will be closed.

MATCH host pattern

Looks up the name of the server that would be used for an incoming connection having the given host and pattern. Returns "OK: <servername>" if a match is found, or "ERROR: <message>" if no match is found.

STATUS [servername]

Get the status of a particular server, or of the usher as a whole if no server is specified.
If a server is specified, the result will be one of

REMOTE	This is a remote server without open connections.
ACTIVE n	This server currently has n open connections
WAITING	This (local) server is running, but has no open connections.
SLEEPING	This (local) server is not running, but is available to connect to.
STOPPING n	This (local) server has been asked to stop, but still has n open connections. It will not accept further connections.
STOPPED	This (local) server is not running, and will not accept connections.
SHUTTINGDOWN	The usher is being shut down, and will not accept further connections.
SHUTDOWN	The usher has been shut down, and will not accept connections. All local servers have been stopped.

If no server is specified, the response will be WAITING, ACTIVE, SHUTTINGDOWN, or SHUTDOWN, with n being the total number of open connections across all servers.

LISTCONNECTIONS [servername]

Returns a space-separated list of all open connections to the given server, or to any server if no server is specified. The list items are "(server)address:port", with the address and port being for the remote end of the connection. Returns "none" if there are no connections to list.

STOP servername

Prevent the given local server from receiving further connections, and stop it once all connections are closed. The result will be the new status of that server: ACTIVE local servers will become STOPPING, and WAITING and SLEEPING serveres become STOPPED. Servers in other states are not affected.

START servername

Allow a STOPPED or STOPPING server to receive connections again. The result will be the new status of that server: STOPPING servers become ACTIVE, and STOPPED servers become SLEEPING. Servers in other states are not affected.

KILL_NOW servername

Immediately kill the given local server, dropping any open connections, and prevent it from receiving new connections and restarting. The named server will immediately change to state STOPPED.

LIST [state]

Without an argument, returns a space-separated list of all servers. With an argument, returns a list of all servers which are in the given state.

SHUTDOWN

Do not accept new connections for any servers, local or remote. Returns "ok".

STARTUP

Begin accepting connections after a SHUTDOWN. Returns "ok".

CONNECTIONS

Returns the number of connections currently open.

RELOAD

Reload the config file, the same as sending SIGHUP. The reply will be "ok", and will not be given until the config file has been reloaded.

RUN scriptname arg "a r g"

Run the named script, which was defined with the "script" config file directive. Arguments given here are appended to the end of the command line, after any arguments given in the "script" directive. Arguments with spaces can be quoted with single or double quotes, and the "\n", "\'", "\"", and "\\" escape sequences are recognized except inside single quotes. You cannot use literal newlines even inside quotes, but must use "\n" if you want a newline character. Returns the output (combined stdout and stderr) of the script, followed by a newline, the exit status and a comment, and another newline.

REMOVE_SERVER servername

Remove the named server, as if by removing it from the config file and giving the "RELOAD" command. Returns "ok", or "not found" if the named server doesn't exist.

ADD_SERVER name { remote | local } args

Add a server with the given name and startup arguments (or name and address for remote servers). "args" is either "hostname port" for remote servers, or "arg 'arg' ..." for local servers. Quotes are treated the same as for RUN. Returns "ok", or an error message.