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.
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
.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
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
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.)
+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
.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
.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
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
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:
.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 .)
.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
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 .)
.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 /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.
.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
.SH "SUMMARY"
.SS "Command responses"
.nf
+.BI "BGDETACH " tag
.BI "BGFAIL " tag " " tokens \fR...
.BI "BGINFO " tag " " tokens \fR...
.BI "BGOK " tag
~mdw / tripe / blobdiff