From 13a55605839046f6f42910de713f4a9b6c44dfd4 Mon Sep 17 00:00:00 2001 Message-Id: <13a55605839046f6f42910de713f4a9b6c44dfd4.1715161854.git.mdw@distorted.org.uk> From: Mark Wooding Date: Wed, 22 Feb 2006 02:54:00 +0000 Subject: [PATCH] tripe-admin manpage: Generate a command and message summary. Organization: Straylight/Edgeware From: Mark Wooding There's such a big pile of information it seems nice to provide a quick index at the end. An unpleasant awk script seems to do the job nicely. --- doc/Makefile.am | 10 +- doc/make-summary | 29 +++ doc/{tripe-admin.5 => tripe-admin.5.in} | 247 +++++++++++++----------- 3 files changed, 173 insertions(+), 113 deletions(-) create mode 100755 doc/make-summary rename doc/{tripe-admin.5 => tripe-admin.5.in} (97%) diff --git a/doc/Makefile.am b/doc/Makefile.am index ee4efdde..023d80f3 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,11 +27,17 @@ AUTOMAKE_OPTIONS = foreign +CONST_MANS = tripe.8 tripectl.1 pkstream.1 tripe-mitm.8 man_MANS = \ - tripe.8 tripectl.1 tripe-admin.5 pkstream.1 tripe-mitm.8 \ + $(CONST_MANS) tripe-admin.5 \ @pymans@ @pygtkmans@ + PYTHONMANS = tripe-keys.8 tripe-keys.conf.5 PYGTKMANS = tripemon.1 -EXTRA_DIST = $(man_MANS) $(PYTHONMANS) $(PYGTKMANS) +EXTRA_DIST = $(CONST_MANS) tripe-admin.5.in $(PYTHONMANS) $(PYGTKMANS) + +tripe-admin.5: tripe-admin.5.in make-summary + awk -f $(srcdir)/make-summary <$(srcdir)/tripe-admin.5.in >$@.new + mv $@.new $@ ##----- That's all, folks --------------------------------------------------- diff --git a/doc/make-summary b/doc/make-summary new file mode 100755 index 00000000..2aff34c6 --- /dev/null +++ b/doc/make-summary @@ -0,0 +1,29 @@ +#! /usr/bin/awk -f + +BEGIN { n = 0; opts = 0; sep = 0; } + +/^\.\\\"\* ([0-9]+) (.*)$/ { + n = $2; + name = $3; + for (i = 4; i <= NF; i++) name = name " " $i; + head[n] = name; +} +/^\.\\\"\+opts$/ { opts = 1; lines[n] = lines[n] "\\h'2n'Options:\n.RS\n"; } +/^\.\\\"\-opts$/ { opts = 0; lines[n] = lines[n] ".RE\n"; } +/^\.\\\"\+sep$/ { sep = 1; } +/^\.\\\"\-sep$/ { sep = 0; } +/^\.\\\"\-opts$/ { opts = 0; lines[n] = lines[n] ".RE\n"; } +/^\.SP/ { print; getline; lines[n] = lines[n] $0 "\n"; } +/^\.TP/ { if (opts) { print; getline; lines[n] = lines[n] $0 "\n"; } } +/^\.SS/ { if (sep) lines[n] = lines[n] ".PP\n"; } + +{ print; } + +/^\.\\\"= summary/ { + for (i = 0; i < 100; i++) { + if (!(i in head)) continue; + print ".SS \"" head[i] "\""; + print ".nf"; + print lines[i] ".fi"; + } +} diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5.in similarity index 97% rename from doc/tripe-admin.5 rename to doc/tripe-admin.5.in index 5d07d690..4bd8144b 100644 --- a/doc/tripe-admin.5 +++ b/doc/tripe-admin.5.in @@ -5,6 +5,10 @@ . 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 @@ -206,8 +210,9 @@ to the end of the line. Lowercase key letters control individual message types. Uppercase key letters control collections of message types. .SH "COMMAND REFERENCE" +.\"* 10 Commands The commands provided are: -.TP +.SP .BI "ADD " peer " \fR[" options "\fR] " address "\fR..." Adds a new peer. The peer is given the name .IR peer ; @@ -220,6 +225,7 @@ option on the command line). The 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 @@ -242,21 +248,22 @@ given, seconds are assumed. .TP .BI "\-tunnel " tunnel Use the named tunnel driver, rather than the default. +.\"-opts .RE -.TP +.SP .BI "ADDR " peer Emits an .B INFO line reporting the IP address and port number stored for .IR peer . -.TP +.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. -.TP +.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. @@ -268,18 +275,18 @@ that it can encrypt and decrypt packets correctly. Options and responses are the same as for the .B PING command. -.TP +.SP .BI "FORCEKX " peer Requests the server to begin a new key exchange with .I peer immediately. -.TP +.SP .B "GETCHAL" Requests a challenge. The challenge is returned in an .B INFO line, as a base64-encoded string. See .BR CHECKCHAL . -.TP +.SP .BI "GREET " peer " " challenge Sends a greeting packet containing the .I challenge @@ -287,14 +294,14 @@ Sends a greeting packet containing the .IR peer . The expectation is that this will cause the peer to recognize us and begin a key-exchange. -.TP +.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. -.TP +.SP .BI "IFNAME " peer Emits an .B INFO @@ -303,25 +310,25 @@ 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 +.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. -.TP +.SP .B "LIST" For each currently-known peer, an .B INFO line is written containing the peer's name, as given to .BR ADD . -.TP +.SP .BI "NOTIFY " tokens\fR... Issues a .B USER notification to all interested administration clients. -.TP +.SP .BI "PEERINFO " peer Returns information about a peer, in key-value form. The following keys are returned. @@ -334,7 +341,7 @@ The tunnel driver used for this peer. The keepalive interval, in seconds, or zero if no keepalives are to be sent. .RE -.TP +.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 @@ -363,6 +370,7 @@ response was received. .IP Options recognized for this command are: .RS +.\"+opts .TP .BI "\-background " tag Run the command in the background, using the given @@ -375,8 +383,9 @@ seconds before giving up on a response. The default is 5 seconds. (The time format is the same as for the .B "ADD \-keepalive" option.) +.\"-opts .RE -.TP +.SP .B "PORT" Emits an .B INFO @@ -384,15 +393,15 @@ 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 +.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. -.TP +.SP .B "QUIT" Instructs the server to exit immediately. A warning is sent. -.TP +.SP .B "SERVINFO" Returns information about the server, in the form of key-value pairs. The following keys are used. @@ -415,14 +424,14 @@ or .BR nil , if the server has or hasn't (respectively) become a daemon. .RE -.TP +.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. -.TP +.SP .BR "TRACE " [\fIoptions\fP] Selects trace outputs: see .B "Trace lists" @@ -491,12 +500,12 @@ without one of or .BR m . .RE -.TP +.SP .B "TUNNELS" For each available tunnel driver, an .B INFO line is printed giving its name. -.TP +.SP .B "VERSION" Causes the server to emit an .B INFO @@ -504,7 +513,7 @@ 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. -.TP +.SP .BR "WATCH " [\fIoptions\fP] Enables or disables asynchronous messages .IR "for the current connection only" . @@ -534,34 +543,35 @@ messages. .B A All of the above. .RE -.TP +.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. -.TP +.SP .BI "already-daemon" (For .BR DAEMON .) The .B tripe server is already running as a daemon. -.TP +.SP .BI "bad-addr-syntax " message (For commands accepting socket addresses.) The address couldn't be understood. -.TP +.SP .BI "bad-syntax " cmd " " message (For any command.) The command couldn't be understood: e.g., the number of arguments was wrong. -.TP +.SP .BI "bad-time-spec " word The .I word @@ -573,28 +583,28 @@ specifications are nonnegative integers followed optionally by or .BR s , for days, hours, minutes, or seconds, respectively. -.TP +.SP .BI "bad-trace-option " char (For .BR TRACE .) An unknown trace option was requested. -.TP +.SP .BI "bad-watch-option " char (For .BR WATCH .) An unknown watch option was requested. -.TP +.SP .BI "daemon-error " ecode " " message (For .BR DAEMON .) An error occurred during the attempt to become a daemon, as reported by .IR message . -.TP +.SP .BI "invalid-port " number (For .BR ADD .) The given port number is out of range. -.TP +.SP .BI "peer-create-fail " peer (For .BR ADD .) @@ -602,36 +612,36 @@ Adding .I peer failed for some reason. A warning should have been emitted explaining why. -.TP +.SP .BI "peer-exists " peer (For .BR ADD .) There is already a peer named .IR peer . -.TP +.SP .B "ping-send-failed" The attempt to send a ping packet failed, probably due to lack of encryption keys. -.TP +.SP .BI "resolve-error " hostname (For .BR ADD .) The DNS name .I hostname could not be resolved. -.TP +.SP .BI "resolver-timeout " hostname (For .BR ADD .) The DNS name .I hostname took too long to resolve. -.TP +.SP .BI "unknown-command " token The command .B token was not recognised. -.TP +.SP .BI "unknown-peer " name (For .BR ADDR , @@ -641,7 +651,7 @@ and .BR STATS .) There is no peer called .IR name . -.TP +.SP .BI "unknown-service " service (For .BR ADD .) @@ -650,8 +660,9 @@ The service name couldn't be found in .BR /etc/services . .SH "NOTIFICATIONS" +.\"* 30 Notification broadcasts (NOTE codes) The following notifications are sent to clients who request them. -.TP +.SP .BI "ADD " peer " " ifname " " address \fR... A new peer has been added. The peer's name is .IR peer , @@ -659,37 +670,39 @@ its tunnel is network interface .IR ifname , and its network address is .IR address . -.TP +.SP .BI "DAEMON" The server has forked off into the sunset and become a daemon. -.TP +.SP .BI "GREET " challenge " " address \fR... A valid greeting was received, with the given challenge (exactly as it was returned by .B GETCHAL earlier). -.TP +.SP .BI "KILL " peer The peer .I peer has been killed. -.TP +.SP .BI "KXDONE " peer Key exchange with .I peer finished successfully. -.TP +.SP .BI "KXSTART " peer Key exchange with .I peer has begun or restarted. If key exchange keeps failing, this message will be repeated periodically. -.TP +.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 @@ -713,17 +726,17 @@ These all indicate that the .B tripe server has become unable to continue. If enabled, the server will dump core in its configuration directory. -.TP +.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. -.TP +.SP .BI "ADMIN accept-error " ecode " " message There was an error while attempting to accept a connection from a new client. -.TP +.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. @@ -731,74 +744,74 @@ client has been closed. These indicate errors in challenges, either in the .B CHECKCHAL command or in greeting packets. -.TP +.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. -.TP +.SP .B "CHAL incorrect-tag" Challenge received contained the wrong authentication data. It might be very stale, or a forgery. -.TP +.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. -.TP +.SP .B "CHAL replay duplicated-sequence" Challenge received was a definite replay of an old challenge. Someone's up to something! -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.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). -.TP +.SP .BI "KEYMGMT public-key " tag " " tokens\fR... These messages all indicate a problem with the public key named .IR tag . -.TP +.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. -.TP +.SP .BI "KEYMGMT public-key " tag " bad " message The public key couldn't be read, or is invalid. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.SP .BI "KEYMGMT public-key " tag " not-found" The public key for peer .I tag wasn't in the public keyring. -.TP +.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 @@ -822,7 +835,7 @@ is one of the tokens .BR switch-rq , or .BR switch-ok . -.TP +.SP .BI "KX " peer " bad-expected-reply-log" The challenges .B tripe @@ -832,43 +845,43 @@ supplied is wrong: someone is attempting to use bogus challenges to persuade your .B tripe server to leak private key information. No chance! -.TP +.SP .BI "KX " peer " decrypt-failed reply\fR|\fBswitch-ok" A symmetrically-encrypted portion of a key-exchange message failed to decrypt. -.TP +.SP .BI "KX " peer " invalid " msgtoken A key-exchange message was malformed. This almost certainly indicates a bug somewhere. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.SP .BI "KX " peer " unknown-message 0x" nn An unknown key-exchange message arrived. .SS "PEER warnings" @@ -877,69 +890,69 @@ details of the network protocol. The second word is usually the name of a peer, or .RB ` \- ' if none is relevant. -.TP +.SP .BI "PEER " peer " bad-packet no-type" An empty packet arrived. This is very strange. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.SP .BI "PEER " peer " malformed-encrypted-ping" The peer sent a ping response which is hopelessly invalid. There's definitely a bug somewhere. -.TP +.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. -.TP +.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. -.TP +.SP .BI "PEER \- socket-read-error " ecode " " message An error occurred trying to read an incoming packet. -.TP +.SP .BI "PEER " peer " socket-write-error " ecode " " message An error occurred attempting to send a network packet. We lost that one. -.TP +.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. -.TP +.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. -.TP +.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 @@ -947,7 +960,7 @@ 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. -.TP +.SP .BI "SERVER ignore signal " name A signal arrived, but the server ignored it. Currently this happens for .B SIGHUP @@ -957,29 +970,29 @@ configuration files. Since 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. -.TP +.SP .BI "SERVER quit signal " \fR[\fInn\fR|\fIname\fR] A signal arrived and .B tripe is going to quit. -.TP +.SP .BI "SERVER quit admin-request" A client of the administration interface issued a .B QUIT command. -.TP +.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. -.TP +.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. -.TP +.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 @@ -989,65 +1002,65 @@ 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. -.TP +.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. -.TP +.SP .BI "TUN - " tun-name " open-error " device " " ecode " " message An attempt to open the tunnel device file .I device failed. -.TP +.SP .BI "TUN \- linux config-error " ecode " " message Configuring the Linux TUN/TAP interface failed. -.TP +.SP .BI "TUN " ifname " " tun-name " read-error " ecode " " message Reading from the tunnel device failed. -.TP +.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. -.TP +.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. -.TP +.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. -.TP +.SP .BI "TUN \- slip fork-error " ecode " " message The SLIP driver encountered an error forking a child process while allocating a new dynamic interface. -.TP +.SP .BI "TUN \- slip no-slip-interfaces" The driver ran out of static SLIP interfaces. Either preallocate more, or use dynamic SLIP interface allocation. -.TP +.SP .BI "TUN " ifname " slip overflow" The SLIP driver gave up reading a packet because it got too large. -.TP +.SP .BI "TUN \- slip pipe-error " ecode " " message The SLIP driver encountered an error creating pipes while allocating a new dynamic interface. -.TP +.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. -.TP +.SP .BI "TUN \- unet config-error " ecode " " message Configuring the Linux Unet interface failed. Unet is obsolete and shouldn't be used any more. -.TP +.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. -.TP +.SP .BI "TUN \- unet ifname-too-long" The Unet interface's name overflowed, so we couldn't read it properly. Unet is obsolete and shouldn't be used any more. @@ -1055,9 +1068,21 @@ Unet is obsolete and shouldn't be used any more. These are issued by administration clients using the .B WARN command. -.TP +.SP .BI "USER " tokens\fR... An administration client issued a warning. +.\"-sep +.SH "SUMMARY" +.SS "Command responses" +.nf +.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). -- [mdw]