# # # patch "README" # from [8b05deed0806eb11afddcfd9f4fb71290973f90c] # to [7b341bcea032b78c9ca7ba9f634f3442ece4a0c2] # ============================================================ --- README 8b05deed0806eb11afddcfd9f4fb71290973f90c +++ README 7b341bcea032b78c9ca7ba9f634f3442ece4a0c2 @@ -1,258 +1,13 @@ -Introduction ------------- - This is an 'usher' to allow multiple monotone servers to work from the same port. It asks the client what it wants to sync, and then looks up the matching server in a table. It then forwards the connection to the specific instance belonging to that server. -All servers using the same usher need to have the same server key. -Usher requires cooperation from the client, which is usually the case for -most of the newer monotone versions starting from version 0.24 which was -released in late 2005. +This runs on unix-type systems, it probably won't compile on Windows. -Usage: - usher [-p pidfile] +The documentation is in doc/documentation.html . -Options: - -p pidfile a path to a file (deleted on program exit) to - record the pid of the usher in [optional] - path to a file that which specifies how to map - the clients requests to monotone servers. - [required] - -An 'usher' is useful in at least the following situations: - -- a monotone webhosting service where many instances of different - databases are (sometimes) active - -- if you have a clear separation of what goes into certain databases, - either based on certain branchnames or hostnames (main in one - database, plugins in another etc.) - -- if you want to limit the 'namespace' of branchnames in one database - - -Configuration file syntax -------------------------- - -The configuration file for usher is in 'basic_io' like format, -similar to what monotone uses. - -It consists of lines with the following general syntax: - - keyword "value" "value2" "value3" ... - -- values are separated by spaces and enclosed by double quotes. -- blocks of lines are separated by empty lines - -Example: - - 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/db.mtn" "*" - - -Description of keywords and their values ----------------------------------------- - -- username "" "" - - This defines one or more usernames identified by the password - specified which can access the 'usher' over the administrative port. - (see below: Administrative interface) - Insert such a line for every username you need. - - Default: none - -- monotone "" "" " ... - - Describes the arguments usher should use when spawning dynamic - monotone servers. Since usher spawns monotone instances which - 'serve' things that argument is applied. - - Default: monotone "mtn" - - Example: monotone "mtn" "-k" "address@hidden" - -- adminaddr "
:" - - The administrative (ip-)address and port, where administrative - commands can be issued. (see below: Administrative interface) - - Default: none - -- listenaddr "
:" - - Normal address and portnumber on which the usher process should - listen for incoming connections. - - Default: listenaddr "0.0.0.0:4691" - -- logdir "/path/for/logfiles/" - - A path (ending in a slash) where logfiles usher produces should - be stored. The names of the logfiles are taken from the server - stanzas in the configuration file (described below) appended - with '.log' - - Default: logdir "./" - - -The remainder of the configuration file consists of stanza's specifying -which servers are running in coordination with usher and how request -should be redirected to them. - -A server block can have two general forms, one for local (dynamically -created) 'serve' processes and one for 'remote' monotone processes: - - server "" - host "" - pattern "" - remote "" - -or - - server "" - host "" - pattern "" - local "" "" "" ..."" - - -When usher receives a request (on 'listenaddr'), a match is tried with -the value specified on the 'host' keyword lines. If the initial substring -('stem') of the requested host matches a value the request is: - -- directed to the host at 'ipaddress:port' if the last line of the block - is 'remote'. - -- directed to a dynamically created monontone serving process if the last - keyword line specifies 'local', using the arguments from that line, - including the common arguments specified on the 'monotone' keyword line. - -Note that 'host' has to be an initial substring of what the client -asked to connect to, but does not have to match exactly. This means that -you don't have to know in advance whether clients will be asking for -'host' or 'host:port'. - -If no server block with a matching 'host' is found, the include pattern -offered by the client will be compared against the 'pattern' stem values -lines in the same way. In particular, note that the pattern lines are -not globs; they are initial substrings (stem's) just like the 'host' lines. - -For 'local' servers usher uses a port range (currently hardcoded) to start -monotone serve processes on. The default range is: 15000-65000. -Also, for local serve processes there is an 'idle_timeout' value after -which local servers are terminated if no client is using it. This value is -by default 60 seconds. (hardcoded) -Similarly, usher will use the local address interface for the address range. -The current range is: 127.0.1.1 - 127.254.254.254 - - -Administrative interface ------------------------- - -If the 'adminaddr' keyword line is given in the configuration file, the -usher will listen for administrative connections on the specified -address:port. The connecting client can issue commands of the form -(note the lack of quotes here) - - COMMAND [arguments] - -and after any command except USERPASS the usher will send a reply and -close the connection. The reply will always end with a newline. - -- USERPASS username password - - Required before any other command, so random people can't do bad things. - If incorrect, the connection will be closed immediately. - -- MATCH host pattern - - Looks up the name of the server which 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 server, as named by the "server" lines in the - config file. If a server is specified, the result will be one of: - - REMOTE This is a remote server without active connections - ACTIVE n This server currently has n active connections - WAITING This (local) server is running, but has no connections - SLEEPING This (local) server is not running, but is available - STOPPING n This (local) server has been asked to stop, but still - has n active connections. It will not accept further - connections. - STOPPED This (local) server has been stopped, and will not - accept connections. The server process is not running. - SHUTTINGDOWN The usher has been shut down, no servers are accepting - connections. - SHUTDOWN The usher has been shut down, all connections have - been closed, and all local server processes have been - stopped. - -If no server is specified, the repsonse will be SHUTTINGDOWN, SHUTDOWN, -WAITING, or ACTIVE (with n being the total number of open connections, -across all servers). - -- LISTCONNECTIONS [servername] - - Returns a space-separated list of all clients connected to the given - server, or connected to any server is the servername is not provided. - - Example output: "(servername)123.123.123.123:123 (servername)127.0.2.4:1025" - - 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 become STOPPING, and WAITING - and SLEEPING servers 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. (A server in the - "STOPPING" state becomes ACTIVE, and a STOPPED server becomes SLEEPING. - A server in some other state is not affected.) - -- LIST [state] - - Returns a space-separated list of all servers. If a state is given, only - list the servers that are in that state. - -- SHUTDOWN - - Do not accept new connections for any servers, local or remote. - Returns "ok". - -- STARTUP - - Begin accepting connections again after a SHUTDOWN. Returns "ok". - -- CONNECTIONS - - Returns the number of connections currently open. - -- RELOAD - - Reload the config file (same as sending SIGHUP). The reply will be "ok", - and will not be given until the config file has been reloaded. - +If you want to get your list of servers from someplace other than direclty +included in the config file, you'll want to subclass serverlist_reader (see +basic_io_serverlist_reader for an example), and then change src/usher.cc to +use your new subclass instead of basic_io_serverlist_reader. \ No newline at end of file