doc/ethereal.pod.template

   1
   2 =head1 NAME
   3
   4 Ethereal - Interactively browse network traffic
   5
   6 =head1 SYNOPSYS
   7
   8 B<ethereal>
   9 S<[ B<-B> byte view height ]>
  10 S<[ B<-b> bold font ]>
  11 S<[ B<-c> count ]>
  12 S<[ B<-F> ]>
  13 S<[ B<-f> filter expression ]>
  14 S<[ B<-G> ]>
  15 S<[ B<-h> ]>
  16 S<[ B<-i> interface ]>
  17 S<[ B<-k> ]>
  18 S<[ B<-m> font ]>
  19 S<[ B<-n> ]>
  20 S<[ B<-P> packet list height ]>
  21 S<[ B<-Q> ]>
  22 S<[ B<-r> infile ]>
  23 S<[ B<-S> ]>
  24 S<[ B<-s> snaplen ]>
  25 S<[ B<-T> tree view height ]>
  26 S<[ B<-t> time stamp format ]>
  27 S<[ B<-v> ]>
  28 S<[ B<-w> savefile]>
  29
  30 =head1 DESCRIPTION
  31
  32 B<Ethereal> is a network protocol analyzer based on the B<GTK+> GUI toolkit.  It lets
  33 you interactively browse packet data from a live network or from a previously saved
  34 capture file. Ethereal knows how to read B<pcap> / B<tcpdump> formatted capture files,
  35 as well as those of B<snoop>, B<LanAlyzer>, uncompressed B<Sniffer>,
  36 Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>, and B<Sniffer Pro>.
  37
  38 =head1 OPTIONS
  39
  40 =over 4
  41
  42 =item -B
  43
  44 Sets the initial height of the byte view (bottom) pane.
  45
  46 =item -b
  47
  48 Sets the name of the bold font used for the data in the byte view
  49 pane that corresponds to the field selected in the protocol tree pane.
  50
  51 =item -c
  52
  53 Sets the default number of packets to read when capturing live
  54 data.
  55
  56 =item -F
  57
  58 Specifies that the live packet capture will be performed in a separate
  59 process. It is then possible to open/reload the file to display the
  60 packets actually captured.
  61
  62 =item -f
  63
  64 Sets the capture filter expression.
  65
  66 =item -G
  67
  68 Dumps a glossary of display filter keywords to stdout and exits.
  69
  70 =item -h
  71
  72 Prints the version and options and exits.
  73
  74 =item -i
  75
  76 Sets the name of the interface to use for live packet capture.  It
  77 should match one of the names listed in "B<netstat -i>" or "B<ifconfig -a>".
  78
  79 =item -k
  80
  81 Starts the capture session immediately; this option requires
  82 the B<-i> and B<-w> parameters.
  83
  84 =item -m
  85
  86 Sets the name of the font used by B<Ethereal> for most text.
  87
  88 =item -n
  89
  90 Disables network object name resolution (such as hostname, TCP and UDP port
  91 names).
  92
  93 =item -P
  94
  95 Sets the initial height of the packet list (top) pane.
  96
  97 =item -Q
  98
  99 Causes B<Ethereal> to exit after the end of capture session (useful in
 100 batch mode with B<-c> option for instance); this option requires the
 101 B<-i> and B<-w> parameters.
 102
 103 =item -r
 104
 105 Reads packet data from I<file>.
 106
 107 =item -S
 108
 109 Specifies that the live packet capture will be performed in a separate
 110 process (same as option B<-F>) and that the packet displaying should be
 111 synchronized with the capture session without human operation
 112 (i.e. without load/reload). This is an experimental feature.
 113
 114 =item -s
 115
 116 Sets the default snapshot length to use when capturing live data.
 117 No more than I<snaplen> bytes of each network packet will be read into
 118 memory, or saved to disk.
 119
 120 =item -T
 121
 122 Sets the initial height of the tree view (middle) pane
 123
 124 =item -t
 125
 126 Sets the format of the packet timestamp displayed in the packet list
 127 window.  The format can be one of 'r' (relative), 'a' (absolute), or 'd'
 128 (delta).  The relative time is the time elapsed between the first packet
 129 and the current packet.  The absolute time is the actual date and time the
 130 packet was captured.  The delta time is the time since the previous packet
 131 was captured.  The default is relative.
 132
 133 =item -v
 134
 135 Prints the version and exits.
 136
 137 =item -w
 138
 139 Sets the default capture file name.
 140
 141 =back
 142
 143 =head1 INTERFACE
 144
 145 =head2 MENU ITEMS
 146
 147 =over 4
 148
 149 =item File:Open, File:Close, File:Reload
 150
 151 Open, close, or reload a capture file.
 152
 153 =item File:Print
 154
 155 Prints, for all the packets in the current capture, the packet number,
 156 followed by  a description of each protocol header found in the packet,
 157 followed by the packet data itself.  Printing options can be set with the
 158 I<Edit:Preferences> menu item, or in the dialog box popped up by this
 159 item.
 160
 161 =item File:Print Packet
 162
 163 Print a description of each protocol header found in the packet, followed
 164 by the packet data itself.  Printing options can be set with the
 165 I<Edit:Preferences> menu item.
 166
 167 =item File:Quit
 168
 169 Exits the application.
 170
 171 =item Edit:Preferences
 172
 173 Sets the packet printing and filter options (see L<"Preferences"> below).
 174
 175 =item Capture:Start
 176
 177 Initiates a live packet capture (see L<"Capture Preferences"> below).
 178 A temporary file will be created to hold the capture. The location of the
 179 file can be chosen by setting your TMPDIR environment variable before
 180 starting ethereal. Otherwise, the default TMPDIR location is system-dependent,
 181 but is likely either /var/tmp or /tmp.
 182
 183 =item Display:Options
 184
 185 Sets the format of the packet timestamp displayed in the packet list
 186 window to relative, absolute, or delta.
 187
 188 =item Tools:Follow TCP Stream
 189
 190 If you have a TCP packet selected, it will display the contents of the TCP
 191 data stream in a separate window.
 192
 193 =back
 194
 195 =head2 WINDOWS
 196
 197 =over 4
 198
 199 =item Main Window
 200
 201 The main window is split into three panes.  You can resize each pane using
 202 a "thumb" at the right end of each divider line.  Below the panes is a
 203 strip that shows the file load progress, current filter, and informational
 204 text.
 205
 206 The top pane contains the list of network packets that you can scroll
 207 through and select.  The packet number, packet timestamp, source and
 208 destination addresses, protocol, and description are printed for each
 209 packet.  An effort is made to display information as high up the protocol
 210 stack as possible, e.g. IP addresses are displayed for IP packets, but the
 211 MAC layer address is displayed for unknown packet types.
 212
 213 The middle pane contains a I<protocol tree> for the currently-selected
 214 packet.  The tree displays each field and its value in each protocol header
 215 in the stack.
 216
 217 The lowest pane contains a hex dump of the actual packet data.
 218 Selecting a field in the I<protocol tree> highlights the corresponding
 219 bytes in this section.
 220
 221 A display filter can be entered into the strip at the bottom.
 222 A filter for HTTP, HTTPS, and DNS traffic might look like this:
 223
 224   tcp.port == 80 || tcp.port == 443 || tcp.port == 53
 225
 226 Selecting the I<Filter:> button lets you choose from a list of named
 227 filters that you can optionally save.  Pressing the Return or Enter
 228 keys will cause the filter to be applied to the current list of packets.
 229
 230 =item Preferences
 231
 232 The I<Preferences> dialog lets you select the output format of packets
 233 printed using the I<File:Print Packet> menu item and configure
 234 commonly-used filters.
 235
 236 =over 6
 237
 238 =item Printing Preferences
 239
 240 The radio buttons at the top of the I<Printing> page allow you choose
 241 between  printing the packets as text or PostScript, and sending the
 242 output directly to a command or saving it to a file.  The I<Command:> text
 243 entry box is the command to send files to (usually B<lpr>), and the
 244 I<File:> entry box lets you enter the name of the file you wish to save
 245 to.  Additinally, you can select the I<File:> button to browse the file
 246 system for a particular save file.
 247
 248 =item Filter Preferences
 249
 250 The I<Filters> page lets you create and modify filters, and set the
 251 default filter to use when capturing data or opening a capture file.
 252
 253 The I<Filter name> entry specifies a descriptive name for a filter, e.g.
 254 B<Web and DNS traffic>.  The I<Filter string> entry is the text that
 255 actually describes the filtering action to take, as described above.The
 256 dialog buttons perform the following actions:
 257
 258 =over 6
 259
 260 =item New
 261
 262 If there is text in the two entry boxes, it creates a new associated list
 263 item.
 264
 265 =item Change
 266
 267 Modifies the currently selected list item to match what's in the entry
 268 boxes.
 269
 270 =item Copy
 271
 272 Makes a copy of the currently selected list item.
 273
 274 =item Delete
 275
 276 Deletes the currently selected list item.
 277
 278 =item OK
 279
 280 Sets the currently selected list item as the active filter.  If  nothing
 281 is selected, turns filtering off.
 282
 283 =item Save
 284
 285 Saves the current filter list in F<$HOME/.ethereal/filters>.
 286
 287 =item Cancel
 288
 289 Closes the dialog without making any changes.
 290
 291 =back
 292
 293 =item Column Preferences
 294
 295 The I<Columns> page lets you specify the number, title, and format
 296 of each column in the packet list.
 297
 298 The I<Column title> entry is used to specify the title of the column
 299 displayed at the top of the packet list.  The type of data that the column
 300 displays can be specified using the I<Column format> option menu.  The row
 301 of buttons on the left perform the following actions:
 302
 303 =over 6
 304
 305 =item New
 306
 307 Adds a new column to the list.
 308
 309 =item Change
 310
 311 Modifies the currently selected list item.
 312
 313 =item Delete
 314
 315 Deletes the currently selected list item.
 316
 317 =item Up / Down
 318
 319 Moves the selected list item up or down one position.
 320
 321 =item OK
 322
 323 Currently has no effect.
 324
 325 =item Save
 326
 327 Saves the current column format as the default.
 328
 329 =item Cancel
 330
 331 Closes the dialog without making any changes.
 332
 333 =back
 334
 335 =back
 336
 337 =item Capture Preferences
 338
 339 The I<Capture Preferences> dialog lets you specify various parameters for
 340 capturing live packet data.
 341
 342 The I<Interface:> entry box lets you specify the interface from which to
 343 capture packet data.  The I<Count:> entry specifies the number of packets
 344 to capture.  Entering 0 will capture packets indefinitely.  The I<Filter:>
 345 entry lets you specify the capture filter using a tcpdump-style filter
 346 string as described above.  The I<File:> entry specifies the file to save
 347 to, as in the I<Printer Options> dialog above.  You can choose to open the
 348 file after capture, and you can also specify the maximum number of bytes
 349 to capture per packet with the I<Capture length> entry.
 350
 351 =item Display Options
 352
 353 The I<Display Options> dialog lets you specify the format of the time stamp
 354 in the packet list.  You can select "Time of day" for absolute time stamps,
 355 "Seconds since beginning of capture" for relative time stamps, or
 356 "Seconds since previous frame" for delta time stamps.
 357
 358 =back
 359
 360 =head1 DISPLAY FILTER SYNTAX
 361
 362 The grammar used for B<Ethereal>'s display filter syntax is similar to
 363 the syntax of the C programming language.
 364
 365 =insert_dfilter_table
 366
 367 =head1 SEE ALSO
 368
 369 L<tcpdump(1)>, L<pcap(3)>
 370
 371 =head1 NOTES
 372
 373 The latest version of B<ethereal> can be found at
 374 B<http://ethereal.zing.org>.
 375
 376 =head1 AUTHORS
 377
 378   Original Author
 379   -------- ------
 380   Gerald Combs  <gerald@zing.org>
 381
 382
 383   Contributors
 384   ------------
 385   Gilbert Ramirez          <gramirez@tivoli.com>
 386   Hannes R. Boehm          <hannes@boehm.org>
 387   Mike Hall                <mlh@io.com>
 388   Bobo Rajec               <bobo@bsp-consulting.sk>
 389   Laurent Deniel           <deniel@worldnet.fr>
 390   Don Lafontaine           <lafont02@cn.ca>
 391   Guy Harris               <guy@netapp.com>
 392   Simon Wilkinson          <sxw@dcs.ed.ac.uk>
 393   Joerg Mayer              <jmayer@telemation.de>
 394   Martin Maciaszek         <fastjack@i-s-o.net>
 395   Didier Jorand            <Didier.Jorand@alcatel.fr>
 396   Jun-ichiro itojun Hagino <itojun@iijlab.net>
 397   Richard Sharpe           <sharpe@ns.aus.com>
 398   John McDermott           <jjm@jkintl.com>
 399   Jeff Jahr                <jjahr@shastanets.com>
 400   Brad Robel-Forrest       <bradr@watchguard.com>
 401   Ashok Narayanan          <ashokn@cisco.com>
 402   Aaron Hillegass          <aaron@classmax.com>
 403   Jason Lango              <jal@netapp.com>
 404   Johan Feyaerts           <Johan.Feyaerts@siemens.atea.be>
 405   Olivier Abad             <abad@daba.dhis.org>
 406   Thierry Andry            <Thierry.Andry@advalvas.be>
 407
 408 Alain Magloire <alainm@rcsm.ece.mcgill.ca> was kind enough to give his
 409 permission to use his version of snprintf.c.
 410
 411 Dan Lasley <dlasley@promus.com> gave permission for his dumpit() hex-dump
 412 routine to be used.
 413