server: Correct handling of interface names in tun interface.

[tripe] / doc / tripe-admin.5.in

diff --git a/doc/tripe-admin.5.in b/doc/tripe-admin.5.in
index 4a966aa..94c7c3b 100644 (file)
--- 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
 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.
 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
 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
 .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.
 .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
 .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.
 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
 .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
 .\"* 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
 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
 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
 .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
 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 .
 .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
 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
 .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]
 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;
 .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:
 .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
 .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 .)
 .BI "peer-create-fail " peer
 (For
 .BR ADD .)


@@ -651,6 +825,30 @@ The DNS name
 .I hostname
 took too long to resolve.
 .SP
 .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
 .BI "unknown-command " token
 The command
 .B token


@@ -667,13 +865,32 @@ and
 There is no peer called
 .IR name .
 .SP
 There is no peer called
 .IR name .
 .SP

-.BI "unknown-service " service
+.BI "unknown-port " port

 (For
 .BR ADD .)
 (For
 .BR ADD .)

-The service name
-.I service
+The port name
+.I port

 couldn't be found in 
 .BR /etc/services .
 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.
 .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
 .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
 .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 /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.
 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.
 .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
 .SS "USER warnings"
 These are issued by administration clients using the
 .B WARN