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
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
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
.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.
.\"* 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
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
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
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 .
.BR ADD .
.SP
.BI "NOTIFY " tokens\fR...
-Issues a
+Issues a
.B USER
notification to all interested administration clients.
.SP
.RS
.TP
.BI "ping-ok " millis
-A response was received
+A response was received
.I millis
after the ping was sent.
.TP
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
.SP
.BR "TRACE " [\fIoptions\fP]
Selects trace outputs: see
-.B "Trace lists"
+.B "Trace lists"
above. Message types provided are:
.RS
.PP
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:
.RE
.SP
.BI "WARN " tokens\fR...
-Issues a
+Issues a
.B USER
warning to all interested administration clients.
.SH "ERROR MESSAGES"
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 ,
.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
+is already the tag of an outstanding job.
+.SP
.BI "unknown-command " token
The command
.B token
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.
.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
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
.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
.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
.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.
.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
~mdw / tripe / blobdiff