=head1 NAME
-Tethereal - Dump and analyze network traffic
+tethereal - Dump and analyze network traffic
=head1 SYNOPSYS
B<tethereal>
S<[ B<-c> count ]>
S<[ B<-D> ]>
-S<[ B<-f> filter expression ]>
+S<[ B<-f> capture filter expression ]>
S<[ B<-F> file format ]>
S<[ B<-h> ]>
S<[ B<-i> interface ]>
+S<[ B<-l> ]>
S<[ B<-n> ]>
+S<[ B<-N> resolving flags ] ...>
S<[ B<-o> preference setting ] ...>
+S<[ B<-p> ]>
S<[ B<-r> infile ]>
-S<[ B<-R> filter expression ]>
+S<[ B<-R> display filter expression ]>
S<[ B<-s> snaplen ]>
S<[ B<-t> time stamp format ]>
S<[ B<-v> ]>
addition, B<Tethereal> can read capture files from B<snoop> (including
B<Shomiti>) and B<atmsnoop>, B<LanAlyzer>, B<Sniffer> (compressed or
uncompressed), Microsoft B<Network Monitor>, AIX's B<iptrace>,
-B<NetXray>, B<Sniffer Pro>, B<RADCOM>'s WAN/LAN analyzer,
+B<NetXray>, B<Sniffer Pro>, B<Etherpeek>, B<RADCOM>'s WAN/LAN analyzer,
B<Lucent/Ascend> router debug output, HP-UX's B<nettl>, the dump output
from B<Toshiba's> ISDN routers, the output from B<i4btrace> from the
-ISDN4BSD project, and output in IPLog format from the Cisco Secure
-Intrusion Detection System. There is no need to tell B<Tethereal> what
-type of file you are reading; it will determine the file type by itself.
-B<Tethereal> is also capable of reading any of these file formats if
-they are compressed using gzip. B<Tethereal> recognizes this directly
-from the file; the '.gz' extension is not required for this purpose.
+ISDN4BSD project, the output in B<IPLog> format from the Cisco Secure
+Intrusion Detection System, B<pppd logs> (pppdump format), the output
+from VMS's B<TCPIPtrace> utility, and the text output from the
+B<DBS Etherwatch> VMS utility. There is no need to tell B<Tethereal>
+what type of file you are reading; it will determine the file type by
+itself. B<Tethereal> is also capable of reading any of these file
+formats if they are compressed using gzip. B<Tethereal> recognizes this
+directly from the file; the '.gz' extension is not required for this
+purpose.
If the B<-w> flag is not specified, B<Tethereal> prints a decoded form
of the packets it captures or reads; otherwise, it writes those packets
to the file specified by that flag.
When printing a decoded form of packets, B<Tethereal> prints, by
-default, a summary line giving a time stamp for the packet if it's
-reading a capture file (but not if it's printing packets as it captures
-them), the source and destination address for the packet, the top-level
-protocol for the packet that B<Tethereal> understands, and a summary of
-the packet's contents for that protocol. If the B<-V> flag is
-specified, it prints intead a protocol tree, showing all the fields of
-all protocols in the packet.
+default, a summary line containing the fields specified by the
+preferences file (which are also the fields displayed in the packet list
+pane in B<Ethereal>), although if it's printing packets as it captures
+them, rather than printing packets from a saved capture file, it won't
+print the "frame number" field. If the B<-V> flag is specified, it
+prints intead a protocol tree, showing all the fields of all protocols
+in the packet.
When writing packets to a file, B<Tethereal>, by default, writes the
file in B<libpcap> format, and writes all of the packets it sees to the
syntax follows the rules of the pcap library. This syntax is different
from the read filter syntax. A read filter can also be specified when
capturing, and only packets that pass the read filter will be displayed
-or saved to the output file; note, however, that capture filers are much
+or saved to the output file; note, however, that capture filters are much
more efficient than read filters, and it may be more difficult for
B<Tethereal> to keep up with a busy network if a read filter is
specified for a live capture.
specified as a single argument (which means that if it contains spaces,
it must be quoted), or can be specified with command-line arguments
after the option arguments, in which case all the arguments after the
-filter arguments are treated as a filter expression.
+filter arguments are treated as a filter expression. If the filter is
+specified with command-line arguments after the option arguments, it's a
+capture filter if a capture is being done (i.e., if no B<-r> flag was
+specified) and a read filter if a capture file is being read (i.e., if a
+B<-r> flag was specified).
=head1 OPTIONS
=item -D
-Turns off treating the original IPv4 TOS field as the Differentiated
-Services Field. The structure of the DS Field is defined in RFC 2474.
+Prints a list of the interfaces on which B<Tethereal> can capture, and
+exits. Note that "can capture" means that B<Tethereal> was able to open
+that device to do a live capture; if, on your system, a program doing a
+network capture must be run from an account with special privileges (for
+example, as root), then, if B<Tethereal> is run with the B<-D> flag and
+is not run from such an account, it will not list any interfaces.
=item -f
interface if there are no non-loopback interfaces; if there are no
interfaces, B<Tethereal> reports an error and doesn't start the capture.
+=item -l
+
+Flush the standard output after the information for each packet is
+printed. (This is not, strictly speaking, line-buffered if B<-V>
+was specified; however, it is the same as line-buffered if B<-V> wasn't
+specified, as only one line is printed for each packet, and, as B<-l> is
+normally used when piping a live capture to a program or script, so that
+output for a packet shows up as soon as the packet is seen and
+dissected, it should work just as well as true line-buffering. We do
+this as a workaround for a deficiency in the Microsoft Visual C++ C
+library.)
+
+This may be useful when piping the output of B<Tethereal> to another
+program, as it means that the program to which the output is piped will
+see the dissected data for a packet as soon as B<Tethereal> sees the
+packet and generates that output, rather than seeing it only when the
+standard output buffer containing that data fills up.
+
=item -n
Disables network object name resolution (such as hostname, TCP and UDP port
names).
+=item -N
+
+Turns on name resolving for particular types of addresses and port
+numbers; the argument is a string that may contain the letters B<m> to
+enable MAC address resolution, B<n> to enable network address
+resolution, and B<t> to enable transport-layer port number resolution.
+This overrides B<-n> if both B<-N> and B<-n> are present.
+
=item -o
Sets a preference value, overriding the default value and any value read
preference (which is the same name that would appear in the preference
file), and I<value> is the value to which it should be set.
+=item -p
+
+I<Don't> put the interface into promiscuous mode. Note that the
+interface might be in promiscuous mode for some other reason; hence,
+B<-p> cannot be used to ensure that the only traffic that is captured is
+traffic sent to or from the machine on which B<Tethereal> is running,
+broadcast traffic, and multicast traffic to addresses received by that
+machine.
+
=item -r
Reads packet data from I<file>.
=item -t
-Sets the format of the packet timestamp printed in summary lines.
-The format can be one of 'r' (relative), 'a' (absolute), or 'd'
-(delta). The relative time is the time elapsed between the first packet
-and the current packet. The absolute time is the actual date and time the
-packet was captured. The delta time is the time since the previous packet
-was captured. The default is relative.
+Sets the format of the packet timestamp printed in summary lines. The
+format can be one of 'r' (relative), 'a' (absolute), 'ad' (absolute with
+date), or 'd' (delta). The relative time is the time elapsed between
+the first packet and the current packet. The absolute time is the
+actual time the packet was captured, with no date displayed; the
+absolute date and time is the actual time and date the packet was
+captured. The delta time is the time since the previous packet was
+captured. The default is relative.
=item -v
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 read filter
-is simply:
+Boolean values are either true or false. In a read filter expression
+testing the value of a Boolean field, "true" is expressed as 1 or any
+other non-zero value, and "false" is expressed as zero. For example, a
+token-ring packet's source route field is boolean. To find any
+source-routed packets, a read filter would be:
- tr.sr
+ tr.sr == 1
-Non source-routed packets can be found with the negation of that filter:
+Non source-routed packets can be found with:
- ! tr.sr
+ tr.sr == 0
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:
ip.dst eq www.mit.edu
ip.src == 192.168.1.1
-IPv4 address can be compared with the same logical relations as numbers:
+IPv4 addresses 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 read filter.
Classless InterDomain Routing (CIDR) notation can be used to test if an
-IPv4 address is in a certain subnet. For example, this read filter
+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
ip.addr eq sneezy/24
The CIDR notation can only be used on IP addresses or hostnames, not in
-variable names. So, a read filter like "ip.src/24 == ip.dst/24" is
+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
ipx.srcnet == 0xc0a82c00
-A substring operator also exists. You can check the substring
+A slice 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:
-
- 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:
+If the length of your byte-slice is only one byte, then it is still
+represented in hex, but without the preceding "0x":
- fddi.src[0:3] == fddi.dst[0:3]
+ llc[3] == aa
-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
+You can use the slice 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.).
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:
+The following syntax governs slices:
- frame[-4] == 0.1.2.3
+ [i:j] i = start_offset, j = length
+ [i-j] i = start_offet, j = end_offset, inclusive.
+ [i] i = start_offset, length = 1
+ [:j] start_offset = 0, length = j
+ [i:] start_offset = i, end_offset = end_of_field
-or
+Offsets and lengths can be negative, in which case they indicate the
+offset from the B<end> of the field. Here's how to check the last 4
+bytes of a frame:
frame[-4:4] == 0.1.2.3
+or
+
+ frame[-4:] == 0.1.2.3
+
+You can create complex concatenations of slices using the comma operator:
+
+ field[1,3-5,9:] == 01:03:04:05:09:0a:0b
+
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
=head1 FILES
-F</usr/local/etc/ethereal.conf> and F<$HOME/.ethereal/preferences>
-contain system-wide and personal preference settings, respectively. The
-file contains preference settings of the form I<prefname>B<:>I<value>,
-one per line, where I<prefname> is the name of the preference (which is
-the same name that would appear in the preference file), and I<value> is
-the value to which it should be set; white space is allowed between B<:>
-and I<value>. A preference setting can be continued on subsequent lines
-by indenting the continuation lines with white space. A B<#> character
-starts a comment that runs to the end of the line.
+The F<ethereal.conf> file, which is installed in the F<etc> directory
+under the main installation directory (for example, F</usr/local/etc>)
+on UNIX-compatible systems, and in the main installation directory (for
+example, F<C:\Program Files\Ethereal>) on Windows systems, and the
+personal preferences file, which is F<$HOME/.ethereal/preferences> on
+UNIX-compatible systems and F<%APPDATA%\Ethereal\preferences> (or, if
+%APPDATA% isn't defined,
+F<%USERPROFILE%\Application Data\Ethereal\preferences>) on
+Windows systems, contain system-wide and personal preference settings,
+respectively. The file contains preference settings of the form
+I<prefname>B<:>I<value>, one per line, where I<prefname> is the name of
+the preference (which is the same name that would appear in the
+preference file), and I<value> is the value to which it should be set;
+white space is allowed between B<:> and I<value>. A preference setting
+can be continued on subsequent lines by indenting the continuation lines
+with white space. A B<#> character starts a comment that runs to the
+end of the line.
The system-wide preference file is read first, if it exists, overriding
B<Tethereal>'s default values; the personal preferences file is then
read, if it exists, overriding default values and values read from the
system-wide preference file.
-F</etc/ethers> is consulted to correlate 6-byte hardware addresses to
-names. If an address is not found in F</etc/ethers>, the
-F<$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:
+The F<ethers> file, which is found in the F</etc> directory on
+UNIX-compatible systems, and in the main installation directory (for
+example, F<C:\Program Files\Ethereal>) on Windows systems, is consulted
+to correlate 6-byte hardware addresses to names. If an address is not
+found in the F<ethers> file, the F<$HOME/.ethereal/ethers> file on
+UNIX-compatible systems, and the F<%APPDATA%\Ethereal\ethers> file (or, if
+%APPDATA% isn't defined, the
+F<%USERPROFILE%\Application Data\Ethereal\ethers> file) on Windows
+systems 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
-F</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 F</etc/ethers> file, except that each address is
-three bytes instead of six.
-
-F</etc/ipxnets> and F<$HOME/.ethereal/ipxnets> correlate 4-byte IPX
-network numbers to names. The format is the same as the F</etc/ethers>
-file, except that each address if four bytes instead of six.
+The F<manuf> file, which is installed in the F<etc> directory under the
+main installation directory (for example, F</usr/local/etc>) on
+UNIX-compatible systems, and in the main installation directory (for
+example, F<C:\Program Files\Ethereal>) on Windows systems, 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
+F<ethers> file, except that each address is three bytes instead of six.
+
+The F<ipxnets> file, which is found in the F</etc> directory on
+UNIX-compatible systems, and in the main installation directory (for
+example, F<C:\Program Files\Ethereal>) on Windows systems, correlates
+4-byte IPX network numbers to names. If a network number is not found
+in the F<ipxnets> file, the F<$HOME/.ethereal/ipxnets> file on
+UNIX-compatible systems, and the F<%APPDATA%\Ethereal\ipxnets> file (or,
+if %APPDATA% isn't defined, the
+F<%USERPROFILE%\Application Data\Ethereal\ipxnets> file)
+on Windows systems, is consulted next. The format is the same as the
+F<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.
=head1 SEE ALSO
-L<ethereal(1)>, L<tcpdump(8)>, L<pcap(3)>
+L<ethereal(1)>, L<
editcap(1)>, L<tcpdump(8)>, L<pcap(3)>
=head1 NOTES
B<Tethereal> is part of the B<Ethereal> distribution. The latest version
-of B<Ethereal> can be found at B<http://ethereal.zing.org>.
+of B<Ethereal> can be found at B<http://www.ethereal.com>.
=head1 AUTHORS
git.samba.org / obnox / wireshark / wip.git / blobdiff