X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/64cf222377512d2cbdc8d750420e11cc5ddecdbd..010e6f63edc4be4e127c18fc6c2c2a138efc93d2:/doc/tripe-admin.5.in

diff --git a/doc/tripe-admin.5.in b/doc/tripe-admin.5.in
index 0d9e7b66..caaf2557 100644
--- a/doc/tripe-admin.5.in
+++ b/doc/tripe-admin.5.in
@@ -25,9 +25,6 @@ clients can be written in scripting languages such as Perl, Python or
 Tcl, or more advanced clients such as GUI monitors can be written in C
 with little difficulty.
 .PP
-By default, the server listens for admin connections on the Unix-domain
-socket
-.BR /var/lib/tripe/tripesock .
 Administration commands use a textual protocol.  Each client command or
 server response consists of a line of ASCII text terminated by a single
 linefeed character.  No command may be longer than 255 characters.
@@ -65,10 +62,15 @@ All commands can be run as simple commands.  Long-running commands
 and
 .BR PING )
 block the client until they finish, but the rest of the server continues
-running.
-.SS "Asynchronous messages"
-There are three types of asynchronous messages which
-aren't associated with any particular command.
+running.  See
+.B "Background commands"
+to find out how to issue long-running commands without blocking.
+.SS "Asynchronous broadcasts"
+There are three types of asynchronous broadcast messages which aren't
+associated with any particular command.  Clients can select which
+broadcast messages they're interested in using the
+.B WATCH
+command.
 .PP
 The
 .B WARN
@@ -92,10 +94,6 @@ Finally, the
 .B NOTE
 message is a machine-readable notification about some routine but
 interesting event such as creation or destruction of peers.
-.PP
-The presence of asynchronous messages can be controlled using the
-.B WATCH
-command.
 .SS "Background commands"
 Some commands (e.g.,
 .B ADD
@@ -122,12 +120,12 @@ option.  From this point on, the server is ready to process more
 commands and reply to them.
 .PP
 Responses to background commands are indicated by a line beginning with
-one of the tokens 
+one of the tokens
 .BR BGOK ,
 .BR BGFAIL ,
 or
 .BR BGINFO ,
-followed by the command tag.  These correspond to the 
+followed by the command tag.  These correspond to the
 .BR OK ,
 .BR FAIL ,
 and
@@ -150,6 +148,64 @@ response: it will always detach and then issue any
 lines followed by
 .B BGOK
 response.
+.SS "Client-provided services"
+.\"* 25 Service-related messages
+An administration client can provide services to other clients.
+Services are given names and versions.  A client can attempt to
+.I claim
+a particular service by issuing the
+.B SVCCLAIM
+command.  This may fail, for example, if some other client already
+provides the same or later version of the service.
+.PP
+Other clients can issue
+.I "service commands"
+using the
+.B "SVCSUBMIT"
+command; the service provider is expected to handle these commands and
+reply to them.
+.PP
+There are three important asynchronous messages which will be sent to
+service providers.
+.SP
+.BI "SVCCANCEL " jobid
+The named job has been cancelled, either because the issuing client has
+disconnected or explicitly cancelled the job using the
+.B BGCANCEL
+command.
+.SP
+.BI "SVCCLAIM " service " " version
+Another client has claimed a later version of the named
+.I service.  The recipient is no longer the provider of this service.
+.SP
+.BI "SVCJOB " jobid " " service " " command " " args \fR...
+Announces the arrival of a new job.  The
+.I jobid
+is a simple token consisting of alphanumeric characters which
+.B tripe
+uses to identify this job.
+.PP
+The service provider can reply to the job using the commands
+.BR SVCINFO ,
+.B SVCOK
+and
+.BR SVCFAIL .
+The first of these sends an
+.B INFO
+response and leaves the job active; the other two send an
+.B OK
+or
+.B FAIL
+response respectively, and mark the job as being complete.
+.PP
+(Since
+.B SVCSUBMIT
+is a potentially long-running command, it can be run in the background.
+This detail is hidden from service providers:
+.B tripe
+will issue the corresponding
+.BR BG ...
+responses when appropriate.)
 .SS "Network addresses"
 A network address is a sequence of words.  The first is a token
 identifying the network address family.  The length of an address and
@@ -159,19 +215,19 @@ are always in upper-case.
 .PP
 At present, only one address family is understood.
 .TP
-.BI "INET " address " " port
+.BI "INET " address " \fR[" port \fR]
 An Internet socket, naming an IPv4 address and UDP port.  On output, the
 address is always in numeric dotted-quad form, and the port is given as
 a plain number.  On input, DNS hostnames and symbolic port names are
