diff options
author | Guy Harris <guy@alum.mit.edu> | 1999-12-16 08:05:46 +0000 |
---|---|---|
committer | Guy Harris <guy@alum.mit.edu> | 1999-12-16 08:05:46 +0000 |
commit | dcf312c1079785c4632580eee023080ef6f1fa60 (patch) | |
tree | af93c0212afbb0db93bbd43b8b2704f879f9b0d8 /doc/ethereal.pod.template | |
parent | f34e877593e4ae244e130751c23a6dd9470b18fa (diff) |
Put "Ethereal" in boldface everywhere it appears.
Reformat some (source) paragraphs, for the benefit of those with editors
that don't wrap lines in the display.
Delete some extra "=back" directives.
Fix the description of the "Preferences" dialog (it lets you control
various preferences, not just print preferences; it's the "Print" tab
that lets you control print preferences).
svn path=/trunk/; revision=1352
Diffstat (limited to 'doc/ethereal.pod.template')
-rw-r--r-- | doc/ethereal.pod.template | 252 |
1 files changed, 137 insertions, 115 deletions
diff --git a/doc/ethereal.pod.template b/doc/ethereal.pod.template index ba38bc0fe1..00e768d62f 100644 --- a/doc/ethereal.pod.template +++ b/doc/ethereal.pod.template @@ -30,37 +30,40 @@ S<[ B<-w> savefile]> 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<libpcap> -capture files, including those of B<tcpdump>. In addition, Ethereal can +previously saved capture file. B<Ethereal> knows how to read B<libpcap> +capture files, including those of B<tcpdump>. In addition, B<Ethereal> can read capture files from B<snoop> (including B<Shomiti>) and B<atmsnoop>, B<LanAlyzer>, uncompressed B<Sniffer>, Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>, B<Sniffer Pro>, B<RADCOM>'s WAN/LAN analyzer, B<Lucent/Ascend> router debug output, HP-UX's B<nettl>, and the dump output from B<Toshiba's> ISDN routers. There is no need to -tell Ethereal what type of file you are reading; it will determine the -file type by itself. Ethereal is also capable of reading any of these -file formats if they are compressed using gzip. Ethereal recognizes +tell B<Ethereal> what type of file you are reading; it will determine the +file type by itself. B<Ethereal> is also capable of reading any of these +file formats if they are compressed using gzip. B<Ethereal> recognizes this directly from the file; the '.gz' extension is not required for this purpose. -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 +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 (or EBCDIC) data in that conversation. Display filters in B<Ethereal> -are very powerful; more fields are filterable in Ethereal than in other +are very powerful; more fields are filterable in B<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 +richer. As B<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. +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. -Compressed file support uses (and therefore requires) the zlib library. If the zlib -library is not present, Ethereal will compile, but will be unable to read compressed files. +Compressed file support uses (and therefore requires) the zlib library. +If the zlib library is not present, B<Ethereal> will compile, but will +be unable to read compressed files. =head1 OPTIONS @@ -217,11 +220,11 @@ capture, if any. =item Capture:Start -Initiates a live packet capture (see L<"Capture Preferences"> below). -A temporary file will be created to hold the capture. The location of the +Initiates a live packet capture (see L<"Capture Preferences"> below). A +temporary file will be created to hold the capture. The location of the file can be chosen by setting your TMPDIR environment variable before -starting ethereal. Otherwise, the default TMPDIR location is system-dependent, -but is likely either /var/tmp or /tmp. +starting B<Ethereal>. Otherwise, the default TMPDIR location is +system-dependent, but is likely either /var/tmp or /tmp. =item Display:Options @@ -329,20 +332,20 @@ packets are displayed. =item Preferences -The I<Preferences> dialog lets you select the output format of packets -printed using the I<File:Print Packet> menu item. +The I<Preferences> dialog lets you control various personal preferences +for the behavior of B<Ethereal>. =over 6 =item Printing Preferences The radio buttons at the top of the I<Printing> page allow you choose -between printing the packets as text or PostScript, and sending the -output directly to a command or saving it to a file. The I<Command:> text -entry box is the command to send files to (usually B<lpr>), and the -I<File:> entry box lets you enter the name of the file you wish to save -to. Additinally, you can select the I<File:> button to browse the file -system for a particular save file. +between printing packets with the I<File:Print Packet> menu item as text +or PostScript, and sending the output directly to a command or saving it +to a file. The I<Command:> text entry box is the command to send files +to (usually B<lpr>), and the I<File:> entry box lets you enter the name +of the file you wish to save to. Additionally, you can select the +I<File:> button to browse the file system for a particular save file. =item Column Preferences @@ -393,8 +396,6 @@ displayed in the TCP stream window. To change a color, simply select an attribute from the "Set:" menu and use the color selector to get the desired color. The new text colors are displayed in a sample window. -=back - =item GUI Preferences The I<GUI> page is used to modify small aspects of the GUI to your own @@ -497,27 +498,27 @@ The I<Filter> button shows the filter used to select packets which should be dissected by a plugin (see L<"DISPLAY FILTER SYNTAX"> below). This filter can be modified. -=back - =head1 CAPTURE FILTER SYNTAX See manual page of tcpdump(8). =head1 DISPLAY FILTER SYNTAX -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. +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". +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: +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 @@ -539,18 +540,20 @@ Furthermore, each protocol field is typed. The types are: String (text) Double-precision floating point number -An integer may be expressed in decimal, octal, or hexadecimal notation. The following -three display filters are equivalent: +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. However, a boolean field is present in a -protocol decode only if its value is true. If the value is false, the field is not presence. -You can therefore check the truth value of a boolean field by simply checking for its -existence, that is, by naming the field. For example, a token-ring packet's source route -field is boolean. To find any source-routed packets, the display filter is simply: +Boolean values are either true or false. However, a boolean field is +present in a protocol decode only if its value is true. If the value is +false, the field is not presence. You can therefore check the truth +value of a boolean field by simply checking for its existence, that is, +by naming the field. For example, a token-ring packet's source route +field is boolean. To find any source-routed packets, the display filter +is simply: tr.sr @@ -558,78 +561,87 @@ Non source-routed packets can be found with the negation of that filter: ! tr.sr -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: +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 eth.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'. +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: +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 -IPv4 address can be compared with the same logical relations as numbers: eq, ne, gt, -ge, lt, and le. The IPv4 address is stored in host order, so you do not have to worry -about how the endianness of an IPv4 address when using it in a display filter. +IPv4 address can be compared with the same logical relations as numbers: +eq, ne, gt, ge, lt, and le. The IPv4 address is stored in host order, +so you do not have to worry about how the endianness of an IPv4 address +when using it in a display filter. -Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address -is in a certain subnet. For example, this display filter will find all packets -in the 129.111 Class-B network: +Classless InterDomain Routing (CIDR) notation can be used to test if an +IPv4 address is in a certain subnet. For example, this display filter +will find all packets in the 129.111 Class-B network: ip.addr == 129.111.0.0/16 -Remember, the number after the slash represents the number of bits used to represent -the network. CIDR notation can also be used with hostnames, in this example of finding -IP addresses on the same Class C network as 'sneezy' +Remember, the number after the slash represents the number of bits used +to represent the network. CIDR notation can also be used with +hostnames, in this example of finding IP addresses on the same Class C +network as 'sneezy': ip.addr eq sneezy/24 -The CIDR notation can only be used on IP addresses or hostnames, not in variable names. -So, a display filter like "ip.src/24 == ip.dst/24" is not valid. (yet) +The CIDR notation can only be used on IP addresses or hostnames, not in +variable names. So, a display filter like "ip.src/24 == ip.dst/24" is +not valid. (yet) -IPX networks are represented by unsigned 32-bit integers. Most likely you will be using -hexadecimal when testing for IPX network values: +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: +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: eth.src[0:3] == 00:00:83 -Or more simply, since the number of bytes is inherent in the byte-string you provide, you -can provide just the offset. The previous example can be stated like this: +Or more simply, since the number of bytes is inherent in the byte-string +you provide, you can provide just the offset. The previous example can +be stated like this: eth.src[0] == 00:00:83 -In fact, the only time you need to explicitly provide a length is when you don't provide -a byte-string, and are comparing fields against fields: +In fact, the only time you need to explicitly provide a length is when +you don't provide a byte-string, and are comparing fields against +fields: fddi.src[0:3] == fddi.dst[0:3] -If the length of your byte-string is only one byte, then it must be represented in the -same way as an unsigned 8-bit integer: +If the length of your byte-string is only one byte, then it must be +represented in the same way as an unsigned 8-bit integer: llc[3] == 0xaa -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.). +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 -Offsets for byte-strings can also be negative, in which case the negative number indicates -the number of bytes from the end of the field or protocol that you are testing. Here's how -to check the last 4 bytes of a frame: +Offsets for byte-strings can also be negative, in which case the +negative number indicates the number of bytes from the end of the field +or protocol that you are testing. Here's how to check the last 4 bytes +of a frame: frame[-4] == 0.1.2.3 @@ -637,69 +649,79 @@ or frame[-4:4] == 0.1.2.3 -All the above tests can be combined together with logical expressions. These too are expressable -in C-like syntax or with English-like abbreviations: +All 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: +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: +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. +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". +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. +The following is a table of protocol and protocol fields that are +filterable in B<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 FILES -B</etc/ethers> is consulted to correlate 6-byte hardware addresses to names. If an address is not -found in B</etc/ethers>, the B<$HOME/.ethereal/ethers> file is consulted next. Each line -contains one hardware address and name, separated by whitespace. -The digits of the hardware address are separated by either a colon (:), a dash (-), or -a period (.). The following three lines are valid lines of an ethers file: +B</etc/ethers> is consulted to correlate 6-byte hardware addresses to +names. If an address is not found in B</etc/ethers>, the +B<$HOME/.ethereal/ethers> file is consulted next. Each line contains +one hardware address and name, separated by whitespace. The digits of +the hardware address are separated by either a colon (:), a dash (-), or +a period (.). The following three lines are valid lines of an ethers +file: ff:ff:ff:ff:ff:ff Broadcast c0-00-ff-ff-ff-ff TR_broadcast 00.00.00.00.00.00 Zero_broadcast -B</usr/local/etc/manuf> matches the 3-byte vendor portion of a 6-byte hardware address with -the manufacturer's name. The format of the file is the same as the B</etc/ethers> file, -except that each address is three bytes instead of six. +B</usr/local/etc/manuf> matches the 3-byte vendor portion of a 6-byte +hardware address with the manufacturer's name. The format of the file +is the same as the B</etc/ethers> file, except that each address is +three bytes instead of six. -B</etc/ipxnets> and B<$HOME/.ethereal/ipxnets> correlate 4-byte IPX network numbers to names. -The format is the same as the B</etc/ethers> file, except that each address if four bytes -instead of six. Additionally, the address can be represented a single hexadecimal number, -as is more common in the IPX world, rather than four hex octets. For example, these four -lines are valid lines of an ipxnets file. +B</etc/ipxnets> and B<$HOME/.ethereal/ipxnets> correlate 4-byte IPX +network numbers to names. The format is the same as the B</etc/ethers> +file, except that each address if four bytes instead of six. +Additionally, the address can be represented a single hexadecimal +number, as is more common in the IPX world, rather than four hex octets. +For example, these four lines are valid lines of an ipxnets file. C0.A8.2C.00 HR c0-a8-1c-00 CEO @@ -712,7 +734,7 @@ L<tcpdump(8)>, L<pcap(3)> =head1 NOTES -The latest version of B<ethereal> can be found at +The latest version of B<Ethereal> can be found at B<http://ethereal.zing.org>. =head1 AUTHORS |