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
.\"* 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
.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
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 "\-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
if the server has or hasn't (respectively) become a daemon.
.RE
.SP
+.BI "SETIFNAME " peer " " new-name
+Informs the server that the
+.IR peer 's
+tunnel-interface name has been changed to
+.IR new-name .
+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
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
+is already the tag of an outstanding job.
+.SP
.BI "unknown-command " token
The command
.B token
.BR ADDR ,
.BR IFNAME ,
.BR KILL ,
+.BR SETIFNAME ,
and
.BR STATS .)
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.
has begun or restarted. If key exchange keeps failing, this message
will be repeated periodically.
.SP
+.BI "NEWIFNAME " peer " " old-name " " new-name
+The given
+.IR peer 's
+tunnel interface name has been changed from
+.I old-name
+to
+.IR new-name ,
+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
.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