chiark / gitweb /
Mention that I wrote mallory's help message in the manpage.
[tripe] / doc / tripe-admin.5
CommitLineData
d6623498 1.\" -*-nroff-*-
2.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
3.SH NAME
4tripe-admin \- administrator commands for TrIPE
5.SH DESCRIPTION
6This manual page describes the administration interface provided by the
7.BR tripe (8)
8daemon.
9.PP
10The
11.BR tripectl (8)
12program can be used either interactively or in scripts to communicate
13with the server using this interface. Alternatively, simple custom
14clients can be written in scripting languages such as Perl, Python or
15Tcl, or more advanced clients such as GUI monitors can be written in C
16with little difficulty.
17.PP
18By default, the server listens for admin connections on the Unix-domain
19socket
20.BR /var/lib/tripe/tripesock .
21Administration commands use a simple textual protocol. Each client
22command or server response consists of a line of ASCII text terminated
8bc63560 23by a single linefeed character. No command may be longer than 255
24characters.
d6623498 25.SS "General structure"
26Each command or response line consists of a sequence of
27whitespace-separated words. The number and nature of whitespace
28characters separating two words in a client command is not significant;
29the server always uses a single space character. The first word in a
30line is a
31.I keyword
32identifying the type of command or response contained. Keywords in
33client commands are not case-sensitive; the server always uses uppercase
34for its keywords.
35.SS "Server responses"
36For client command, the server responds with zero or more
37.B INFO
38lines, followed by either an
39.B OK
40line or a
41.B FAIL
42line. Each
43.B INFO
44provides information requested in the command. An
45.B OK
46response contains no further data. A
47.B FAIL
48code is followed by a human-readable explanation of why the command
49failed.
50.PP
51In addition, there are two types of asynchronous `responses', which
52aren't associated with any particular command. The
53.B WARN
54response contains a human-readable message warning of an error
55encountered while processing a command, unexpected or unusual behaviour
56by a peer, or a possible attack by an adversary. Under normal
57conditions, the server shouldn't emit any warnings. The
58.B TRACE
59response contains a human-readable tracing message containing diagnostic
60information. Trace messages are controlled using the
61.B \-T
62command-line option to the server, or the
63.B TRACE
64administration command (see below). Support for tracing can be disabled
65when the package is being configured, and may not be available in your
66version.
67.SS "Command reference"
68The commands provided are:
69.TP
70.B "HELP"
71Causes the server to emit an
72.B INFO
73line for each command it supports. Each line lists the command name,
74followed by the names of the arguments. This may be helpful as a memory
75aid for interactive use, or for program clients probing for features.
76.TP
77.BR "TRACE " [\fIoptions\fP]
78A trace argument consists of a string of letters (listed below)
79selecting trace outputs, optionally interspersed with
80.RB ` + '
81to enable, or
82.RB ` \- '
83to disable, the subsequently listed outputs; the initial behaviour is to
84enable listed outputs. For example, the string
85.B ra\-st+x
86enables tracing of peer management, admin-connection handling and
87key-exchange processing, and disables tracing of symmetric keyset
88management and the system-specific tunnel driver. If no argument is
89given, a table is returned showing the available tracing option letters
90and their meanings. Programs should not attempt to parse this table:
91its format is not guaranteed to remain the same.
92.RS
2d752320 93.PP
d6623498 94Currently, the following tracing options are supported:
95.TP
96.B t
97Tunnel events: reception of packets to be encrypted, and injection of
98successfully-decrypted packets.
99.TP
100.B r
101Peer management events: creation and destruction of peer attachments,
102and arrival of messages.
103.TP
104.B a
105Administration interface: acceptance of new connections, and handling of
106the backgroud name-resolution required by the
107.B ADD
108command.
109.TP
110.B p
111Display contents of packets sent and received by the tunnel and/or peer
112modules.
113.TP
114.B c
115Display inputs, outputs and intermediate results of cryptographic
116operations. This includes plaintext and key material. Use with
117caution.
118.TP
119.B s
120Handling of symmetric keysets: creation and expiry of keysets, and
121encryption and decryption of messages.
122.TP
123.B x
124Key exchange: reception, parsing and emission of key exchange messages.
125.TP
126.B m
127Key management: loading keys and checking for file modifications.
128.PP
129Note that the
130.B p
131(packet contents)
132and
133.B c
134(crypto details)
135outputs provide extra detail for other outputs. Specifying
136.B p
137without
138.B r
139or
140.B t
141isn't useful; neither is specifying
142.B c
143without one of
144.BR s ,
145.B x
146or
147.BR m .
148.RE
149.TP
150.B "PORT"
151Emits an
152.B INFO
153line containing just the number of the UDP port used by the
154.B tripe
155server. If you've allowed your server to allocate a port dynamically,
156this is how to find out which one it chose.
157.TP
158.B "DAEMON"
159Causes the server to disassociate itself from its terminal and become a
160background task. This only works once. A warning is issued.
161.TP
162.B "LIST"
163For each currently-known peer, an
164.B INFO
165line is written containing the peer's name, as given to
166.BR ADD .
167.TP
168.BI "IFNAME " peer
169Emits an
170.B INFO
171line containing the name of the network interface used to collect IP
172packets which are to be encrypted and sent to
173.IR peer .
174Used by configuration scripts so that they can set up routing tables
175appropriately after adding new peers.
176.TP
177.BI "ADDR " peer
178Emits an
179.B INFO
180line reporting the IP address and port number stored for
181.IR peer .
182.TP
183.BI "STATS " peer
184Emits a number of
185.B INFO
186lines, each containing one or more statistics in the form
187.IB name = value \fR.
188The statistics-gathering is experimental and subject to change.
189.TP
190.BI "KILL " peer
191Causes the server to forget all about
192.IR peer .
193All keys are destroyed, and no more packets are sent. No notification
194is sent to the peer: if it's important that the peer be notified, you
195must think of a way to do that yourself.
196.TP
197.BI "ADD " "peer addr port"
198Adds a new peer. The peer is given the name
199.IR peer ;
200the peer's public key is assumed to be in the file
201.B keyring.pub
202(or whatever alternative file was specified in the
203.B \-K
204option on the command line). The peer's
205.B tripe
206implementation may be contacted at the given UDP port and IP address.
207.TP
208.B "QUIT"
209Instructs the server to exit immediately. A warning is sent.
210.SH "SEE ALSO"
211.BR tripectl (1),
212.BR tripe (8).
213.PP
214.IR "The Trivial IP Encryption Protocol" ,
215.SH "AUTHOR"
216Mark Wooding, <mdw@nsict.org>