Update documentation, including display filter docs.
authorGilbert Ramirez <gram@alumni.rice.edu>
Tue, 3 Aug 1999 16:33:12 +0000 (16:33 -0000)
committerGilbert Ramirez <gram@alumni.rice.edu>
Tue, 3 Aug 1999 16:33:12 +0000 (16:33 -0000)
svn path=/trunk/; revision=427

README
doc/ethereal.pod.template

diff --git a/README b/README
index f08d1e879660da57d26ea5dfbfbfdc326b7f771f..3f3aa5b222ce0a3cd8e77f597976e1597c3cd5f8 100644 (file)
--- a/README
+++ b/README
@@ -34,13 +34,9 @@ It should run on other systems without too much trouble.
 NOTE: the Makefile appears to depend on GNU "make"; it doesn't appear to
 work with the "make" that comes with Solaris 7 nor the BSD "make".
 
-In addition, wiretap (see below) requires "flex" - it cannot be built
-with vanilla "lex" - and either "bison" or the Berkeley "yacc"; whilst
-the "yacc" that comes with Solaris 7 has a "-p" flag to replace "yy" in
-various variable names with a specified prefix, to allow multiple
-yacc-built parsers in the same program, it doesn't replace "yy" in the
-"y.tab.h" file, so the lexical analyzer has no clue that "yylval" has
-been renamed to "wtap_lval".  (What *were* they thinking?)
+In addition, ethereal requires "flex" - it cannot be built
+with vanilla "lex" - and either "bison" or the Berkeley "yacc". Your flex
+version must be 2.5.1 or greater. Check this with 'flex -V'.
 
 You must therefore install GNU "make", "flex", and either "bison" or
 Berkeley "yacc" on systems that lack them.
index fea59013d0682a0dfbfa8a0d616858d8ddda3bdb..641049ed065912dd839e4ccbd2345f28f3c80473 100644 (file)
@@ -29,11 +29,29 @@ S<[ B<-w> savefile]>
 
 =head1 DESCRIPTION
 
-B<Ethereal> is a network protocol analyzer based on the B<GTK+> GUI toolkit.  It lets
+B<Ethereal> is a GUI network protocol analyzer.  It lets
 you interactively browse packet data from a live network or from a previously saved
-capture file. Ethereal knows how to read B<pcap> / B<tcpdump> formatted capture files,
-as well as those of B<snoop>, B<LanAlyzer>, uncompressed B<Sniffer>,
-Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>, and B<Sniffer Pro>.
+capture file. Ethereal knows how to read B<libpcap> capture files, including those of
+B<tcpdump>. In addition, Ethereal can read capture files from B<snoop> (including
+B<Shomiti>), B<LanAlyzer>,
+uncompressed B<Sniffer>, Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>,
+B<Sniffer Pro>, and B<RADCOM>'s WAN/LAN analyzer.
+There is no need to tell Ethereal what type of file you
+are reading; it will determine the file type by itself.
+
+Like other protocol analyzers, B<Ethereal>'s main window shows 3 views of a packet. It
+shows a summary line, briefly describing what the packet is. A protocol tree is shown, allowing
+you to drill down to exact protocol or field that you interested in. Finally, a hex dump
+shows you exactly what the packet looks like when it goes over the wire.
+
+In addition, B<Ethereal> has some features that make it unique. It can assemble all
+the packets in a TCP conversation and show you the ASCII data in that conversation. Display
+filters in B<Ethereal> are very powerful; more fields are filterable in Ethereal than in other
+protocol analyzers, and the syntax you can use to create your filters is richer. As Ethereal
+progresses, expect more and more protocol fields to be allowed in display filters.
+
+Packet capturing is performed with the pcap library. The capture filter syntax follows
+the rules of the pcap library. This syntax is different from the display filter syntax.
 
 =head1 OPTIONS
 
@@ -359,14 +377,128 @@ in the packet list.  You can select "Time of day" for absolute time stamps,
 
 =head1 DISPLAY FILTER SYNTAX
 
