Move AFS info into man page

Submitted by:	Ken Hornstein <[email protected]>

diff --git a/README-AFS b/README-AFS
deleted file mode 100644 (file)
index 018dd33..0000000
--- a/README-AFS
+++ /dev/null
@@ -1,147 +0,0 @@
-RX Patches for tcpdump 3.4
-
-This directory contains a patch to tcpdump that decodes the information
-inside of RX packets (the protocol used by AFS).  Specifically, all of
-the RX header information is decoded, and many of the arguments to the
-AFS calls.
-
-Some examples:
-
-11:02:26.961538 elvis.7001 > pike.afsfs: rx data fs call rename old fid 536876964/1/1 ".newsrc.new" new fid 536876964/1/1 ".newsrc" (84) (DF)
-
-This is a RX call from elvis (a client) to pike (a fileserver).  It can
-be broken down as follows:
-
-       rx data
-
-This indicates it's an RX packet, and it's rx packet type is "data".
-
-       fs call
-
-This is a packet to the fileserver service (port 7000), and it's an RPC
-call (as opposed to a reply).
-
-       rename
-
-This is the "name" of the call.  This happens to be the rename call.
-
-       old fid 536876964/1/1 ".newsrc.new" new fid 536876964/1/1 ".newsrc"
-
-These are the arguments specific to the RPC call.  In this case, "fid"
-refers to the File Identifier (the unique handle used by AFS to refer
-to every file).  536876964/1/1 is the FID for the directory entry for
-my home directory.  ".newsrc.new" is the name of the old filename,
-".newsrc" is the new name of the filename.
-
-11:02:26.963769 pike.afsfs > elvis.7001: rx data fs reply rename (220) (DF)
-
-The difference here is:
-
-       fs reply rename
-
-which indicates it's a response to the previous RPC call that did a rename.
-The tcpdump module contains a cache of requests (by default, 64) to match
-up RPC calls to replies.  It's possible that in some cases the request will
-be too far seperated from the reply for the cache to match them up.
-
-Some other examples:
-
-13:52:29.743835 elvis.7001 > pike.afsfs: rx data fs call fetch-acl fid 536876964/1/1 (44) (DF)
-13:52:29.750686 pike.afsfs > elvis.7001: rx data fs reply fetch-acl +{system:anyuser rl} +{kenh rlidwka} -{heidi rlidwka} (184) (DF)
-
-This is the result of doing "fs listacl" on my home directory.  You see that
-the request contains the FID of my home directory, and the response contains
-the ACL.  Entries with a + are positive ACL entries, and entries with a -
-are negative ACL entries.
-
-More examples:
-
-13:58:48.397489 elvis.47375 > riker.afsprot: rx data pt call name-to-id "tmc.admin" (292) (DF)
-13:58:48.399103 riker.afsprot > elvis.47375: rx challenge (44) (DF)
-13:58:48.399509 elvis.47375 > riker.afsprot: rx response (140) (DF)
-13:58:48.402905 riker.afsprot > elvis.47375: rx data pt reply name-to-id ids: -584 (36) (DF)
-13:58:48.403438 elvis.47375 > riker.afsprot: rx data pt call name-to-id "tmc.admin" (292) (DF)
-13:58:48.405381 riker.afsprot > elvis.47375: rx data pt reply name-to-id ids: -584 (36) (DF)
-13:58:48.405757 elvis.47375 > riker.afsprot: rx data pt call id-to-name ids: <none!> (36) (DF)
-13:58:48.407058 riker.afsprot > elvis.47375: rx data pt reply id-to-name <none!> (32) (DF)
-13:58:48.407418 elvis.47375 > riker.afsprot: rx data pt call list-elements id -584 (36) (DF)
-13:58:48.409696 riker.afsprot > elvis.47375: rx data pt reply list-elements 1025 1099 2317 4081 (52) (DF)
-13:58:48.410077 elvis.47375 > riker.afsprot: rx data pt call id-to-name ids: 1025 1099 2317 4081 (52) (DF)
-13:58:48.413009 riker.afsprot > elvis.47375: rx data pt reply id-to-name "chas" "tripicia" "heidi" "kenh" (1056) (DF)
-13:58:50.817930 riker.afsprot > elvis.47375: rx data pt reply id-to-name "chas" "tripicia" "heidi" "kenh" (1056) (DF)
-13:58:53.477978 riker.afsprot > elvis.47375: rx data pt reply id-to-name "chas" "tripicia" "heidi" "kenh" (1056) (DF)
-
-Here is the result of running "pts members tmc.admin" on our cell.
-
-The first line shows the initial PTS call to find out the ID of the tmc.admin
-group.  The next two lines shows the RX authentication step (challenge/
-response packets).  Then the same call is made again (why?  I don't know).
-Then the ID to name call is made with no ids in the ID list (again, I don't
-know why this happens).  Then the call is made to list all of the members
-of group -584.  When this list is obtained, the id-to-name call is used
-to convert the list of userids into usernames.  Note that at this point
-because the pts program exits, the ptserver process sends multiple responses
-to the last packet because the final ack has never been received from
-the client.
-
-In general, nearly every AFS RPC is decoded in some form.  Some only
-have the call name, while others decode the arguments to the call (as
-seen above).  In general, you can expect most arguments to fileserver,
-pts, vldb, and ubik calls to be decoded.  There is limited decoding
-of callback, kauth, and bos calls, and currently there is no decoding
-of volserver calls.  I generally tried to decode arguments I thought
-were useful/interesting to humans, but I don't claim to be complete.
-
-Here are some hints/tips to using this patch successfully:
-
-- By default, tcpdump only grabs the first 68 bytes of the packet.  This
-  isn't enough to parse the complete RX header, much less the RPC
-  arguments.  It's recommended you specify a large snap size to tcpdump
-  using the -s flag (I usually do at least 200, and sometimes 300).
-  If you don't specify a snap size, you'll see the following displayed:
-
-14:33:28.497655 elvis.7001 > picard.afsfs: [|rx] (44) (DF)
-14:33:28.499769 picard.afsfs > elvis.7001: [|rx] (148) (DF)
-
-  [|rx] means "truncated rx packet".  There are similar things printed
-  for packets truncated during RPC call decoding ([|fs], [|prot], etc
-  etc).  Note that due to (IMHO) stupid RPC encoding, some RPC calls
-  are very large and will require large snap lengths to decode
-  completely.
-
-- You can use two -v options (-vv) to enable printing of more information
-  inside the rx header, as shown below.
-
-14:37:10.700438 elvis.7001 > picard.afsfs: rx data cid 467592a8 call# 3372 seq 1 ser 5043 <client-init>,<last-pckt> fs call fetch-status fid 536881810/66/52 (44) (DF) (ttl 255, id 30359)
-14:37:10.703651 picard.afsfs > elvis.7001: rx data cid 467592a8 call# 3372 seq 1 ser 5537 <last-pckt> fs reply fetch-status (148) (DF) (ttl 255, id 27089)
-
-  In this packet, "cid" indicates the call identifies (which can be viewed
-  if you're careful with rxdebug), "call#" refers to the RPC call number,
-  "seq" is the RX sequence number, and "ser" is the RX serial number.
-  This is followed by a comma-separated list of RX flags enclosed in <>.
-  The list of possible flags are:
-
-       client-init     Indication that this is an RPC call initiated by a
-                       client.
-       req-ack         An ack is requested for this packet.
-       last-pckt       This is the last packet in this RPC call.
-       more-pckts      There are more packets in this RPC call.
-       free-pckt       Note sure what this means
-
-  If you want even _more_ detail, add another -v (-vvv) and you will get
-  two additional fields output" The security index for the connection and
-  the service id of the RPC call.
-
-- If there is an error, a "rx abort" packet will be returned.  In this
-  case, the error code will be printed from the abort packet (except
-  in the case of a Ubik "beacon" message, because that's how Ubik
-  yes votes are returned, so a more meaningful response is printed).
-
-- Many of arguments to the RPC calls will not make sense without a good
-  understanding of AFS internals.  "Use the Source, Luke!".
-
-Improvements and fixes to this code are welcome.  Share and enjoy!
-
-Ken Hornstein
[email protected]
-10/15/99

diff --git a/tcpdump.1 b/tcpdump.1
index c2d635c6a1cf9db33fadb407c30b2a64653239f3..78cb26459c7250b332109a71c80b9a7a87f3ddce 100644 (file)
--- a/tcpdump.1
+++ b/tcpdump.1
@@ -1,4 +1,4 @@
-.\" @(#) $Header: /tcpdump/master/tcpdump/Attic/tcpdump.1,v 1.73 2000-01-15 07:54:15 itojun Exp $ (LBL)
+.\" @(#) $Header: /tcpdump/master/tcpdump/Attic/tcpdump.1,v 1.74 2000-01-27 23:53:50 fenner Exp $ (LBL)

 .\"
 .\" Copyright (c) 1987, 1988, 1989, 1990, 1991, 1992, 1994, 1995, 1996, 1997
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Copyright (c) 1987, 1988, 1989, 1990, 1991, 1992, 1994, 1995, 1996, 1997
 .\"    The Regents of the University of California.  All rights reserved.


@@ -1111,6 +1111,64 @@ NFS reply packets do not explicitly identify the RPC operation.  Instead,
 \fItcpdump\fP keeps track of ``recent'' requests, and matches them to the
 replies using the transaction ID.  If a reply does not closely follow the
 corresponding request, it might not be parsable.
 \fItcpdump\fP keeps track of ``recent'' requests, and matches them to the
 replies using the transaction ID.  If a reply does not closely follow the
 corresponding request, it might not be parsable.

+.HD
+AFS Request and Replies
+.LP
+Transarc AFS (Andrew File System) requests and replies are printed
+as:
+.HD
+.RS
+.nf
+.sp .5
+\fIsrc.sport > dst.dport: rx packet-type\fP
+\fIsrc.sport > dst.dport: rx packet-type service call call-name args\fP
+\fIsrc.sport > dst.dport: rx packet-type service reply call-name args\fP
+.sp .5
+\f(CW
+elvis.7001 > pike.afsfs:
+       rx data fs call rename old fid 536876964/1/1 ".newsrc.new"
+       new fid 536876964/1/1 ".newsrc"
+pike.afsfs > elvis.7001: rx data fs reply rename
+\fP
+.sp .5
+.fi
+.RE
+In the first line, host elvis sends a RX packet to pike.  This was
+a RX data packet to the fs (fileserver) service, and is the start of
+an RPC call.  The RPC call was a rename, with the old directory file id
+of 536876964/1/1 and an old filename of `.newsrc.new', and a new directory
+file id of 536876964/1/1 and a new filename of `.newsrc'.  The host pike
+responds with a RPC reply to the rename call (which was successful, because
+it was a data packet and not an abort packet).
+.LP
+In general, all AFS RPCs are decoded at least by RPC call name.  Most
+AFS RPCs have at least some of the arguments decoded (generally only
+the `interesting' arguments, for some definition of interesting).
+.LP
+The format is intended to be self-describing, but it will probably
+not be useful to people who are not familiar with the workings of
+AFS and RX.
+.LP
+If the -v (verbose) flag is given twice, additional information is printed,
+such as the the RX call ID, call number, sequence number, serial number,
+and the RX packet flags.
+.LP
+If the -v flag is given again, the security index and service id are printed.
+.LP
+Error codes are printed for abort packets, with the exception of Ubik
+beacon packets (because abort packets are used to signify a yes vote
+for the Ubik protocol).
+.LP
+Note that AFS requests are very large and many of the arguments won't
+be printed unless \fIsnaplen\fP is increased.  Try using `\fB-s 256\fP'
+to watch AFS traffic.
+.LP
+AFS reply packets do not explicitly identify the RPC operation.  Instead,
+\fItcpdump\fP keeps track of ``recent'' requests, and matches them to the
+replies using the call number and service ID.  If a reply does not closely
+follow the
+corresponding request, it might not be parsable.
+

 .HD
 KIP Appletalk (DDP in UDP)
 .LP
 .HD
 KIP Appletalk (DDP in UDP)
 .LP