# # # patch "README" # from [da9ddd5105546b034c6da8e20d8ad3752c6329e0] # to [8b05deed0806eb11afddcfd9f4fb71290973f90c] # ============================================================ --- README da9ddd5105546b034c6da8e20d8ad3752c6329e0 +++ README 8b05deed0806eb11afddcfd9f4fb71290973f90c @@ -1,214 +1,258 @@ 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. + +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 means it only works -for recent (0.23 or later) clients. In order to match against hostnames -a post-0.23 client is needed (0.23 clients can only be matched against -their include pattern). +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. -Usage: +Usage: usher [-p pidfile] 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. + -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.) + +- 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 -Config file syntax ------------------- -The configuration file for usher is in 'basic_io' like formate, similare to -what monotone uses. +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" ... + keyword "value" "value2" "value3" ... -* values are separated by spaces and enclosed by double quotes. -* blocks of lines are separated by empty lines +- 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/" + 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 "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" "*" + 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. + +- 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 +- 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) + +- 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 +- 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 config - file (described below) appended with '.log' + +- 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 config 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: +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. -server "" -host "" -pattern "" -remote "" +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 "" "" "" ..."" + 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: +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'. [: I could not get this to work at all?] -- 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. +- directed to the host at 'ipaddress:port' if the last line of the block + is 'remote'. -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'. +- 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. +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) -[ is this at all affecting performance, wrt cache?] +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. -Current range is: 127.0.1.1 - 127.254.254.254 - +The current range is: 127.0.1.1 - 127.254.254.254 + + Administrative interface ------------------------ -If the 'adminaddr' keyword line is given in the config 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] +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 +- 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 +- 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] +- 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 + + 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. - SHUTDOWN - the usher has been shut down, all connections have been closed, - and all local server processes have been stopped. - + 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. - "(servername)123.123.123.123:12345 (servername)127.0.2.4:1025" +- 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. +- STOP servername -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.) + 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. -LIST [state] +- 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". +- SHUTDOWN -STARTUP + Do not accept new connections for any servers, local or remote. + Returns "ok". + +- STARTUP + Begin accepting connections again after a SHUTDOWN. Returns "ok". -CONNECTIONS +- CONNECTIONS + Returns the number of connections currently open. -RELOAD +- 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.