X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/72917fe7c663aced54f7e1185b7b72ba59aea73c..6b6ad6702f305891ced3b9a7cf3061c75eabda86:/doc/tripe-admin.5.in

diff --git a/doc/tripe-admin.5.in b/doc/tripe-admin.5.in
deleted file mode 100644
index 94c7c3b8..00000000
--- a/doc/tripe-admin.5.in
+++ /dev/null
@@ -1,1343 +0,0 @@
-.\" -*-nroff-*-
-.\"
-.ie t \{\
-.  if \n(.g \{\
-.    fam P
-.  \}
-.\}
-.
-.de SP
-.TP
-..
-.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
-.SH NAME
-tripe-admin \- administrator commands for TrIPE
-.SH DESCRIPTION
-This manual page describes the administration interface provided by the
-.BR tripe (8)
-daemon.
-.PP
-The
-.BR tripectl (8)
-program can be used either interactively or in scripts to communicate
-with the server using this interface.  Alternatively, simple custom
-clients can be written in scripting languages such as Perl, Python or
-Tcl, or more advanced clients such as GUI monitors can be written in C
-with little difficulty.
-.PP
-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.
-.SS "General structure"
-Each command or response line consists of a sequence of
-whitespace-separated words.  The number and nature of whitespace
-characters separating two words in a client command is not significant;
-the server always uses a single space character.  The first word in a
-line is a
-.I keyword
-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 "Simple commands"
-For simple client command, the server responds with zero or more
-.B INFO
-lines, followed by either an
-.B OK
-line or a
-.B FAIL
-line.  Each
-.B INFO
-provides information requested in the command.  An
-.B OK
-response contains no further data.  A
-.B FAIL
-code is followed by a machine-readable explanation of why the command
-failed.
-.PP
-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.  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
-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.
-.PP
-The
-.B TRACE
-message contains a human-readable tracing message containing diagnostic
-information.  Trace messages are controlled using the
-.B \-T
-command-line option to the server, or 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.
-.PP
-Finally, the
-.B NOTE
-message is a machine-readable notification about some routine but
-interesting event such as creation or destruction of peers.
-.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
-or
-.B BGINFO
-response: it will always detach and then issue any
-.B BGINFO
-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
-the meanings of the subsequent words depend on the address family.
-Address family tokens are not case-sensitive on input; on output, they
-are always in upper-case.
-.PP
-At present, only one address family is understood.
-.TP
-.BI "INET " address " " port
-An Internet socket, naming an IPv4 address and UDP port.  On output, the
-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, 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.  Addresses output by the server always have an address family
-token.
-.SS "Key-value output"
-Some commands (e.g.,
-.B STATS
-and
-.BR SERVINFO )
-produce output in the form of
-.IB key = value
-pairs, one per word.  Neither the
-.I key
-nor the
-.I value
-contain spaces.
-.SS "Trace lists"
-Commands which enable or disable kinds of output (e.g.,
-.B TRACE
-and
-.BR WATCH )
-work in similar ways.  They take a single optional argument, which
-consists of a string of letters selecting message types, optionally
-interspersed with
-.RB ` + '
-to enable, or
-.RB ` \- '
-to disable, the subsequently listed types.
-.PP
-If the argument is omitted, the available message types are displayed,
-one to an
-.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 ` + ' 
-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.
-.PP
-Lowercase key letters control individual message types.  Uppercase key
-letters control collections of message types.
-.SH "COMMAND REFERENCE"
-.\"* 10 Commands
-The commands provided are:
-.SP
-.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
-.B keyring.pub
-(or whatever alternative file was specified in the
-.B \-K
-option on the command line).  The
-.I address
-is the network address (see above for the format) at which the peer can
-be contacted.  The following options are recognised.
-.RS
-.\"+opts
-.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
-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.
-.\"-opts
-.RE
-.SP
-.BI "ADDR " peer
-Emits an
-.B INFO
-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
-and not previously either passed to
-.B CHECKCHAL
-or in a greeting message.
-.SP
-.B "DAEMON"
-Causes the server to disassociate itself from its terminal and become a
-background task.  This only works once.  A warning is issued.
-.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
-that it can encrypt and decrypt packets correctly.  Options and
-responses are the same as for the
-.B PING
-command.
-.SP
-.BI "FORCEKX " peer
-Requests the server to begin a new key exchange with
-.I peer
-immediately.
-.SP
-.B "GETCHAL"
-Requests a challenge.  The challenge is returned in an
-.B INFO
-line, as a base64-encoded string.  See
-.BR CHECKCHAL .
-.SP
-.BI "GREET " peer " " challenge
-Sends a greeting packet containing the
-.I challenge
-(base-64 encoded) to the named
-.IR peer .
-The expectation is that this will cause the peer to recognize us and
-begin a key-exchange.
-.SP
-.B "HELP"
-Causes the server to emit an
-.B INFO
-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 
-.BI "IFNAME " peer
-Emits an
-.B INFO
-line containing the name of the network interface used to collect IP
-packets which are to be encrypted and sent to
-.IR peer .
-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 .
-All keys are destroyed, and no more packets are sent.  No notification
-is sent to the peer: if it's important that the peer be notified, you
-must think of a way to do that yourself.
-.SP
-.B "LIST"
-For each currently-known peer, an
-.B INFO
-line is written containing the peer's name, as given to
-.BR ADD .
-.SP
-.BI "NOTIFY " tokens\fR...
-Issues a 
-.B USER
-notification to all interested administration clients.
-.SP
-.BI "PEERINFO " peer
-Returns information about a peer, in key-value form.  The following keys
-are returned.
-.RS
-.TP
-.B tunnel
-The tunnel driver used for this peer.
-.TP
-.B keepalive
-The keepalive interval, in seconds, or zero if no keepalives are to be
-sent.
-.RE
-.SP
-.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
-.\"+opts
-.TP
-.BI "\-background " tag
-Run the command in the background, using the given
-.IR tag .
-.TP
-.BI "\-timeout " time
-Wait for
-.I time
-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
-.B "PORT"
-Emits an
-.B INFO
-line containing just the number of the UDP port used by the
-.B tripe
-server.  If you've allowed your server to allocate a port dynamically,
-this is how to find out which one it chose.
-.SP
-.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.
-.SP
-.B "QUIT"
-Instructs the server to exit immediately.  A warning is sent.
-.SP
-.B "SERVINFO"
-Returns information about the server, in the form of key-value pairs.
-The following keys are used.
-.RS
-.TP
-.B implementation
-A keyword naming the implementation of the
-.BR tripe (8)
-server.  The current implementation is called
-.BR edgeware-tripe .
-.TP
-.B version
-The server's version number, as reported by
-.BR VERSION .
-.TP
-.B daemon
-Either
-.B t
-or
-.BR nil ,
-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
-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" 
-above.  Message types provided are:
-.RS
-.PP
-Currently, the following tracing options are supported:
-.TP
-.B t
-Tunnel events: reception of packets to be encrypted, and injection of
-successfully-decrypted packets.
-.TP
-.B r
-Peer management events: creation and destruction of peer attachments,
-and arrival of messages.
-.TP
-.B a
-Administration interface: acceptance of new connections, and handling of
-the backgroud name-resolution required by the
-.B ADD
-command.
-.TP
-.B s
-Handling of symmetric keysets: creation and expiry of keysets, and
-encryption and decryption of messages.
-.TP
-.B x
-Key exchange: reception, parsing and emission of key exchange messages.
-.TP
-.B m
-Key management: loading keys and checking for file modifications.
-.TP
-.B l
-Display information about challenge issuing and verification.
-.TP
-.B p
-Display contents of packets sent and received by the tunnel and/or peer
-modules.
-.TP
-.B c
-Display inputs, outputs and intermediate results of cryptographic
-operations.  This includes plaintext and key material.  Use with
-caution.
-.TP
-.B A
-All of the above.
-.PP
-Note that the
-.B p
-(packet contents)
-and
-.B c
-(crypto details)
-outputs provide extra detail for other outputs.  Specifying
-.B p
-without
-.BR r
-or
-.B t
-isn't useful; neither is specifying
-.B c
-without one of
-.BR s ,
-.BR l ,
-.B x
-or
-.BR m .
-.RE
-.SP
-.B "TUNNELS"
-For each available tunnel driver, an
-.B INFO
-line is printed giving its name.
-.SP
-.B "VERSION"
-Causes the server to emit an
-.B INFO
-line stating its software version, as two words: the server name, and
-its version string.  The server name
-.B tripe
-is reserved to the Straylight/Edgeware implementation.
-.SP
-.BR "WATCH " [\fIoptions\fP]
-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 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:
-.TP
-.B t
-.B TRACE
-messages.
-.TP
-.B n
-.B NOTE
-messages.
-.TP
-.B w
-.B WARN
-messages.
-.TP
-.B A
-All of the above.
-.RE
-.SP
-.BI "WARN " tokens\fR...
-Issues a 
-.B USER
-warning to all interested administration clients.
-.SH "ERROR MESSAGES"
-.\"* 20 Error messages (FAIL codes)
-The following
-.B FAIL
-(or
-.BR BGFAIL )
-messages are sent to clients as a result of errors during command
-processing.
-.SP
-.BI "already-daemon"
-(For
-.BR DAEMON .)
-The
-.B tripe
-server is already running as a daemon.
-.SP
-.BI "bad-addr-syntax " message
-(For commands accepting socket addresses.)  The address couldn't be
-understood.
-.SP
-.BI "bad-syntax " cmd " " message
-(For any command.)  The command couldn't be understood: e.g., the number
-of arguments was wrong.
-.SP
-.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.
-.SP
-.BI "bad-trace-option " char
-(For
-.BR TRACE .)
-An unknown trace option was requested.
-.SP
-.BI "bad-watch-option " char
-(For
-.BR WATCH .)
-An unknown watch option was requested.
-.SP
-.BI "daemon-error " ecode " " message
-(For
-.BR DAEMON .)
-An error occurred during the attempt to become a daemon, as reported by
-.IR message .
-.SP
-.BI "invalid-port " number
-(For
-.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 .)
-Adding
-.I peer
-failed for some reason.  A warning should have been emitted explaining
-why.
-.SP
-.BI "peer-exists " peer
-(For
-.BR ADD .)
-There is already a peer named
-.IR peer .
-.SP
-.B "ping-send-failed"
-The attempt to send a ping packet failed, probably due to lack of
-encryption keys.
-.SP
-.BI "resolve-error " hostname
-(For
-.BR ADD .)
-The DNS name
-.I hostname
-could not be resolved.
-.SP
-.BI "resolver-timeout " hostname
-(For
-.BR ADD .)
-The DNS name
-.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
-was not recognised.
-.SP
-.BI "unknown-peer " name
-(For
-.BR ADDR ,
-.BR IFNAME ,
-.BR KILL ,
-.BR SETIFNAME ,
-and
-.BR STATS .)
-There is no peer called
-.IR name .
-.SP
-.BI "unknown-port " port
-(For
-.BR ADD .)
-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.
-.SP
-.BI "ADD " peer " " ifname " " address \fR...
-A new peer has been added.  The peer's name is
-.IR peer ,
-its tunnel is network interface
-.IR ifname ,
-and its network address is
-.IR address .
-.SP
-.BI "DAEMON"
-The server has forked off into the sunset and become a daemon.
-.SP
-.BI "GREET " challenge " " address \fR...
-A valid greeting was received, with the given challenge (exactly as it
-was returned by
-.B GETCHAL
-earlier).
-.SP
-.BI "KILL " peer
-The peer
-.I peer
-has been killed.
-.SP
-.BI "KXDONE " peer
-Key exchange with
-.I peer
-finished successfully.
-.SP
-.BI "KXSTART " peer
-Key exchange with
-.I peer
-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
-command.
-.SH "WARNINGS"
-.\"* 40 Warning broadcasts (WARN codes)
-.\"+sep
-There are many possible warnings.  They are categorized according to
-their first tokens.
-.PP
-Many of these warnings report system errors.  These are reported as a
-pair of tokens, described below as
-.I ecode
-and
-.IR message .
-The
-.I ecode
-is a string of the form
-.BI E number
-giving the
-.BR errno (3)
-value of the error; the
-.I message
-is the `human-readable' form of the message, as reported by
-.BR strerror (3).
-.SS "ABORT warnings"
-These all indicate that the
-.B tripe
-server has become unable to continue.  If enabled, the server will dump
-core in its configuration directory.
-.SP
-.BI "ABORT repeated-select-errors"
-The main event loop is repeatedly failing.  If the server doesn't quit,
-it will probably waste all available CPU doing nothing.
-.SS "ADMIN warnings"
-These indicate a problem with the administration socket interface.
-.SP
-.BI "ADMIN accept-error " ecode " " message
-There was an error while attempting to accept a connection from a new
-client.
-.SP
-.BI "ADMIN client-write-error " ecode " " message
-There was an error sending data to a client.  The connection to the
-client has been closed.
-.SS "CHAL warnings"
-These indicate errors in challenges, either in the
-.B CHECKCHAL
-command or in greeting packets.
-.SP
-.B "CHAL impossible-challenge"
-The server hasn't issued any challenges yet.  Quite how anyone else
-thought he could make one up is hard to imagine.
-.SP
-.B "CHAL incorrect-tag"
-Challenge received contained the wrong authentication data.  It might be
-very stale, or a forgery.
-.SP
-.B "CHAL invalid-challenge"
-Challenge received was the wrong length.  We might have changed MAC
-algorithms since the challenge was issued, or it might just be rubbish.
-.SP
-.B "CHAL replay duplicated-sequence"
-Challenge received was a definite replay of an old challenge.  Someone's
-up to something!
-.SP
-.B "CHAL replay old-sequence"
-Challenge received was old, but maybe not actually a replay.  Try again.
-.SS "KEYMGMT warnings"
-These indicate a problem with the keyring files, or the keys stored in
-them.
-.SP
-.BI "KEYMGMT bad-private-key " message
-The private key could not be read, or failed a consistency check.  If
-there was a problem with the file, usually there will have been
-.B key-file-error
-warnings before this.
-.SP
-.BI "KEYMGMT bad-public-keyring " message
-The public keyring couldn't be read.  Usually, there will have been 
-.B key-file-error
-warnings before this.
-.SP
-.BI "KEYMGMT key-file-error " file ":" line " " message
-Reports a specific error with the named keyring file.  This probably
-indicates a bug in
-.BR key (1).
-.SP
-.BI "KEYMGMT public-key " tag " " tokens\fR...
-These messages all indicate a problem with the public key named
-.IR tag .
-.SP
-.BI "KEYMGMT public-key " tag " algorithm-mismatch"
-The algorithms specified on the public key don't match the ones for our
-private key.  All the peers in a network have to use the same
-algorithms.
-.SP
-.BI "KEYMGMT public-key " tag " bad " message
-The public key couldn't be read, or is invalid.
-.SP
-.BI "KEYMGMT public-key " tag " bad-public-group-element"
-The public key is invalid.  This may indicate a malicious attempt to
-introduce a bogus key.
-.SP
-.BI "KEYMGMT public-key " tag " bad-algorithm-selection"
-The algorithms listed on the public key couldn't be understood.  The
-algorithm selection attributes are probably malformed and need fixing.
-.SP
-.BI "KEYMGMT public-key " tag " incorrect-group"
-The public key doesn't use the same group as our private key.  All the
-peers in a network have to use the same group.
-.SP
-.BI "KEYMGMT public-key " tag " not-found"
-The public key for peer
-.I tag
-wasn't in the public keyring.
-.SP
-.BI "KEYMGMT public-key " tag " unknown-type"
-The type of the public key isn't understood.  Maybe you need to upgrade
-your copy of
-.BR tripe .
-(Even if you do, you'll have to regenerate your keys.)
-.SS "KX warnings"
-These indicate problems during key-exchange.  Many indicate either a bug
-in the server (either yours or the remote one), or some kind of attack
-in progress.  All name a
-.I peer
-as the second token: this is the peer the packet is apparently from,
-though it may have been sent by an attacker instead.
-.PP
-In the descriptions below,
-.I msgtoken
-is one of the tokens
-.BR pre-challenge ,
-.BR cookie ,
-.BR challenge ,
-.BR reply ,
-.BR switch-rq ,
-or
-.BR switch-ok .
-.SP
-.BI "KX " peer " bad-expected-reply-log"
-The challenges
-.B tripe
-uses in its protocol contain a check value which proves that the
-challenge is honest.  This message indicates that the check value
-supplied is wrong: someone is attempting to use bogus challenges to
-persuade your
-.B tripe
-server to leak private key information.  No chance!
-.SP
-.BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok"
-A symmetrically-encrypted portion of a key-exchange message failed to
-decrypt.
-.SP
-.BI "KX " peer " invalid " msgtoken
-A key-exchange message was malformed.  This almost certainly indicates a
-bug somewhere.
-.SP
-.BI "KX " peer " incorrect cookie\fR|\fBswitch-rq\fR|\fBswitch-ok"
-A message didn't contain the right magic data.  This may be a replay of
-some old exchange, or random packets being sent in an attempt to waste
-CPU.
-.SP
-.BI "KX " peer " public-key-expired"
-The peer's public key has expired.  It's maintainer should have given
-you a replacement before now.
-.SP
-.BI "KX " peer " sending-cookie"
-We've received too many bogus pre-challenge messages.  Someone is trying
-to flood us with key-exchange messages and make us waste CPU on doing
-hard asymmetric crypto sums.
-.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 
-.BR pre-challenge ,
-it may simply mean that the peer has recently restarted.
-.SP
-.BI "KX " peer " unknown-challenge"
-The peer is asking for an answer to a challenge which we don't know
-about.  This may mean that we've been inundated with challenges from
-some malicious source
-.I who can read our messages
-and discarded the valid one.
-.SP
-.BI "KX " peer " unknown-message 0x" nn
-An unknown key-exchange message arrived.
-.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 
-.RB ` \- '
-if none is relevant.
-.SP
-.BI "PEER " peer " bad-packet no-type"
-An empty packet arrived.  This is very strange.
-.SP
-.BI "PEER " peer " bad-packet unknown-category 0x" nn
-The message category
-.I nn
-(in hex) isn't understood.  Probably a strange random packet from
-somewhere; could be an unlikely bug.
-.SP
-.BI "PEER " peer " bad-packet unknown-type 0x" nn
-The message type
-.I nn
-(in hex) isn't understood.  Probably a strange random packet from
-somewhere; could be an unlikely bug.
-.SP
-.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.
-.SP
-.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.
-.SP
-.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
-key.  There is usually a considerable overlap in the validity periods of
-successive session keys, so this shouldn't occur unless the key exchange
-takes ages or fails.
-.SP
-.BI "PEER " peer " malformed-encrypted-ping"
-The peer sent a ping response which is hopelessly invalid.  There's
-definitely a bug somewhere.
-.SP
-.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.
-.SP
-.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.
-.SP
-.BI "PEER \- socket-read-error " ecode " " message
-An error occurred trying to read an incoming packet.
-.SP
-.BI "PEER " peer " 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
-willing to wait, or maybe the peer has gone mad.
-.SP
-.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.
-.SP
-.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.
-.SP
-.BI "SERVER ignore signal " name
-A signal arrived, but the server ignored it.  Currently this happens for
-.B SIGHUP
-because that's a popular way of telling daemons to re-read their
-configuration files.  Since
-.B tripe
-re-reads its keyrings automatically and has no other configuration
-files, it's not relevant, but it seemed better to ignore the signal than
-let the server die.
-.SP
-.BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR]
-A signal arrived and
-.B tripe
-is going to quit.
-.SP
-.BI "SERVER quit admin-request"
-A client of the administration interface issued a
-.B QUIT
-command.
-.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.
-.SS "SYMM warnings"
-These are concerned with the symmetric encryption and decryption
-process.
-.SP
-.BI "SYMM replay old-sequence"
-A packet was received with an old sequence number.  It may just have
-been delayed or duplicated, or it may have been an attempt at a replay
-attack.
-.SP
-.BI "SYMM replay duplicated-sequence"
-A packet was received with a sequence number we've definitely seen
-before.  It may be an accidental duplication because the 'net is like
-that, or a deliberate attempt at a replay.
-.SS "TUN warnings"
-These concern the workings of the system-specific tunnel driver.  The
-second word is the name of the tunnel interface in question, or
-.RB ` \- '
-if none.
-.SP
-.BI "TUN \- bsd no-tunnel-devices"
-The driver couldn't find an available tunnel device.  Maybe if you
-create some more 
-.BI /dev/tun nn
-files, it will work.
-.SP
-.BI "TUN \- " tun-name " open-error " device " " ecode " " message
-An attempt to open the tunnel device file
-.I device
-failed.
-.SP
-.BI "TUN \- linux config-error " ecode " " message
-Configuring the Linux TUN/TAP interface failed.
-.SP
-.BI "TUN " ifname " " tun-name " read-error " ecode " " message
-Reading from the tunnel device failed.
-.SP
-.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.
-.SP
-.BI "TUN " ifname " slip eof"
-The SLIP driver encountered end-of-file on its input descriptor.
-Pending data is discarded, and no attempt is made to read any more data
-from that interface ever.
-.SP
-.BI "TUN " ifname " slip escape-end"
-The SLIP driver encountered an escaped `end' marker.  This probably
-means that someone's been sending it junk.  The erroneous packet is
-discarded, and we hope that we've rediscovered synchronization.
-.SP
-.BI "TUN \- slip fork-error " ecode " " message
-The SLIP driver encountered an error forking a child process while
-allocating a new dynamic interface.
-.SP
-.BI "TUN \- slip no-slip-interfaces"
-The driver ran out of static SLIP interfaces.  Either preallocate more,
-or use dynamic SLIP interface allocation.
-.SP
-.BI "TUN " ifname " slip overflow"
-The SLIP driver gave up reading a packet because it got too large.
-.SP
-.BI "TUN \- slip pipe-error " ecode " " message
-The SLIP driver encountered an error creating pipes while allocating a
-new dynamic interface.
-.SP
-.BI "TUN \- slip read-ifname-failed " ecode " " message
-The SLIP driver encountered an error reading the name of a dynamically
-allocated interface.  Maybe the allocation script is broken.
-.SP
-.BI "TUN \- unet config-error " ecode " " message
-Configuring the Linux Unet interface failed.  Unet is obsolete and
-shouldn't be used any more.
-.SP
-.BI "TUN \- unet getinfo-error " ecode " " message
-Reading information about the Unet interface failed.  Unet is obsolete
-and shouldn't be used any more.
-.SS "USER warnings"
-These are issued by administration clients using the
-.B WARN
-command.
-.SP
-.BI "USER " tokens\fR...
-An administration client issued a warning.
-.\"-sep
-.SH "SUMMARY"
-.SS "Command responses"
-.nf
-.BI "BGDETACH " tag
-.BI "BGFAIL " tag " " tokens \fR...
-.BI "BGINFO " tag " " tokens \fR...
-.BI "BGOK " tag
-.BI "FAIL " tokens \fR...
-.BI "INFO " tokens \fR...
-.B OK
-.fi
-.\"= summary
-.SH "SEE ALSO"
-.BR tripectl (1),
-.BR tripe (8).
-.PP
-.IR "The Trivial IP Encryption Protocol" .
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>