Write a pidfile on request, and delete it when finished.

[tripe] / doc / tripe-admin.5

.\" -*-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>