identifying the type of command or response contained. Keywords in
client commands are not case-sensitive; the server always uses uppercase
for its keywords.
-.SS "Server responses"
-For client command, the server responds with zero or more
+.SS "Simple commands"
+For simple client command, the server responds with zero or more
.B INFO
lines, followed by either an
.B OK
code is followed by a machine-readable explanation of why the command
failed.
.PP
-In addition, there are three types of asynchronous messages which
-aren't associated with any particular command. The
+Simple command processing is strictly synchronous: the server reads a
+command, processes it, and responds, before reading the next command.
+All commands can be run as simple commands. Long-running commands
+(e.g.,
+.B ADD
+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.
+.PP
+The
.B WARN
message contains a machine-readable message warning of an error
encountered while processing a command, unexpected or unusual behaviour
by a peer, or a possible attack by an adversary. Under normal
-conditions, the server shouldn't emit any warnings. The
+conditions, the server shouldn't emit any warnings.
+.PP
+The
.B TRACE
message contains a human-readable tracing message containing diagnostic
information. Trace messages are controlled using the
.B TRACE
administration command (see below). Support for tracing can be disabled
when the package is being configured, and may not be available in your
-version. Finally, the
+version.
+.PP
+Finally, the
.B NOTE
message is a machine-readable notification about some routine but
interesting event such as creation or destruction of peers.
The presence of asynchronous messages can be controlled using the
.B WATCH
command.
+.SS "Background commands"
+Some commands (e.g.,
+.B ADD
+and
+.BR PING )
+take a long time to complete. To prevent these long-running commands
+from tying up a server connection, they can be run in the background.
+Not all commands can be run like this: the ones that can provide a
+.B \-background
+option, which must be supplied with a
+.IR tag .
+.PP
+A command may fail before it starts running in the background. In this
+case, the server emits a
+.B FAIL
+response, as usual. To indicate that a command has started running in
+the background, the server emits a response of the form
+.BI "BGDETACH " tag \fR,
+where
+.I tag
+is the value passed to the
+.B \-background
+option. From this point on, the server is ready to process more
+commands and reply to them.
+.PP
+Responses to background commands are indicated by a line beginning with
+one of the tokens
+.BR BGOK ,
+.BR BGFAIL ,
+or
+.BR BGINFO ,
+followed by the command tag. These correspond to the
+.BR OK ,
+.BR FAIL ,
+and
+.B INFO
+responses for simple commands:
+.B BGINFO
+indicates information from a background command which has not completed
+yet; and
+.B BGOK
+and
+.B BGFAIL
+indicates that a background command succeeded or failed, respectively.
+.PP
+A background command will never issue an
+.B OK
+response: it will always detach and then issue a
+.B BGOK
+response.
.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
be contacted. The following options are recognised.
.RS
.TP
+.BI "\-background " tag
+Run the command in the background, using the given
+.IR tag .
+.TP
.BI "\-keepalive " time
Send a no-op packet if we've not sent a packet to the peer in the last
.I time
.B PING
command.
.TP
+.BI "FORCEKX " peer
+Requests the server to begin a new key exchange with
+.I peer
+immediately.
+.TP
.B "HELP"
Causes the server to emit an
.B INFO
Options recognized for this command are:
.RS
.TP
+.BI "\-background " tag
+Run the command in the background, using the given
+.IR tag .
+.TP
.BI "\-timeout " time
Wait for
.I time
server. If you've allowed your server to allocate a port dynamically,
this is how to find out which one it chose.
.TP
+.B "RELOAD"
+Instructs the server to recheck its keyring files. The server checks
+these periodically anyway but it may be necessary to force a recheck,
+for example after adding a new peer key.
+.TP
.B "QUIT"
Instructs the server to exit immediately. A warning is sent.
.TP
.SH "ERROR MESSAGES"
The following
.B FAIL
+(or
+.BR BGFAIL )
messages are sent to clients as a result of errors during command
processing.
.TP
~mdw / tripe / blobdiff