.SH "COMMAND REFERENCE"
The commands provided are:
.TP
-.BI "ADD " peer " " address\fR...
+.BI "ADD " peer " \fR[" options "\fR] " 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
option on the command line). The
.I address
is the network address (see above for the format) at which the peer can
-be contacted.
+be contacted. The following options are recognised.
+.RS
+.TP
+.BI "\-keepalive " time
+Send a no-op packet if we've not sent a packet to the peer in the last
+.I time
+interval. This is useful for persuading port-translating firewalls to
+believe that the `connection' is still active. 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.
+.TP
+.BI "\-tunnel " tunnel
+Use the named tunnel driver, rather than the default.
+.RE
.TP
.BI "ADDR " peer
Emits an
Causes the server to disassociate itself from its terminal and become a
background task. This only works once. A warning is issued.
.TP
+.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
+that it can encrypt and decrypt packets correctly. Options and
+responses are the same as for the
+.B PING
+command.
+.TP
.B "HELP"
Causes the server to emit an
.B INFO
.B USER
notification to all interested administration clients.
.TP
+.BI "PING \fR[" options "\fR] " peer
+Send a transport-level ping to the peer. The ping and its response are
+not encrypted or authenticated. This command, possibly in conjunction
+with tracing, is useful for ensuring that UDP packets are actually
+flowing in both directions. See also the
+.B EPING
+command.
+.IP
+An
+.B INFO
+line is printed describing the outcome:
+.RS
+.TP
+.BI "ping-ok " millis
+A response was received
+.I millis
+after the ping was sent.
+.TP
+.BI "ping-timeout"
+No response was received within the time allowed.
+.TP
+.BI "ping-peer-died"
+The peer was killed (probably by another admin connection) before a
+response was received.
+.RE
+.IP
+Options recognized for this command are:
+.RS
+.TP
+.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.)
+.RE
+.TP
.B "PORT"
Emits an
.B INFO
(For any command.) The command couldn't be understood: e.g., the number
of arguments was wrong.
.TP
+.BI "bad-time-spec " word
+The
+.I word
+is not a valid time interval specification. Acceptable time
+specifications are nonnegative integers followed optionally by
+.BR d ,
+.BR h ,
+.BR m ,
+or
+.BR s ,
+for days, hours, minutes, or seconds, respectively.
+.TP
.BI "bad-trace-option " char
(For
.BR TRACE .)
There is already a peer named
.IR peer .
.TP
+.B "ping-send-failed"
+The attempt to send a ping packet failed, probably due to lack of
+encryption keys.
+.TP
.BI "resolve-error " hostname
(For
.BR ADD .)
.SH "NOTIFICATIONS"
The following notifications are sent to clients who request them.
.TP
-.BI "ADD " peer " " address \fR...
+.BI "ADD " peer " " ifname " " address \fR...
A new peer has been added. The peer's name is
-.I peer
+.IR peer ,
+its tunnel is network interface
+.IR ifname ,
and its network address is
.IR address .
.TP
.RB ` \- '
if none is relevant.
.TP
-.BI "PEER \- unexpected-source " address\fR...
-A packet arrived from
-.I address
-(a network address \(en see above), but no peer is known at that
-address. This may indicate a misconfiguration, or simply be a result of
-one end of a connection being set up before the other.
-.TP
.BI "PEER " peer " bad-packet no-type"
An empty packet arrived. This is very strange.
.TP
(in hex) isn't understood. Probably a strange random packet from
somewhere; could be an unlikely bug.
.TP
+.BI "PEER " peer " corrupt-encrypted-ping"
+The peer sent a ping response which matches an outstanding ping, but its
+payload is wrong. There's definitely a bug somewhere.
+.TP
+.BI "PEER " peer " corrupt-transport-ping"
+The peer (apparently) sent a ping response which matches an outstanding
+ping, but its payload is wrong. Either there's a bug, or the bad guys
+are playing tricks on you.
+.TP
.BI "PEER " peer " decrypt-failed"
An encrypted IP packet failed to decrypt. It may have been mangled in
transit, or may be a very old packet from an expired previous session
successive session keys, so this shouldn't occur unless the key exchange
takes ages or fails.
.TP
+.BI "PEER " peer " malformed-encrypted-ping"
+The peer sent a ping response which is hopelessly invalid. There's
+definitely a bug somewhere.
+.TP
+.BI "PEER " peer " malformed-transport-ping"
+The peer (apparently) sent a ping response which is hopelessly invalid.
+Either there's a bug, or the bad guys are playing tricks on you.
+.TP
.BI "PEER " peer " packet-build-failed"
There wasn't enough space in our buffer to put the packet we wanted to
send. Shouldn't happen.
.BI "PEER " peer " socket-write-error \-\- " message
An error occurred attempting to send a network packet. We lost that
one.
+.TP
+.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
+willing to wait, or maybe the peer has gone mad.
+.TP
+.BI "PEER \- unexpected-source " address\fR...
+A packet arrived from
+.I address
+(a network address \(en see above), but no peer is known at that
+address. This may indicate a misconfiguration, or simply be a result of
+one end of a connection being set up before the other.
+.TP
+.BI "PEER " peer " unexpected-transport-ping 0x" id
+The peer (apparently) sent a transport ping response whose id doesn't
+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 "SERVER warnings"
These indicate problems concerning the server process as a whole.
.TP
.BI /dev/tun nn
files, it will work.
.TP
-.BI "TUN \- slip no-slip-interfaces"
-The driver ran out of SLIP interfaces. You probably need to preallocate
-some more and restart.
-.TP
.BI "TUN - open-error " device " \-\- " message
An attempt to open the tunnel device file
.I device
failed.
.TP
-.BI "TUN " ifname " read-error \-\- " message
-Reading from the tunnel device failed.
-.TP
.BI "TUN \- linux config-error \-\- " message
Configuring the Linux TUN/TAP interface failed.
.TP
-.BI "TUN \- unet config-error \-\- " message
-Configuring the Linux Unet interface failed. Unet is obsolete and
-shouldn't be used any more.
-.TP
-.BI "TUN \- unet getinfo-error \-\- " message
-Reading information about the Unet interface failed. Unet is obsolete
-and shouldn't be used any more.
+.BI "TUN " ifname " read-error \-\- " message
+Reading from the tunnel device failed.
.TP
-.BI "TUN \- unet ifname-too-long \-\- " message
-The Unet interface's name overflowed, so we couldn't read it properly.
-Unet is obsolete and shouldn't be used any more.
+.BI "TUN " ifname " slip bad-escape"
+The SLIP driver encountered a escaped byte it wasn't expecting to see.
+The erroneous packet will be ignored.
.TP
.BI "TUN " ifname " slip eof"
The SLIP driver encountered end-of-file on its input descriptor.
means that someone's been sending it junk. The erroneous packet is
discarded, and we hope that we've rediscovered synchronization.
.TP
-.BI "TUN " ifname " slip bad-escape"
-The SLIP driver encountered a escaped byte it wasn't expecting to see.
-The erroneous packet will be ignored.
+.BI "TUN \- slip fork-error \-\- " message
+The SLIP driver encountered an error forking a child process while
+allocating a new dynamic interface.
+.TP
+.BI "TUN \- slip no-slip-interfaces"
+The driver ran out of static SLIP interfaces. Either preallocate more,
+or use dynamic SLIP interface allocation.
.TP
.BI "TUN " ifname " slip overflow"
The SLIP driver gave up reading a packet because it got too large.
+.TP
+.BI "TUN \- slip pipe-error \-\- " message
+The SLIP driver encountered an error creating pipes while allocating a
+new dynamic interface.
+.TP
+.BI "TUN \- slip read-ifname-failed \-\- " message
+The SLIP driver encountered an error reading the name of a dynamically
+allocated interface. Maybe the allocation script is broken.
+.TP
+.BI "TUN \- unet config-error \-\- " message
+Configuring the Linux Unet interface failed. Unet is obsolete and
+shouldn't be used any more.
+.TP
+.BI "TUN \- unet getinfo-error \-\- " message
+Reading information about the Unet interface failed. Unet is obsolete
+and shouldn't be used any more.
+.TP
+.BI "TUN \- unet ifname-too-long \-\- " message
+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
.PP
.IR "The Trivial IP Encryption Protocol" .
.SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blobdiff