doc/ethereal.pod

   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<-h> ]>
  13 S<[ B<-i> interface ]>
  14 S<[ B<-m> font ]>
  15 S<[ B<-n> ]>
  16 S<[ B<-P> packet list height ]>
  17 S<[ B<-r> infile ]>
  18 S<[ B<-s> snaplen ]>
  19 S<[ B<-T> tree view height ]>
  20 S<[ B<-t> time stamp format ]>
  21 S<[ B<-v> ]>
  22 S<[ B<-w> savefile]>
  23
  24 =head1 DESCRIPTION
  25
  26 B<Ethereal> is a network protocol analyzer based on the B<GTK+> GUI toolkit.  It lets
  27 you interactively browse packet data from a live network or from a B<pcap>
  28 / B<tcpdump()> formatted capture file.
  29
  30 =head1 OPTIONS
  31
  32 =over 4
  33
  34 =item -B
  35
  36 Sets the initial height of the byte view (bottom) pane
  37
  38 =item -b
  39
  40 The bold font name used for packet fied display.
  41
  42 =item -c
  43
  44 The default number of packets to read when capturing live data.
  45
  46 =item -h
  47
  48 Prints the version and options and exits.
  49
  50 =item -i
  51
  52 The name of the interface to use for live packet capture.  It should match
  53 one of the names listed in "B<netstat -i>" or "B<ifconfig -a>".
  54
  55 =item -m
  56
  57 The font name used by B<Ethereal>.
  58
  59 =item -n
  60
  61 Disable network object name resolution (such as hostname, TCP and UDP port
  62 names).
  63
  64 =item -P
  65
  66 Sets the initial height of the packet list (top) pane
  67
  68 =item -r
  69
  70 Read packet data from I<file>.  Currently, B<Ethereal> only understands
  71 B<pcap> / B<tcpdump> formatted files.
  72
  73 =item -s
  74
  75 The default snapshot length to use when capturing live data.  No more than
  76 I<snaplen> bytes of each network packet will be read into memory, or saved
  77 to disk.
  78
  79 =item -T
  80
  81 Sets the initial height of the tree view (top) pane
  82
  83 =item -t
  84
  85 Sets the format of the packet timestamp displayed in the packet list
  86 window.  The format can be one of 'r' (relative), 'a' (absolute), or 'd'
  87 (delta).  The relative time is the time elapsed between the first packet
  88 and the current packet.  The absolute time is the actual date and time the
  89 packet was captured.  The delta time is the time since the previous packet
  90 was captured.  The default is relative.
  91
  92 =item -v
  93
  94 Prints the version and exits.
  95
  96 =item -w
  97
  98 Sets the default capture file name.
  99
 100 =back
 101
 102 =head1 INTERFACE
 103
 104 =head2 MENU ITEMS
 105
 106 =over 4
 107
 108 =item File:Open, File:Close, File:Reload
 109
 110 Open, close, or reload a capture file.
 111
 112 =item File:Print Packet
 113
 114 Print a description of each protocol header found in the packet, followed
 115 by the packet data itself.  Printing options can be set with the
 116 I<Edit:Preferences> menu item.
 117
 118 =item File:Quit
 119
 120 Exits the application.
 121
 122 =item Edit:Preferences
 123
 124 Sets the packet printing and filter options (see L<"Preferences"> below).
 125
 126 =item Tools:Capture
 127
 128 Initiates a live packet capture (see L<"Capture Preferences"> below).
 129 A temporary file will be created to hold the capture. The location of the
 130 file can be chosen by setting your TMPDIR environment variable before
 131 starting ethereal. Otherwise, the default TMPDIR location is system-dependent,
 132 but is likely either /var/tmp or /tmp.
 133
 134 =item Tools:Follow TCP Stream
 135
 136 If you have a TCP packet selected, it will display the contents of the TCP
 137 data stream in a separate window.
 138
 139 =back
 140
 141 =head2 WINDOWS
 142
 143 =over 4
 144
 145 =item Main Window
 146
 147 The main window is split into three panes.  You can resize each pane using
 148 a "thumb" at the right end of each divider line.  Below the panes is a
 149 strip that shows the file load progress, current filter, and informational
 150 text.
 151
 152 The top pane contains the list of network packets that you can scroll
 153 through and select.  The packet number, packet timestamp, source and
 154 destination addresses, protocol, and description are printed for each
 155 packet.  An effort is made to display information as high up the protocol
 156 stack as possible, e.g. IP addresses are displayed for IP packets, but the
 157 MAC layer address is displayed for unknown packet types.
 158
 159 The middle pane contains a I<protocol tree> for the currently-selected
 160 packet.  The tree displays each field and its value in each protocol header
 161 in the stack.
 162
 163 The lowest pane contains a hex dump of the actual packet data.
 164 Selecting a field in the I<protocol tree> highlights the corresponding
 165 bytes in this section.
 166
 167 A display filter can be entered into the strip at the bottom.  It must
 168 have the same format as B<tcpdump> filter strings, since both programs use
 169 the same underlying library.  A filter for HTTP, HTTPS, and DNS traffic
 170 might look like this:
 171
 172   tcp port 80 or tcp port 443 or port 53
 173
 174 Selecting the I<Filter:> button lets you choose from a list of named
 175 filters that you can optionally save.
 176
 177 =item Preferences
 178
 179 The I<Preferences> dialog lets you select the output format of packets
 180 printed using the I<File:Print Packet> menu item and configure
 181 commonly-used filters.
 182
 183 =over 6
 184
 185 =item Printing Preferences
 186
 187 The radio buttons at the top of the I<Printing> page allow you choose
 188 between  printing the packets as text or PostScript, and sending the
 189 output directly to a command or saving it to a file.  The I<Command:> text
 190 entry box is the command to send files to (usually B<lpr>), and the
 191 I<File:> entry box lets you enter the name of the file you wish to save
 192 to.  Additinally, you can select the I<File:> button to browse the file
 193 system for a particular save file.
 194
 195 =item Filter Preferences
 196
 197 The I<Filters> page lets you create and modify filters, and set the
 198 default filter to use when capturing data or opening a capture file.
 199
 200 The I<Filter name> entry specifies a descriptive name for a filter, e.g.
 201 B<Web and DNS traffic>.  The I<Filter string> entry is the text that
 202 actually describes the filtering action to take, as described above.The
 203 dialog buttons perform the following actions:
 204
 205 =over 6
 206
 207 =item New
 208
 209 If there is text in the two entry boxes, it creates a new associated list
 210 item.
 211
 212 =item Change
 213
 214 Modifies the currently selected list item to match what's in the entry
 215 boxes.
 216
 217 =item Copy
 218
 219 Makes a copy of the currently selected list item.
 220
 221 =item Delete
 222
 223 Deletes the currently selected list item.
 224
 225 =item OK
 226
 227 Sets the currently selected list item as the active filter.  If  nothing
 228 is selected, turns filtering off.
 229
 230 =item Save
 231
 232 Saves the current filter list in F<$HOME/.ethereal/filters>.
 233
 234 =item Cancel
 235
 236 Closes the dialog without making any changes.
 237
 238 =back
 239
 240 =item Column Preferences
 241
 242 The I<Columns> page lets you specify the number, title, and format
 243 of each column in the packet list.
 244
 245 The I<Column title> entry is used to specify the title of the column
 246 displayed at the top of the packet list.  The type of data that the column
 247 displays can be specified using the I<Column format> option menu.  The row
 248 of buttons on the left perform the following actions:
 249
 250 =over 6
 251
 252 =item New
 253
 254 Adds a new column to the list.
 255
 256 =item Change
 257
 258 Modifies the currently selected list item.
 259
 260 =item Delete
 261
 262 Deletes the currently selected list item.
 263
 264 =item Up / Down
 265
 266 Moves the selected list item up or down one position.
 267
 268 =item OK
 269
 270 Currently has no effect.
 271
 272 =item Save
 273
 274 Saves the current column format as the default.
 275
 276 =item Cancel
 277
 278 Closes the dialog without making any changes.
 279
 280 =back
 281
 282 =back
 283
 284 =item Capture Preferences
 285
 286 The I<Capture Preferences> dialog lets you specify various parameters for
 287 capturing live packet data.
 288
 289 The I<Interface:> entry box lets you specify the interface from which to
 290 capture packet data.  The I<Count:> entry specifies the number of packets
 291 to capture.  Entering 0 will capture packets indefinitely.  The I<Filter:>
 292 entry lets you specify the capture filter using a tcpdump-style filter
 293 string as described above.  The I<File:> entry specifies the file to save
 294 to, as in the I<Printer Options> dialog above.  You can choose to open the
 295 file after capture, and you can also specify the maximum number of bytes
 296 to capture per packet with the I<Capture length> entry.
 297
 298 =back
 299
 300 =head1 SEE ALSO
 301
 302 L<tcpdump(1)>, L<pcap(3)>
 303
 304 =head1 NOTES
 305
 306 The latest version of B<ethereal> can be found at
 307 B<http://ethereal.zing.org>.
 308
 309 =head1 AUTHORS
 310
 311   Original Author
 312   -------- ------
 313   Gerald Combs  <gerald@zing.org>
 314
 315
 316   Contributors
 317   ------------
 318   Gilbert Ramirez          <gramirez@tivoli.com>
 319   Hannes R. Boehm          <hannes@boehm.org>
 320   Mike Hall                <mlh@io.com>
 321   Bobo Rajec               <bobo@bsp-consulting.sk>
 322   Laurent Deniel           <deniel@worldnet.fr>
 323   Don Lafontaine           <lafont02@cn.ca>
 324   Guy Harris               <guy@netapp.com>
 325   Simon Wilkinson          <sxw@dcs.ed.ac.uk>
 326   Joerg Mayer              <jmayer@telemation.de>
 327   Martin Maciaszek         <fastjack@i-s-o.net>
 328   Didier Jorand            <Didier.Jorand@alcatel.fr>
 329   Jun-ichiro itojun Hagino <itojun@iijlab.net>
 330   Richard Sharpe           <sharpe@ns.aus.com>
 331
 332 Alain Magloire <alainm@rcsm.ece.mcgill.ca> was kind enough to give his
 333 permission to use his version of snprintf.c.
 334
 335 Dan Lasley <dlasley@promus.com> gave permission for his dumpit() hex-dump
 336 routine to be used.