=head1 SYNOPSYS
B<ethereal>
+S<[ B<-a> capture autostop condition ] ...>
+S<[ B<-b> number of ring buffer files ]>
S<[ B<-B> byte view height ]>
S<[ B<-c> count ]>
S<[ B<-f> capture filter expression ]>
S<[ B<-l> ]>
S<[ B<-m> font ]>
S<[ B<-n> ]>
-S<[ B<-N> resolving flags ] ...>
+S<[ B<-N> resolving flags ] >
S<[ B<-o> preference setting ] ...>
S<[ B<-p> ]>
S<[ B<-P> packet list height ]>
S<[ B<-t> time stamp format ]>
S<[ B<-v> ]>
S<[ B<-w> savefile]>
+S<[ infile ]>
=head1 DESCRIPTION
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. 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>, B<Sniffer> (compressed or uncompressed),
-Microsoft B<Network Monitor>, AIX's B<iptrace>, 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, 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<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.
+previously saved capture file. B<Ethereal>'s native capture file format
+is B<libpcap> format, which is also the format used by B<tcpdump> and
+various other tools. In addition, B<Ethereal> can read capture files
+from B<snoop> and B<atmsnoop>, Shomiti/Finisar B<Surveyor>, Novell
+B<LANalyzer>, Network General/Network Associates DOS-based B<Sniffer>
+(compressed or uncompressed), Microsoft B<Network Monitor>, AIX's
+B<iptrace>, Cinco Networks B<NetXRay>, Network Associates Windows-based
+B<Sniffer>, AG Group/WildPackets B<EtherPeek> and B<TokenPeek>,
+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, 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, the
+text output from the B<DBS Etherwatch> VMS utility, and traffic capture
+files from Visual Networks' Visual UpTime. There is no need to 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
If the zlib library is not present, B<Ethereal> will compile, but will
be unable to read compressed files.
+The pathname of a capture file to be read can be specified with the
+B<-r> option or can be specified as a command-line argument.
+
=head1 OPTIONS
=over 4
+=item -a
+
+Specify a criterion that specifies when B<Tethereal> is to stop writing
+to a capture file. The criterion is of the form I<test>B<:>I<value>,
+where I<test> is one of:
+
+=for man .RS
+
+=for html <P><DL>
+
+=item duration
+
+Stop writing to a capture file after I<value> seconds have elapsed.
+
+=item filesize
+
+Stop writing to a capture file after it reaches a size of I<value>
+kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes).
+
+=for man .RE
+
+=for html </DL>
+
+=item -b
+
+If a maximum capture file size was specified, causes B<Ethereal> to run
+in "ring buffer" mode, with the specified number of files. In "ring
+buffer" mode, B<Ethereal> will write to several capture files; the name
+of the first file, while the capture is in progress, will be the name
+specified by the B<-w> flag, and subsequent files with have .I<n>
+appended, with I<n> counting up.
+
+When the first capture file fills up, B<Ethereal> will switch to writing
+to the next file, until it fills up the last file, at which point it'll
+discard the data in the first file and start writing to that file. When
+that file fills up, B<Ethereal> will discard the data in the next file
+and start writing to it, and so on.
+
+When the capture completes, the files will be renamed to have names
+based on the number of the file and on the date and time at which
+packets most recently started being written to the file.
+
=item -B
Sets the initial height of the byte view (bottom) pane.
=item -r
-Reads packet data from I<file>.
+Reads packet data from I<infile>.
=item -R
=item Capture:Start
-Initiates a live packet capture (see L<"Capture Preferences"> below). A
+Initiates a live packet capture (see L<"Capture Options"> 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 B<Ethereal>. Otherwise, the default TMPDIR location is
while a live capture is in progress or to enable or disable translation
of addresses to names in the display.
-=item Display:Match Selected
+=item Display:Match
+
+Creates a display filter, or adds to the display filter strip at the
+bottom, a display filter based on the data currently highlighted in the
+protocol tree, and applies the filter.
+
+If that data is a field that can be tested in a display filter
+expression, the display filter will test that field; otherwise, the
+display filter will be based on absolute offset within the packet, and
+so could be unreliable if the packet contains protocols with
+variable-length headers, such as a source-routed token-ring packet.
+
+The B<Selected> option creates a display filter that tests for a match
+of the data; the B<Not Selected> option creates a display filter that
+tests for a non-match of the data. The B<And Selected>, B<Or Selected>,
+B<And Not Selected>, and B<Or Not Selected> options add to the end of
+the display filter in the strip at the bottom an AND or OR operator
+followed by the new display filter expression.
+
+=item Display:Prepare
-Creates and applies a display filter based on the data that is currently
-highlighted in the protocol tree. If that data is a field that can be
-tested in a display filter expression, the display filter will test that
-field; otherwise, the display filter will be based on absolute offset
-within the packet, and so could be unreliable if the packet contains
-protocols with variable-length headers, such as a source-routed
-token-ring packet.
+Creates a display filter, or adds to the display filter strip at the
+bottom, a display filter based on the data currently highlighted in the
+protocol tree, but doesn't apply the filter.
=item Display:Colorize Display
Selecting the I<Filter:> button lets you choose from a list of named
filters that you can optionally save. Pressing the Return or Enter
-keys will cause the filter to be applied to the current list of packets.
-Selecting the I<Reset> button clears the display filter so that all
-packets are displayed.
+keys, or selecting the I<Apply> button, will cause the filter to be
+applied to the current list of packets. Selecting the I<Reset> button
+clears the display filter so that all packets are displayed.
=back
The radio buttons at the top of the I<Printing> page allow you choose
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.
+to a file. The I<Command:> text entry box, on UNIX-compatible systems,
+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
=back
-=item TCP Stream Preferences
+=item TCP Streams Preferences
The I<TCP Streams> page can be used to change the color of the text
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.
-=item GUI Preferences
+=item User Interface Preferences
-The I<GUI> page is used to modify small aspects of the GUI to your own
-personal taste:
+The I<User Interface> page is used to modify small aspects of the GUI to
+your own personal taste:
=over 6
=item Selection Bars
-The selection bar in the
-packet list and protocol tree can have either a "browse" or "select"
-behavior. If the selection bar has a "browse" behavior, the arrow keys
-will move an outline of the selection bar, allowing you to browse
-the rest of the list or tree without changing the selection
-until you press the space bar. If the selection bar has a "select"
-behavior, the arrow keys will move the selection bar and change
+The selection bar in the packet list and protocol tree can have either a
+"browse" or "select" behavior. If the selection bar has a "browse"
+behavior, the arrow keys will move an outline of the selection bar,
+allowing you to browse the rest of the list or tree without changing the
+selection until you press the space bar. If the selection bar has a
+"select" behavior, the arrow keys will move the selection bar and change
the selection to the new item in the packet list or protocol tree.
+
+=item Tree Line Style
+
+Trees can be drawn with no lines, solid lines, or dotted lines between
+items, or can be drawn with "tab" headings.
+
+=item Tree Expander Style
+
+The expander item that can be clicked to show or hide items under a tree
+item can be omitted (note that this will prevent you from changing
+whether those items are shown or hidden!), or can be drawn as squares,
+triangles, or circles.
+
+=item Hex Display
+
The highlight method in the hex dump display for the selected protocol
item can be set to use either inverse video, or bold characters.
+=item Save Window Position
+
+If this item is selected, the position of the main Ethereal window will
+be saved when Ethereal exits, and used when Ethereal is started again.
+
+=item Save Window Size
+
+If this item is selected, the size of the main Ethereal window will
+be saved when Ethereal exits, and used when Ethereal is started again.
+
=item Fonts
The "Font..." button lets you select the font to be used for most text.
=back
+=item Capture Preferences
+
+The I<Capture> page lets you specify various parameters for capturing
+live packet data; these are used the first time a capture is started.
+
+The I<Interface:> combo box lets you specify the interface from which to
+capture packet data, or the name of a FIFO from which to get the packet
+data. You can specify whether the interface is to be put in promiscuous
+mode or not with the I<Capture packets in promiscuous mode> check box,
+can specify that the display should be updated as packets are captured
+with the I<Update list of packets in real time> check box, and can
+specify whether in such a capture the packet list pane should scroll to
+show the most recently captured packets with the I<Automatic scrolling
+in live capture> check box.
+
=item Protocol Preferences
There are also pages for various protocols that Ethereal dissects,
=back
-=item Capture Preferences
+=item Capture Options
-The I<Capture Preferences> dialog lets you specify various parameters for
+The I<Capture Options> dialog lets you specify various parameters for
capturing live packet data.
The I<Interface:> combo box lets you specify the interface from which to
-capture packet data, or the name of a FIFO from which to get the packet
-data. The I<Count:> entry specifies the number of packets to capture.
-Entering 0 will capture packets indefinitely. The I<Filter:> entry lets
-you specify the capture filter using a tcpdump-style filter string as
-described above. The I<File:> entry specifies the file to save to, as
-in the I<Printer Options> dialog above. You can specify the maximum
-number of bytes to capture per packet with the I<Capture length> entry,
-can specify whether the interface is to be put in promiscuous mode or
-not with the I<Capture packets in promiscuous mode> check box, can
-specify that the display should be updated as packets are captured with
-the I<Update list of packets in real time> check box, can specify
-whether in such a capture the packet list pane should scroll to show the
-most recently captured packets with the I<Automatic scrolling in live
+capture packet data or a command from which to get the packet data via a
+pipe.
+
+The I<Count:> entry specifies the maximum number of packets to capture.
+0 means Ethereal will not stop capturing at some fixed number of
+captured packets.
+
+The I<File size:> entry specifies the maximum size of a capture file, in
+kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). 0 means
+Ethereal will not stop capturing at some capture file size (although the
+operating system on which Ethereal is running, or the available disk
+space, may still limit the maximum size of a capture file).
+
+The I<Duration:> entry specifies the maximum time over which to capture,
+in seconds. 0 means Ethereal will not stop capturing after some fixed
+time has elapsed.
+
+The I<Filter:> entry lets you specify the capture filter using a
+tcpdump-style filter string as described above.
+
+The I<File:> entry specifies the file to save to, as in the I<Printer
+Options> dialog above.
+
+You can specify the maximum number of bytes to capture per packet with
+the I<Capture length> entry, can specify whether the interface is to be
+put in promiscuous mode or not with the I<Capture packets in promiscuous
+mode> check box, can specify whether Ethereal should run in "ring
+buffer" mode with the I<Use ring buffer> check box and can specify the
+number of files to use with the I<Number of files> spin box, can specify
+that the display should be updated as packets are captured with the
+I<Update list of packets in real time> check box, can specify whether in
+such a capture the packet list pane should scroll to show the most
+recently captured packets with the I<Automatic scrolling in live
capture> check box, and can specify whether addresses should be
-translated to names in the display with the I<Enable MAC name resolution>,
-I<Enable network name resolution> and I<Enable transport name resolution>
-check boxes.
+translated to names in the display with the I<Enable MAC name
+resolution>, I<Enable network name resolution> and I<Enable transport
+name resolution> check boxes.
=item Display Options
Contributors
------------
- Gilbert Ramirez <gram[AT]xiexie.org>
+ Gilbert Ramirez <gram[AT]alumni.rice.edu>
Hannes R. Boehm <hannes[AT]boehm.org>
Mike Hall <mlh[AT]io.com>
Bobo Rajec <bobo[AT]bsp-consulting.sk>
Randy McEoin <rmceoin[AT]pe.net>
Edgar Iglesias <edgar.iglesias[AT]axis.com>
Martina Obermeier <Martina.Obermeier[AT]icn.siemens.de>
- Mark Burton <markb[AT]ordern.com>
Javier Achirica <achirica[AT]ttd.net>
B. Johannessen <bob[AT]havoq.com>
Thierry Pelle <thierry.pelle[AT]rd.francetelecom.fr>
Terje Krogdahl <tekr[AT]nextra.com>
Jean-Francois Mule <jfmule[AT]clarent.com>
Thomas Wittwer <thomas.wittwer[AT]iclip.ch>
+ Matthias Nyffenegger <matthias.nyffenegger[AT]iclip.ch>
Palle Lyckegaard <Palle[AT]lyckegaard.dk>
Nicolas Balkota <balkota[AT]mac.com>
Tom Uijldert <Tom.Uijldert[AT]cmg.nl>
Shinsuke Suzuki <suz[AT]kame.net>
Andrew C. Feren <aferen[AT]cetacean.com>
Tomas Kukosa <tomas.kukosa[AT]anfdata.cz>
-
<a.stockmeier[AT]avm.de>
+
Andreas Stockmeier <a.stockmeier[AT]avm.de>
Pekka Nikander <pekka.nikander[AT]nomadiclab.com>
+ Hamish Moffatt <hamish[AT]cloud.net.au>
+ Kazushi Sugyo <k-sugyou[AT]nwsl.mesh.ad.jp>
+ Tim Potter <tpot[AT]samba.org>
+ Raghu Angadi <rangadi[AT]inktomi.com>
+ Taisuke Sasaki <sasaki[AT]soft.net.fujitsu.co.jp>
+ Tim Newsham <newsham[AT]lava.net>
+ Tom Nisbet <Tnisbet[AT]VisualNetworks.com>
+ Darren New <dnew[AT]san.rr.com>
+ Pavel Mores <pvl[AT]uh.cz>
+ Bernd Becker <bb[AT]bernd-becker.de>
+ Heinz Prantner <Heinz.Prantner[AT]radisys.com>
+ Irfan Khan <ikhan[AT]qualcomm.com>
+ Jayaram V.R <vjayar[AT]cisco.com>
+ Dinesh Dutt <ddutt[AT]cisco.com>
+ Nagarjuna Venna <nvenna[AT]Brixnet.com>
+ Jirka Novak <j.novak[AT]netsystem.cz>
+ Ricardo Barroetaveña <rbarroetavena[AT]veufort.com>
+ Alan Harrison <alanharrison[AT]mail.com>
Alain Magloire <alainm[AT]rcsm.ece.mcgill.ca> was kind enough to give his
permission to use his version of snprintf.c.
git.samba.org / obnox / wireshark / wip.git / blobdiff