-The grammar used for B<Ethereal>'s display filter syntax is similar to
-the syntax of the C programming language.
+Display filters help you remove the noise from a packet trace and let you see only
+the packets that interest you. If a packet meets the requirements expressed in your
+display filter, then it is displayed in the list of packets. Display filters let
+you compare the fields within a protocol against a specific value, compare fields
+against fields, and to check the existence of specified fields or protocols.
+
+The simplest display filter allows you to check for the existence of a protocol or
+field. If you want to see all packets which contain the IPX protocol, the filter would be
+"ipx". (Without the quotation marks) To see all packets that contain a
+Token-Ring RIF field, use "tr.rif".
+
+Fields can also be compared against values. The comparison operators can be expressed
+either through C-like symbols, or through English-like abbreviations:
+
+    eq, ==    Equal
+    ne, !=    Not equal
+    gt, >     Greater than
+    lt, <     Less Than
+    ge, >=    Greater than or Equal to
+    le, <=    Less than or Equal to
+
+Furthermore, each protocol field is typed. The types are:
+
+    Unsigned integer (either 8-bit, 16-bit, or 32-bit)
+    Boolean (true or false)
+    Ethernet address (6 bytes)
+    Byte string (n-number of bytes)
+    IPv4 address
+    IPX network
+
+An integer may be expressed in decimal, octal, or hexadecimal notation. The following
+three display filters are equivalent:
+
+    frame.pkt_len > 10
+    frame.pkt_len > 012
+    frame.pkt_len > 0xa
+
+Boolean values are either true or false. For example, a token-ring packet's source route
+field is boolean:
+
+    tr.sr == true
+
+Ethernet addresses, as well as a string of bytes, are represented in hex digits. The hex
+digits may be separated by colons, periods, or hyphens:
+
+    fddi.dst eq ff:ff:ff:ff:ff:ff
+    ipx.srcnode == 0.0.0.0.0.1
+    ether.src == aa-aa-aa-aa-aa-aa
+
+If a string of bytes contains only one byte, then it is represented as an unsigned integer.
+That is, if you are testing for hex value 'ff' in a one-byte byte-string, you must compare
+it agains '0xff' and not 'ff'.
+
+IPv4 addresses can be represented in either dotted decimal notation, or by using the hostname:
+
+    ip.dst eq www.mit.edu
+    ip.src == 192.168.1.1
+
+IPX networks are represented by unsigned 32-bit integers. Most likely you will be using
+hexadecimal when testing for IPX network values:
+
+    ipx.srcnet == 0xc0a82c00
+
+A substring operator also exists. You can check the substring (byte-string) of any protocol
+or field. For example, you can filter on the vendor portion of an ethernet address (the first
+three bytes) like this:
+
+    ether.src[0:3] == 00:00:83
+
+You can use the substring operator on a protocol name, too. And remember, the "frame" protocol
+encompasses the entire packet, allowing you to look at the nth byte of a packet regardless
+of its frame type (ethernet, token-ring, etc.).
+
+    token[0:5] ne 0.0.0.1.1
+    ipx[0:2] == ff:ff
+    llc[3:1] eq 0xaa
+
+The above tests can be combined together with logical expressions. These too are expressable
+in C-like syntax or with English-like abbreviations:
+
+    and, &&   Logical AND
+    or, ||    Logical OR
+    xor, ^^   Logical XOR
+    not, !    Logical NOT
+
+Expressions can be grouped by parentheses as well. The following are all valid display filter
+expression:
+
+    tcp.port == 80 and ip.src == 192.168.2.1
+    not llc
+    (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
+    tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
+
+A special caveat must be given regarding fields that occur more than once per packet. "ip.addr"
+occurs twice per IP packet, once for the source address, and once for the destination address.
+Likewise, tr.rif.ring fields can occur more than once per packet. The following two expressions
+are not equivalent:
+
+        ip.addr ne 192.168.4.1
+    not ip.addr eq 192.168.4.1
+
+The first filter says "show me all packets where an ip.addr exists that does not equal 192.168.4.1".
+That is, as long as one ip.addr in the packet does not equal 192.168.44.1, the packet passes
+the display filter. The second filter "don't show me any packets that have at least one ip.addr
+field equal to 192.168.4.1". If one ip.addr is 192.168.4.1, the packet does not pass. If B<neither>
+ip.addr fields is 192.168.4.1, then the packet passes.
+
+It is easy to think of the 'ne' and 'eq' operators as having an implict "exists" modifier
+when dealing with multiply-recurring fields. "ip.addr ne 192.168.4.1" can be thought of as
+"there exists an ip.addr that does not equal 192.168.4.1".
+
+Be careful with multiply-recurring fields; they can be confusing.
+
+The following is a table of protocol and protocol fields that are filterable in Ethereal.
+The abbreviation of the protocol or field is given. This abbreviation is what you use in
+the display filter. The type of the field is also given.
 
 =insert_dfilter_table
 
 =head1 SEE ALSO
 
-L<tcpdump(1)>, L<pcap(3)>
+L<tcpdump(8)>, L<pcap(3)>
 
 =head1 NOTES