--- /dev/null
+.\" -*-nroff-*-
+.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
+By default, the server listens for admin connections on the Unix-domain
+socket
+.BR /var/lib/tripe/tripesock .
+Administration commands use a simple textual protocol. Each client
+command or server response consists of a line of ASCII text terminated
+by a single linefeed character.
+.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 "Server responses"
+For 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 human-readable explanation of why the command
+failed.
+.PP
+In addition, there are two types of asynchronous `responses', which
+aren't associated with any particular command. The
+.B WARN
+response contains a human-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
+.B TRACE
+response 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.
+.SS "Command reference"
+The commands provided are:
+.TP
+.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.
+.TP
+.BR "TRACE " [\fIoptions\fP]
+A trace argument consists of a string of letters (listed below)
+selecting trace outputs, optionally interspersed with
+.RB ` + '
+to enable, or
+.RB ` \- '
+to disable, the subsequently listed outputs; the initial behaviour is to
+enable listed outputs. For example, the string
+.B ra\-st+x
+enables tracing of peer management, admin-connection handling and
+key-exchange processing, and disables tracing of symmetric keyset
+management and the system-specific tunnel driver. If no argument is
+given, a table is returned showing the available tracing option letters
+and their meanings. Programs should not attempt to parse this table:
+its format is not guaranteed to remain the same.
+.RS
+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 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 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.
+.PP
+Note that the
+.B p
+(packet contents)
+and
+.B c
+(crypto details)
+outputs provide extra detail for other outputs. Specifying
+.B p
+without
+.B r
+or
+.B t
+isn't useful; neither is specifying
+.B c
+without one of
+.BR s ,
+.B x
+or
+.BR m .
+.RE
+.TP
+.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.
+.TP
+.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
+.B "LIST"
+For each currently-known peer, an
+.B INFO
+line is written containing the peer's name, as given to
+.BR ADD .
+.TP
+.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.
+.TP
+.BI "ADDR " peer
+Emits an
+.B INFO
+line reporting the IP address and port number stored for
+.IR peer .
+.TP
+.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.
+.TP
+.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.
+.TP
+.BI "ADD " "peer addr port"
+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 peer's
+.B tripe
+implementation may be contacted at the given UDP port and IP address.
+.TP
+.B "QUIT"
+Instructs the server to exit immediately. A warning is sent.
+.SH "SEE ALSO"
+.BR tripectl (1),
+.BR tripe (8).
+.PP
+.IR "The Trivial IP Encryption Protocol" ,
+.SH "AUTHOR"
+Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blobdiff