-permitted.  Name resolution does not block the main server, but will
-block the requesting client.  This hopefully makes life simpler for
-stupid clients.  Complex clients which don't wish to be held up can open
-extra connections or do the resolution themselves.)
+permitted; if omitted, the default port 4070 is used.  Name resolution
+does not block the main server, but will block the requesting client,
+unless the command is run in the background.
 .PP
 If, on input, no recognised address family token is found, the following
 words are assumed to represent an
 .B INET
-address.
+address.  Addresses output by the server always have an address family
+token.
 .SS "Key-value output"
 Some commands (e.g.,
 .B STATS
@@ -202,7 +258,7 @@ one to an
 .B INFO
 line, in a fixed-column format.  Column zero contains the key letter for
 selecting that message type; column one contains either a space or a
-.RB ` + ' 
+.RB ` + '
 sign, if the message type is disabled or enabled respectively; and a
 textual description of the message type begins at column 3 and continues
 to the end of the line.
@@ -213,7 +269,7 @@ letters control collections of message types.
 .\"* 10 Commands
 The commands provided are:
 .SP
-.BI "ADD " peer " \fR[" options "\fR] " address "\fR..."
+.BI "ADD \fR[" options "\fR] " peer " " address "\fR..."
 Adds a new peer.  The peer is given the name
 .IR peer ;
 the peer's public key is assumed to be in the file
@@ -231,6 +287,10 @@ be contacted.  The following options are recognised.
 Run the command in the background, using the given
 .IR tag .
 .TP
+.B "\-cork"
+Don't send an immediate challenge to the peer; instead, wait until it
+sends us something before responding.
+.TP
 .BI "\-keepalive " time
 Send a no-op packet if we've not sent a packet to the peer in the last
 .I time
@@ -257,6 +317,10 @@ Emits an
 line reporting the IP address and port number stored for
 .IR peer .
 .SP
+.BI "BGCANCEL " tag
+Cancels the background job with the named
+.IR tag .
+.SP
 .BI "CHECKCHAL " challenge
 Verifies a challenge as being one earlier issued by
 .B GETCHAL
@@ -267,7 +331,7 @@ or in a greeting message.
 .B "DAEMON"
 Causes the server to disassociate itself from its terminal and become a
 background task.  This only works once.  A warning is issued.
-.TP
+.SP
 .BI "EPING \fR[" options "\fR] " peer
 Sends an encrypted ping to the peer, and expects an encrypted response.
 This checks that the peer is running (and not being impersonated), and
@@ -301,7 +365,7 @@ Causes the server to emit an
 line for each command it supports.  Each line lists the command name,
 followed by the names of the arguments.  This may be helpful as a memory
 aid for interactive use, or for program clients probing for features.
-.SP 
+.SP
 .BI "IFNAME " peer
 Emits an
 .B INFO
@@ -311,6 +375,11 @@ packets which are to be encrypted and sent to
 Used by configuration scripts so that they can set up routing tables
 appropriately after adding new peers.
 .SP
+.B "JOBS"
+Emits an
+.B INFO
+line giving the tag for each outstanding background job.
+.SP
 .BI "KILL " peer
 Causes the server to forget all about
 .IR peer .
@@ -325,7 +394,7 @@ line is written containing the peer's name, as given to
 .BR ADD .
 .SP
 .BI "NOTIFY " tokens\fR...
-Issues a 
+Issues a
 .B USER
 notification to all interested administration clients.
 .SP
@@ -356,7 +425,7 @@ line is printed describing the outcome:
 .RS
 .TP
 .BI "ping-ok " millis
-A response was received 
+A response was received
 .I millis
 after the ping was sent.
 .TP
@@ -379,10 +448,16 @@ Run the command in the background, using the given
 .BI "\-timeout " time
 Wait for
 .I time
-seconds before giving up on a response.  The default is 5 seconds.  (The
-time format is the same as for the
-.B "ADD \-keepalive"
-option.)
+seconds before giving up on a response.  The default is 5 seconds.  The
+.I time
+is expressed as a nonnegative integer followed optionally by
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.BR s
+for days, hours, minutes, or seconds respectively; if no suffix is
+given, seconds are assumed.
 .\"-opts
 .RE
 .SP
@@ -434,6 +509,108 @@ This is useful if firewalling decisions are made based on interface
 names: a setup script for a particular peer can change the name, and
 then update the server's records so that they're accurate.
 .SP
+.BI "SVCCLAIM " service " " version
+Attempts to claim the named
+.IR service ,
+offering the given
+.IR version .
+The claim is successful if the service is currently unclaimed, or if
+a version earlier than
+.I version
+is provided; otherwise the command fails with the error
+.BR "service-exists" .
+.SP
+.BI "SVCENSURE " service " \fR[" version \fR]
+Ensure that
+.I service
+is provided, and (if specified) to at least the given
+.IR version .
+An error is reported if these conditions are not met; otherwise the
+command succeeds silently.
+.SP
+.BI "SVCFAIL " jobid " " tokens \fR...
+Send a
+.B FAIL
+(or
+.BR BGFAIL )
+response to the service job with the given
+.IR jobid ,
+passing the
+.I tokens
+as the reason for failure.  The job is closed.
+.SP
+.BI "SVCINFO " jobid " " tokens \fR...
+Send an
+.B INFO
+(or
+.BR BGINFO )
+response to the service job with the given
+.IR jobid ,
+passing the
+.I tokens
+as the info message.  The job remains open.
+.SP
+.B "SVCLIST"
+Output a line of the form
+.RS
+.IP
+.B INFO
+.I service
+.I version
+.PP
+for each service currently provided.
+.RE
+.SP
+.BI "SVCOK " jobid
+Send an
+.B OK
+(or
+.BR BGINFO )
+response to the service job with the given
+.IR jobid .
+The job is closed.
+.SP
+.BI "SVCQUERY " service
+Emits a number of
+.B info
+lines in key-value format, describing the named
+.IR service.
+The following keys are used.
+.RS
+.TP
+.B name
+The service's name.
+.TP
+.B version
+The service's version string.
+.RE
+.SP
+.BI "SVCRELEASE " service
+Announce that the client no longer wishes to provide the named
+.IR service .
+.SP
+.BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR...
+Submit a job to the provider of the given
+.IR service ,
+passing it the named
+.I command
+and the given
+.IR arguments .
+The following options are accepted.
+.RS
+.\"+opts
+.TP
+.BI "\-background " tag
+Run the command in the background, using the given
+.IR tag .
+.TP
+.BI "\-version " version
+Ensure that at least the given
+.I version
+of the service is available before submitting the job.
+.RE
+.\"-opts
+.SP
 .BI "STATS " peer
 Emits a number of
 .B INFO
