# # # add_dir "doc" # # add_file "doc/documentation.html" # content [ffa3e8b4e5954830dd1d69af2f8e441af0681249] # ============================================================ --- doc/documentation.html ffa3e8b4e5954830dd1d69af2f8e441af0681249 +++ doc/documentation.html ffa3e8b4e5954830dd1d69af2f8e441af0681249 @@ -0,0 +1,206 @@ + + + + + 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 +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.
+ +

Usage

+ +
usher [-p pidfile] +<config-file>
+ + + + + + + + + + + +
-p pidfile
+ 		a path to a file (deleted on +program exit) to record the pid of the usher in
+
<config-file>
+ 		a path to the configuration file +to use
+
+ +

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/"

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 "./".
+
+
+

Per-server directives

+
+
server "name"
+
Define a new server with the given name.
+
host "hostname-prefix"
+
This server will match connections made to a hostname with the given prefix.
+
pattern "pattern-prefix"
+
This server will match connections where the user's include +pattern has the given prefix. If you control your DNS, it is better to +use host "hostname-prefix" instead.
+
remote "address:port"
+
Specifies a remote server to forward connections to.
+
+
local "arg1" "arg2" ...
+
Specifies arguments to append to the command line is 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
+
COMMAND [arg] ... <newline>
+
+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 the name +if a match is found, or a blank line 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.
+
+
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.
+
+
+ + \ No newline at end of file