# # # delete "README" # # rename "usher.txt" # to "README" # # patch "README" # from [655e06cb83faec8b3d9f9bd72e11f41d5997c51d] # to [dfd06ce97cbe36c3af669ff2ec827a5e42d6bb76] # # patch "server_manager.cc" # from [6482a786cfbc434d73b33edac40941d3cc52acd8] # to [20966d0c9b18c0095866c15175b1351e902eb70b] # ============================================================ --- usher.txt 655e06cb83faec8b3d9f9bd72e11f41d5997c51d +++ README dfd06ce97cbe36c3af669ff2ec827a5e42d6bb76 @@ -1,131 +1,203 @@ - -This is an "usher" to allow multiple monotone servers to work from +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 that server. All servers using the same usher need -to have the same server key. +the connection to the specific instance belonging to that server. +All servers using the same usher need to have the same server key. -This requires cooperation from the client, which means it only works +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). -Usage: usher [-l address[:port]] [-a address:port] [-p pidfile] +Usage: + usher [-p pidfile] -options: --p a file (deleted on program exit) to record the pid of the usher in - a file that looks like - userpass "username" "password" - monotone "mtn" "-k" "my_key" - adminaddr "127.0.0.1:12345" - logdir "/var/log/usher" +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 - 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/mt.db~" "*" +Config file syntax +------------------ +The configuration file for usher is in 'basic_io' like formate, similare to +what monotone uses. -or in general, one block of one or more lines of - userpass -and optionally any of - monotone - adminaddr
: - listenaddr
: -followed by any number of blocks of a - server -line followed by one or more - host -lines and/or one or more - pattern -lines, and one of - remote - local -, with blocks separated by blank lines. +It consists of lines with the following general syntax: -"userpass" lines specify who is allowed to use the administrative port. -If there is no "monotone" line, it defaults to "mtn". If there is no -"listenaddr" line, it defaults to "0.0.0.0:4691". If there is no "logdir" line, -it defaults to "./". Note that the directory specified in "logdir" must -already exist. +keyword "value" "value2" "value3" ... -A request to server "hostname" will be directed to the -server at :, if that stem is marked as remote, -and to a local server managed by the usher, started with the given -arguments ("mtn serve --bind=something "), if it is -marked as local. -Note that "hostname" has to be an initial substring of who 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 - or : . +* values are separated by spaces and enclosed by double quotes. +* blocks of lines are separated by empty lines -If no server with a matching hostname is found, the include pattern will be -compared against the "pattern" lines in the same way. In particular, not that -the pattern lines are not globs; they are initial substrings just like the -"host" 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/" -Admin commands +server "monotone" +host "localhost" +pattern "net.venge.monotone" +remote "66.96.28.3:4691" -If the -a option is given, the usher will listen for administrative -connections on that port. The connecting client gives commands of the form - COMMAND [arguments] -, and after any command except USERPASS the usher will send a reply and +server "local" +host "127.0.0.1" +pattern "*" +local "-d" "/usr/local/src/managed/my.db" "*" + +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 config + 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: + +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'. [: 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. + +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) +[ is this at all affecting performance, wrt cache?] +Similarly, usher will use the local address interface for the address range. +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] + +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. + Required before any other command, so random people can't do bad things. + If incorrect, the connection will be closed immediately. 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. + 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). 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. + 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.) + 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. + 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". + Do not accept new connections for any servers, local or remote. Returns "ok". STARTUP -Begin accepting connections again after a SHUTDOWN. Returns "ok". + Begin accepting connections again after a SHUTDOWN. Returns "ok". CONNECTIONS -Returns the number of connections currently open. + 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. + 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. ============================================================ --- server_manager.cc 6482a786cfbc434d73b33edac40941d3cc52acd8 +++ server_manager.cc 20966d0c9b18c0095866c15175b1351e902eb70b @@ -213,8 +213,9 @@ } return ss; } - else - throw errstr("Cannot find server."); + else { + throw errstr("Could not find a monotone instance for the pattern '" + pattern + "', perhaps make it less generic?."); + } } void server_manager::disconnect_from_server(serversock const &s)