[Monotone-commits-diffs] net.venge.monotone.contrib.usher: 36e46d4ba9989e8b19a7b22cbdcc0c6ecf0ae75b

[code]

revision:            36e46d4ba9989e8b19a7b22cbdcc0c6ecf0ae75b
date:                2011-01-20T02:41:48
author:              Richard Levitte <address@hidden>
branch:              net.venge.monotone.contrib.usher
changelog:
Add manpages for usher itself and its configuration

manifest:
format_version "1"

new_manifest [5ad1aa61f2abfd8cac21227bd18aa870d114c418]

old_revision [ffab41cdc88376366b3e91cb4c4635197394b6f4]

add_file "doc/usher.1"
 content [ada4715fe014deb2c039d5e21a85247e467d4ea3]

add_file "doc/usher.conf.5"
 content [7a7f424ffcc8d596e24cd61060cac707338ed781]
============================================================
--- /dev/null	
+++ doc/usher.1	ada4715fe014deb2c039d5e21a85247e467d4ea3
@@ -0,0 +1,53 @@
+.\" Man page formatted with recommendations from
+.\" http://www.schweikhardt.net/man_page_howto.html
+.\"
+.\" However, font usage is a bit lacking, so I took inspiration from
+.\" http://fog.ccsf.cc.ca.us/~gboyd/cs260a/online/man/page_format.html
+.\"
+.\" Font usage:
+.\" commands, keywords, option markers: bold (\fB or .B)
+.\" arguments and other input: italic (\fI or .I)
+.\" optional markers ([, ], ...): regular (\fP)
+.\" verbatim text (examples and output): courier (\fC)
+.\"
+.TH "USHER" 1 "2011-01-18" "usher 1.0~dev" "Monotone program suite"
+.SH "NAME"
+usher \- dispatcher for monotone to serve several project databases
+.SH "SYNOPSIS"
+.B usher
+[
+.B \-p
+.I pidfile
+]
+.I config-file
+.SH "DESCRIPTION"
+This is an 'usher' to allow multiple monotone servers to work from the
+same port.  The monotone client specifies a host name and a branch
+pattern with which it wants to sync;
+.B usher
+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
+.BR usher )
+need to have the same server key.
+.PP
+This is mostly useful if you want to serve several completely
+unrelated projects from the same machine.
+.PP
+.B usher
+also has an administrative interface that can be reached with telnet,
+for finer control of the dispatcher.
+.PP
+.B usher
+is controlled with a configuration file.  The syntax of that file is
+described in
+.BR usher.conf (5).
+.SH "OPTIONS"
+.IP "\fB-p\fP \fIpidfile\fP"
+the path to a file to record the identity of the process running
+usher.  This file is deleted when usher terminates.
+.SH "SEE ALSO"
+.BR usher.conf (5)
+.SH "AUTHOR"
+.nf
+Richard Levitte <address@hidden>
============================================================
--- /dev/null	
+++ doc/usher.conf.5	7a7f424ffcc8d596e24cd61060cac707338ed781
@@ -0,0 +1,252 @@
+.\" Man page formatted with recommendations from
+.\" http://www.schweikhardt.net/man_page_howto.html
+.\"
+.\" However, font usage is a bit lacking, so I took inspiration from
+.\" http://fog.ccsf.cc.ca.us/~gboyd/cs260a/online/man/page_format.html
+.\"
+.\" Font usage:
+.\" commands, keywords, option markers: bold (\fB or .B)
+.\" arguments and other input: italic (\fI or .I)
+.\" optional markers ([, ], ...): regular (\fP)
+.\" verbatim text (examples and output): courier (\fC)
+.\"
+.TH "USHER.CONF" 5 "2011-01-18" "usher 1.0~dev" "Monotone program suite"
+.SH "NAME"
+usher.conf \- configuration file for usher
+.SH "DESCRIPTION"
+A 
+.B usher
+configuration file contains instructions for the monotone dispatcher
+usher.  The general syntax is a series of lines, where each line
+starts with a keyword, which is then followed by one or more strings.
+Such lines are then grouped in stanzas separated by empty lines.
+.PP
+An example configuration file can look like this:
+.PP
+.RS
+.nf
+\fC
+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"
+\fP
+.fi
+.RE
+.SH "GLOBAL DIRECTIVES"
+.TP
+\fBuserpass "\fIusername\fP" "\fIpassword\fP"\fP
+This defines a username/password combination used to access the
+administrative interface (see below). You can have any number of 
+\fBuserpass\fP lines.
+.TP
+\fBmonotone "\fIexecutable\fP" "\fIarg1\fP" "\fIarg2\fP"\fP ...
+Gives the first part of the command line used when spawning local servers.
+.IP
+The default is
+'nh
+\fCmonotone "mtn"\fP.
+'hy 1
+.TP
+\fBadminaddr "\fIaddress:port\fP"\fP
+The address and port for the administrative interface to listen on.
+.TP
+\fBlistenaddr "\fIaddress:port\fP"\fP
+The address and port on which to listen for incoming connections.
+.IP
+The default is
+'nh
+\fClistenaddr "0.0.0.0:4691"\fP.
+'hy 1
+.TP
+\fBlogdir "\fI/path/for/log/files/\fP"\fP
+A path (ending with a slash) where per-server logfiles for local
+servers should be stored.
+.IP
+The default is
+'nh
+\fClogdir "./"\fP.
+.hy 1
+.TP
+\fBscript "\fIname\fP" "\fIexe\fP" "\fIarg\fP"\fP ...
+A script that can be executed by given the \fBRUN\fP command on the
+administrative interface. Any arguments specified in the config file
+will be given before any arguments given to the \fBRUN\fP command.
+
+.SH "PER-SERVER DIRECTIVES"
+.TP
+\fBserver "\fIname\fP"\fP
+Define a new server with the given name. Clients that are version 0.48
+or later can connect to a specific server with
+\fImtn://host.com/servername\fP . If you only expect clients 0.48 or
+newer, this is the preferred dispatch mechanism.
+.TP
+\fBhost "\fIhostname-prefix\fP"\fP
+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.
+.TP
+\fBpattern "\fIpattern-prefix\fP"\fP
+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.
+.TP
+\fBremote "\fIaddress:port\fP"\fP
+Specifies a remote server to forward connections to.  
+.TP
+\fBlocal "\fIarg1\fP" "\fIarg2\fP"\fP ...
+Specifies arguments to append to the command line in the
+\fBmonotone\fP directive, to spawn a local server to forward
+connections to.
+.SH "ADMINISTRATIVE INTERFACE"
+If the \fBadminaddr\fP 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 following
+form, ending with a newline:
+.IP
+.I COMMAND
+[
+.I arg
+] ...
+.PP
+After any command except
+.B USERPASS
+the usher will send a reply and close the connection. The reply will
+end with a newline.
+.SH "ADMINISTRATIVE COMMANDS"
+.TP
+\fBUSERPASS\fP \fIusername password\fP
+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
+\fBuserpass\fP lines in the config file, the connection will be
+closed.
+.TP
+\fBMATCH\fP \fIhost pattern\fP
+Looks up the name of the server that would be used for an incoming
+connection having the given host and pattern.
+Returns "\fCOK: \fIservername\fR" if a match is found,
+or "\fCERROR: \fImessage\fR" if no match is found.
+.TP
+\fBSTATUS\fP [ \fIservername\fP ]
+Get the status of a particular server, or of the usher as a whole if
+no server is specified.
+.RS
+.PP
+If a server is specified, the result will be one of
+.IP "\fCREMOTE\fP"
+This is a remote server without open connections.
+.IP "\fCACTIVE \fP\fIn\fP"
+This server currently has n open connections
+.IP "\fCWAITING\fP"
+This (local) server is running, but has no open connections.
+.IP "\fCSLEEPING\fP"
+This (local) server is not running, but is available to connect to.
+.IP "\fCSTOPPING \fP\fIn\fP"
+This (local) server has been asked to stop, but still has n open
+connections. It will not accept further connections.
+.IP "\fCSTOPPED\fP"
+This (local) server is not running, and will not accept connections.
+.IP "\fCSHUTTINGDOWN\fP"
+The usher is being shut down, and will not accept further
+connections.
+.IP "\fCSHUTDOWN\fP"
+The usher has been shut down, and will not accept connections. All
+local servers have been stopped.
+.PP
+If no server is specified, the response will be \fCWAITING\fP,
+\fCACTIVE\fP, \fCSHUTTINGDOWN\fP, or \fCSHUTDOWN\fP, with
+.I n
+being the total number of open connections across all servers.
+.RE
+.TP
+\fBLISTCONNECTIONS\fP [ \fIservername\fP ]
+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.  
+.TP
+\fBSTOP\fP \fIservername\fP
+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: \fCACTIVE\fP local servers will become
+\fCSTOPPING\fP, and \fCWAITING\fP and \fCSLEEPING\fP serveres become \fCSTOPPED\fP. Servers in
+other states are not affected.  
+.TP
+\fBSTART\fP \fIservername\fP
+Allow a \fCSTOPPED\fP or \fCSTOPPING\fP server to receive connections again.
+The result will be the new status of that server: \fCSTOPPING\fP servers
+become \fCACTIVE\fP, and \fCSTOPPED\fP servers become \fCSLEEPING\fP. Servers in other
+states are not affected.
+.TP
+\fBKILL_NOW\fP \fIservername\fP
+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 \fCSTOPPED\fP.
+.TP
+\fBLIST\fP [ \fIstate\fP ]
+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.
+.TP
+\fBSHUTDOWN\fP
+Do not accept new connections for any servers, local or
+remote. Returns "\fCok\fP".
+.TP
+\fBSTARTUP\fP
+Begin accepting connections after a \fBSHUTDOWN\fP. Returns "\fCok\fP".
+.TP
+\fBCONNECTIONS\fP
+Returns the number of connections currently open.
+.TP
+\fBRELOAD\fP
+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.
+.TP
+\fBRUN\fP \fIscriptname\fP \fIarg\fP ...
+Run the named script, which was defined with the \fBscript\fP config
+file directive. Arguments given here are appended to the end of the
+command line, after any arguments given in the \fBscript\fP
+directive.  Arguments with spaces can be quoted with single or double
+quotes, and the "\en", "\e'", "\e"", and "\e\e" escape sequences are
+recognized except inside single quotes. You cannot use literal
+newlines even inside quotes, but must use "\en" 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.
+.TP
+\fBREMOVE_SERVER\fP \fIservername\fP
+Remove the named server, as if by removing it from the config
+file and giving the \fBRELOAD\fP command. Returns "\fCok\fP", or
+"\fCnot found\fP" if the named server doesn't exist.
+.TP
+\fBADD_SERVER\fP \fIname\fP { \fBremote\fP | \fBlocal\fP } \fIarg\fP ...
+Add a server with the given name and startup arguments (or name and
+address for remote servers).
+"\fIarg\fP ..." is either "\fIhostname port\fP" for remote servers, or
+arguments to the underlying
+.B monotone
+server for local servers. Quotes are treated the same as for
+.BR RUN .
+Returns "\fCok\fP", or an error message.
+.SH "SEE ALSO"
+.BR usher (1)
+.SH "AUTHOR"
+.nf
+Richard Levitte <address@hidden>