@@ -443,7 +620,7 @@ The statistics-gathering is experimental and subject to change.
 .SP
 .BR "TRACE " [\fIoptions\fP]
 Selects trace outputs: see
-.B "Trace lists" 
+.B "Trace lists"
 above.  Message types provided are:
 .RS
 .PP
@@ -524,15 +701,15 @@ its version string.  The server name
 is reserved to the Straylight/Edgeware implementation.
 .SP
 .BR "WATCH " [\fIoptions\fP]
-Enables or disables asynchronous messages
+Enables or disables asynchronous broadcasts
 .IR "for the current connection only" .
 See
-.B "Trace lists" 
+.B "Trace lists"
 above.  The default watch state for the connection the server opens
 automatically on stdin/stdout is to show warnings and trace messages;
-other connections show no asynchronous messages.  (This is done in order
-to guarantee that a program reading the server's stdout does not miss
-any warnings.)
+other connections show no asynchronous broadcast messages.  (This is
+done in order to guarantee that a program reading the server's stdout
+does not miss any warnings.)
 .RS
 .PP
 Message types provided are:
@@ -554,7 +731,7 @@ All of the above.
 .RE
 .SP
 .BI "WARN " tokens\fR...
-Issues a 
+Issues a
 .B USER
 warning to all interested administration clients.
 .SH "ERROR MESSAGES"
@@ -585,7 +762,7 @@ of arguments was wrong.
 The
 .I word
 is not a valid time interval specification.  Acceptable time
-specifications are nonnegative integers followed optionally by 
+specifications are nonnegative integers followed optionally by
 .BR d ,
 .BR h ,
 .BR m ,
@@ -614,6 +791,13 @@ An error occurred during the attempt to become a daemon, as reported by
 .BR ADD .)
 The given port number is out of range.
 .SP
+.BI "not-service-provider " service
+(For
+.BR SVCRELEASE .)
+The invoking client is not the current provider of the named
+.IR service ,
+and is therefore not allowed to release it.
+.SP
 .BI "peer-create-fail " peer
 (For
 .BR ADD .)
