X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/2acd7cd6994079a71ee67280913e162dd814ef31..72917fe7c663aced54f7e1185b7b72ba59aea73c:/doc/tripe-admin.5.in

diff --git a/doc/tripe-admin.5.in b/doc/tripe-admin.5.in
index 4a966aa0..94c7c3b8 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
@@ -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
@@ -212,7 +268,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
@@ -256,6 +312,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
@@ -310,6 +370,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 .
@@ -439,6 +504,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
@@ -529,15 +696,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" 
 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:
@@ -619,6 +786,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 .)
@@ -651,6 +825,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
@@ -667,13 +865,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
+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.
@@ -722,6 +939,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
@@ -1035,7 +1263,7 @@ 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.
@@ -1086,10 +1314,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