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