@@ -646,6 +830,30 @@ The DNS name
 .I hostname
 took too long to resolve.
 .SP
+.BI "service-exists " service " " version
+(For
+.BR SVCCLAIM .)
+Another client is already providing the stated
+.I version
+of the
+.IR service .
+.SP
+.BI "service-too-old " service " " version
+(For
+.B SVCENSURE
+and
+.BR SVCSUBMIT .)
+Only the given
+.I version
+of the requested
+.I service
+is available, which does not meet the stated requirements.
+.SP
+.BI "tag-exists " tag
+(For long-running commands.)  The named
+.I tag
+is already the tag of an outstanding job.
+.SP
 .BI "unknown-command " token
 The command
 .B token
@@ -662,13 +870,32 @@ and
 There is no peer called
 .IR name .
 .SP
-.BI "unknown-service " service
+.BI "unknown-port " port
 (For
 .BR ADD .)
-The service name
-.I service
-couldn't be found in 
+The port name
+.I port
+couldn't be found in
 .BR /etc/services .
+.TP
+.BI "unknown-service " service
+(For
+.BR SVCENSURE ,
+.BR SVCQUERY ,
+.BR SVCRELEASE ,
+and
+.BR SVCSUBMIT .)
+The token
+.I service
+is not recognized as the name of a client-provided service.
+.TP
+.BI "unknown-tag " tag
+(For
+.BR BGCANCEL .)
+The given
+.I tag
+is not the tag for any outstanding background job.  It may have just
+finished.
 .SH "NOTIFICATIONS"
 .\"* 30 Notification broadcasts (NOTE codes)
 The following notifications are sent to clients who request them.
@@ -717,6 +944,17 @@ as a result of a
 .B SETIFNAME
 command.
 .SP
+.BI "SVCCLAIM " service " " version
+The named
+.I service
+is now available, at the stated
+.IR version .
+.SP
+.BI "SVCRELEASE " service
+The named
+.I service
+is no longer available.
+.SP
 .BI "USER " tokens\fR...
 An administration client issued a notification using the
 .B NOTIFY
@@ -795,7 +1033,7 @@ there was a problem with the file, usually there will have been
 warnings before this.
 .SP
 .BI "KEYMGMT bad-public-keyring " message
-The public keyring couldn't be read.  Usually, there will have been 
+The public keyring couldn't be read.  Usually, there will have been
 .B key-file-error
 warnings before this.
 .SP
@@ -892,7 +1130,7 @@ hard asymmetric crypto sums.
 .BI "KX " peer " unexpected " msgtoken
 The message received wasn't appropriate for this stage of the key
 exchange process.  This may mean that one of our previous packets got
-lost.  For 
+lost.  For
 .BR pre-challenge ,
 it may simply mean that the peer has recently restarted.
 .SP
@@ -908,7 +1146,7 @@ An unknown key-exchange message arrived.
 .SS "PEER warnings"
 These are largely concerned with management of peers and the low-level
 details of the network protocol.  The second word is usually the name of
-a peer, or 
+a peer, or
 .RB ` \- '
 if none is relevant.
 .SP
@@ -1026,11 +1264,11 @@ if none.
 .SP
 .BI "TUN \- bsd no-tunnel-devices"
 The driver couldn't find an available tunnel device.  Maybe if you
-create some more 
+create some more
 .BI /dev/tun nn
 files, it will work.
 .SP
-.BI "TUN - " tun-name " open-error " device " " ecode " " message
+.BI "TUN \- " tun-name " open-error " device " " ecode " " message
 An attempt to open the tunnel device file
 .I device
 failed.
@@ -1081,10 +1319,6 @@ shouldn't be used any more.
 .BI "TUN \- unet getinfo-error " ecode " " message
 Reading information about the Unet interface failed.  Unet is obsolete
 and shouldn't be used any more.
-.SP
-.BI "TUN \- unet ifname-too-long"
-The Unet interface's name overflowed, so we couldn't read it properly.
-Unet is obsolete and shouldn't be used any more.
 .SS "USER warnings"
 These are issued by administration clients using the
 .B WARN
@@ -1096,6 +1330,7 @@ An administration client issued a warning.
 .SH "SUMMARY"
 .SS "Command responses"
 .nf
+.BI "BGDETACH " tag
 .BI "BGFAIL " tag " " tokens \fR...
 .BI "BGINFO " tag " " tokens \fR...
 .BI "BGOK " tag