Don't send an immediate challenge to the peer; instead, wait until it
sends us something before responding.
.TP
+.B "\-ephemeral"
+The association with the peer is not intended to persist indefinitely.
+If a peer marked as ephemeral is killed, or the
+.BR tripe (8)
+daemon is shut down, send a
+.B bye
+packet to the peer so that it forgets about us; if a peer marked as
+ephemeral sends us a
+.B bye
+packet then it is killed (but in this case no further
+.B bye
+packet is sent). Peers not marked as ephemeral exhibit neither of these
+behaviours; each peer must have the other marked as ephemeral for the
+association to be fully torn down if either end kills the other.
+.TP
.BI "\-keepalive " time
Send a no-op packet if we've not sent a packet to the peer in the last
.I time
to authenticate the peer. The default is to use the key tagged
.IR peer .
.TP
+.BI "\-knock \fR[" prefix .\fR] tag
+Send the string
+.RI [ prefix\fB. ] tag
+in
+.B token-rq
+and
+.B knock
+messages to the peer during key-exchange. The string as a whole should
+name the local machine to the peer, and
+.I tag
+should name its public key. When such messages are received from a
+currently unknown peer,
+.BR tripe (8)
+emits a
+.B KNOCK
+notification stating the peer's (claimed) name and address. The server
+will already have verified that the sender is using the peer's private
+key by this point. This option implies
+.BR \-ephemeral .
+.TP
.B "\-mobile"
The peer is a mobile device, and is likely to change address rapidly.
If a packet arrives from an unknown address, the server's usual response
and if one succeeds, the server will update its idea of the peer's
address and emit an
.B NEWADDR
-notification.
+notification. This option implies
+.BR \-ephemeral .
.TP
.BI "\-priv " tag
Use the private key
The keepalive interval, in seconds, or zero if no keepalives are to be
sent.
.TP
+.B knock
+If present, the string sent to the peer to set up the association; see
+the
+.B \-knock
+option to
+.BR ADD ,
+and the
+.B KNOCK
+notification.
+.TP
.B key
The (short) key tag being used for the peer, as passed to the
.B ADD
.B current-private-key
The full key tag of the private key currently being used for this
association. This may change during the life of the association.
+.TP
+.B corked
+Either
+.B t
+or
+.B nil
+depending on whether or not (respectively) key-exchange is waiting for
+the peer to initiate.
+.TP
+.B mobile
+Either
+.B t
+or
+.B nil
+depending on whether or not (respectively) the peer is expected to
+change its address unpredictably.
+.TP
+.B ephemeral
+Either
+.B t
+or
+.B nil
+depending on whether the association with the peer is expected to be
+temporary or persistent (respectively).
.RE
.SP
.BI "PING \fR[" options "\fR] " peer
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 "STATS " peer
+Emits a number of
+.B INFO
+lines, each containing one or more statistics in the form
+.IB name = value \fR.
+The statistics-gathering is experimental and subject to change.
+.SP
.BI "SVCCLAIM " service " " version
Attempts to claim the named
.IR service ,
.RE
.\"-opts
.SP
-.BI "STATS " peer
-Emits a number of
-.B INFO
-lines, each containing one or more statistics in the form
-.IB name = value \fR.
-The statistics-gathering is experimental and subject to change.
-.SP
.BR "TRACE " [\fIoptions\fP]
Selects trace outputs: see
.B "Trace lists"
The attempt to send a ping packet failed, probably due to lack of
encryption keys.
.SP
+.B "provider-failed"
+(For
+.BR SVCSUBMIT .)
+The service provider disconnected without sending back a final reply to
+the job.
+.SP
+.B "provider-overloaded"
+(For
+.BR SVCSUBMIT .)
+The service provider has too many jobs queued up for it already.
+.SP
.BI "resolve-error " hostname
(For
.BR ADD .)
.I port
couldn't be found in
.BR /etc/services .
-.TP
+.SP
.BI "unknown-service " service
(For
.BR SVCENSURE ,
The token
.I service
is not recognized as the name of a client-provided service.
-.TP
+.SP
.BI "unknown-tag " tag
(For
.BR BGCANCEL .)
.I tag
is not the tag for any outstanding background job. It may have just
finished.
+.SP
+.BI "unknown-tunnel " tun
+(For
+.BR ADD .)
+The given
+.I tun
+is not the name of any known tunnel driver.
.
.\"--------------------------------------------------------------------------
.SH "NOTIFICATIONS"
.I peer
has been killed.
.SP
+.BI "KNOCK " peer " " address
+The currently unknown
+.I peer
+is attempting to connect from
+.IR address .
+.SP
.BI "KXDONE " peer
Key exchange with
.I peer
.I tag
couldn't be found in the keyring.
.SP
+.BI "KEYMGMT " which "-keyring " file " unknown-key-id 0x" keyid
+A key with the given
+.I keyid
+(in hex) was requested but not found.
+.SP
.BI "KEYMGMT " which "-keyring " file " line " line " " message
The contents of the keyring file are invalid. There may well be a bug
in the
.BR challenge ,
.BR reply ,
.BR switch-rq ,
-or
.BR switch-ok .
+.BR token-rq ,
+.BR token ,
+or
+.BR knock .
.SP
.BI "KX " peer " algorithms-mismatch local-private-key " privtag " peer-public-key " pubtag
The algorithms specified in the peer's public key
An error occurred attempting to send a network packet. We lost that
one.
.SP
+.BI "PEER " address\fR... " socket-write-error " ecode " " message
+An error occurred attempting to send a network packet. We lost that
+one.
+.SP
.BI "PEER " peer " unexpected-encrypted-ping 0x" id
The peer sent an encrypted ping response whose id doesn't match any
outstanding ping. Maybe it was delayed for longer than the server was
match any outstanding ping. Maybe it was delayed for longer than the
server was willing to wait, or maybe the peer has gone mad; or maybe
there are bad people trying to confuse you.
+.SS "PRIVSEP warnings"
+These indicate problems with the privilege-separation helper process.
+(The server tries to drop its privileges when it starts up, leaving a
+privileged helper process behind which will create and hand over tunnel
+descriptors on request, but hopefully not do anything else especially
+dangerous. Tunnel descriptors are not completely safe, but this is
+probably better than nothing.)
+.SP
+.BI "PRIVSEP child-exited " rc
+The helper process exited normally with status
+.IR rc .
+Status 0 means that it thought the server didn't want it any more; 1
+means that it was invoked incorrectly; 127 means that some system call
+failed.
+.SP
+.BI "PRIVSEP child-killed " sig
+The helper process was killed by signal number
+.IR sig .
+.SP
+.BI "PRIVSEP child-died " status
+The helper process died in some unexpected way;
+.I status is the raw status code returned by
+.BR waitpid (2),
+because the server didn't understand how to decode it.
+.SP
+.BI "PRIVSEP helper-died"
+A tunnel driver requires a tunnel descriptor from the helper, but the
+helper isn't running so this won't work.
+.SP
+.BI "PRIVSEP helper-read-error " ecode " " message
+The server failed to read a response from the helper process.
+.SP
+.BI "PRIVSEP helper-short-read"
+The helper process didn't send back enough data, and has likely crashed.
+.SP
+.BI "PRIVSEP helper-write-error " ecode " " message
+The server failed to send a message to the helper process.
+.SP
+.BI "PRIVSEP no-fd-from-helper"
+The helper process sent back a positive response, but didn't include the
+requested tunnel descriptor.
+.SP
+.BI "PRIVSEP unknown-response-code"
+The helper process sent back an incomprehensible reply. It's probably
+very confused and may crash.
.SS "SERVER warnings"
These indicate problems concerning the server process as a whole.
.SP
.BI "SERVER select-error " ecode " " message
An error occurred in the server's main event loop. This is bad: if it
happens too many times, the server will abort.
+.SP
+.BI "SERVER waitpid-error " ecode " " message
+The server was informed that one of its child processes had exited, but
+couldn't retrieve the child's status.
.SS "SYMM warnings"
These are concerned with the symmetric encryption and decryption
process.
~mdw / tripe / blobdiff