doc/tethereal.pod.template

   1
   2 =head1 NAME
   3
   4 Tethereal - Dump and analyze network traffic
   5
   6 =head1 SYNOPSYS
   7
   8 B<tethereal>
   9 S<[ B<-c> count ]>
  10 S<[ B<-f> filter expression ]>
  11 S<[ B<-F> file format ]>
  12 S<[ B<-h> ]>
  13 S<[ B<-i> interface ]>
  14 S<[ B<-l> ]>
  15 S<[ B<-n> ]>
  16 S<[ B<-o> preference setting ] ...>
  17 S<[ B<-p> ]>
  18 S<[ B<-r> infile ]>
  19 S<[ B<-R> filter expression ]>
  20 S<[ B<-s> snaplen ]>
  21 S<[ B<-t> time stamp format ]>
  22 S<[ B<-v> ]>
  23 S<[ B<-V> ]>
  24 S<[ B<-w> savefile ]>
  25 S<[ B<-x> ]>
  26 S<[ filter expression ]>
  27
  28 =head1 DESCRIPTION
  29
  30 B<Tethereal> is a network protocol analyzer.  It lets you capture packet
  31 data from a live network, or read packets from a previously saved
  32 capture file, either printing a decoded form of those packets to the
  33 standard output or writing the packets to a file.  B<Tethereal> knows
  34 how to read B<libpcap> capture files, including those of B<tcpdump>.  In
  35 addition, B<Tethereal> can read capture files from B<snoop> (including
  36 B<Shomiti>) and B<atmsnoop>, B<LanAlyzer>, B<Sniffer> (compressed or
  37 uncompressed), Microsoft B<Network Monitor>, AIX's B<iptrace>,
  38 B<NetXray>, B<Sniffer Pro>, B<RADCOM>'s WAN/LAN analyzer,
  39 B<Lucent/Ascend> router debug output, HP-UX's B<nettl>, the dump output
  40 from B<Toshiba's> ISDN routers, the output from B<i4btrace> from the
  41 ISDN4BSD project, and output in IPLog format from the Cisco Secure
  42 Intrusion Detection System.  There is no need to tell B<Tethereal> what
  43 type of file you are reading; it will determine the file type by itself.
  44 B<Tethereal> is also capable of reading any of these file formats if
  45 they are compressed using gzip.  B<Tethereal> recognizes this directly
  46 from the file; the '.gz' extension is not required for this purpose.
  47
  48 If the B<-w> flag is not specified, B<Tethereal> prints a decoded form
  49 of the packets it captures or reads; otherwise, it writes those packets
  50 to the file specified by that flag.
  51
  52 When printing a decoded form of packets, B<Tethereal> prints, by
  53 default, a summary line containing the fields specified by the
  54 preferences file (which are also the fields displayed in the packet list
  55 pane in B<Ethereal>), although if it's printing packets as it captures
  56 them, rather than printing packets from a saved capture file, it won't
  57 print the "frame number" field.  If the B<-V> flag is specified, it
  58 prints intead a protocol tree, showing all the fields of all protocols
  59 in the packet.
  60
  61 When writing packets to a file, B<Tethereal>, by default, writes the
  62 file in B<libpcap> format, and writes all of the packets it sees to the
  63 output file.  The B<-F> flag can be used to specify the format in which
  64 to write the file; it can write the file in B<libpcap> format (standard
  65 B<libpcap> format, a modified format used by some patched versions of
  66 B<libpcap>, or the format used by Red Hat Linux 6.1), B<snoop> format,
  67 uncompressed B<Sniffer> format, Microsoft B<Network Monitor> 1.x format,
  68 and the format used by Windows-based versions of the B<Sniffer>
  69 software.
  70
  71 Read filters in B<Tethereal>, which allow you to select which packets
  72 are to be decoded or written to a file, are very powerful; more fields
  73 are filterable in B<Tethereal> than in other protocol analyzers, and the
  74 syntax you can use to create your filters is richer.  As B<Tethereal>
  75 progresses, expect more and more protocol fields to be allowed in read
  76 filters.
  77
  78 Packet capturing is performed with the pcap library.  The capture filter
  79 syntax follows the rules of the pcap library.  This syntax is different
  80 from the read filter syntax.  A read filter can also be specified when
  81 capturing, and only packets that pass the read filter will be displayed
  82 or saved to the output file; note, however, that capture filers are much
  83 more efficient than read filters, and it may be more difficult for
  84 B<Tethereal> to keep up with a busy network if a read filter is
  85 specified for a live capture.
  86
  87 Compressed file support uses (and therefore requires) the zlib library.
  88 If the zlib library is not present, B<Tethereal> will compile, but will
  89 be unable to read compressed files.
  90
  91 A capture or read filter can either be specified with the B<-f> or B<-R>
  92 option, respectively, in which case the entire filter expression must be
  93 specified as a single argument (which means that if it contains spaces,
  94 it must be quoted), or can be specified with command-line arguments
  95 after the option arguments, in which case all the arguments after the
  96 filter arguments are treated as a filter expression.
  97
  98 =head1 OPTIONS
  99
 100 =over 4
 101
 102 =item -c
 103
 104 Sets the default number of packets to read when capturing live
 105 data.
 106
 107 =item -f
 108
 109 Sets the capture filter expression.
 110
 111 =item -F
 112
 113 Sets the file format of the output capture file.
 114
 115 =item -h
 116
 117 Prints the version and options and exits.
 118
 119 =item -i
 120
 121 Sets the name of the network interface to use for live packet capture.
 122 It should match one of the names listed in "B<netstat -i>" or
 123 "B<ifconfig -a>".  If no interface is specified, B<Tethereal> searches
 124 the list of interfaces, choosing the first non-loopback interface if
 125 there are any non-loopback interfaces, and choosing the first loopback
 126 interface if there are no non-loopback interfaces; if there are no
 127 interfaces, B<Tethereal> reports an error and doesn't start the capture.
 128
 129 =item -l
 130
 131 Make the standard output line buffered.  This may be useful when piping
 132 the output of B<Tethereal> to another program, as it means that the
 133 program to which the output is piped will see lines of output as soon as
 134 B<Tethereal> generates those lines, rather than seeing them only when
 135 the standard output buffer containing those lines fills up.
 136
 137 =item -n
 138
 139 Disables network object name resolution (such as hostname, TCP and UDP port
 140 names).
 141
 142 =item -o
 143
 144 Sets a preference value, overriding the default value and any value read
 145 from a preference file.  The argument to the flag is a string of the
 146 form I<prefname>B<:>I<value>, where I<prefname> is the name of the
 147 preference (which is the same name that would appear in the preference
 148 file), and I<value> is the value to which it should be set.
 149
 150 =item -p
 151
 152 I<Don't> put the interface into promiscuous mode.  Note that the
 153 interface might be in promiscuous mode for some other reason; hence,
 154 B<-p> cannot be used to ensure that the only traffic that is captured is
 155 traffic sent to or from the machine on which B<Tethereal> is running,
 156 broadcast traffic, and multicast traffic to addresses received by that
 157 machine.
 158
 159 =item -r
 160
 161 Reads packet data from I<file>.
 162
 163 =item -R
 164
 165 Causes the specified filter (which uses the syntax of read filters,
 166 rather than that of capture filters) to be applied before printing a
 167 decoded form of packets or writing packets to a file; packets not
 168 matching the filter are discarded rather than being printed or written.
 169
 170 =item -s
 171
 172 Sets the default snapshot length to use when capturing live data.
 173 No more than I<snaplen> bytes of each network packet will be read into
 174 memory, or saved to disk.
 175
 176 =item -t
 177
 178 Sets the format of the packet timestamp printed in summary lines.  The
 179 format can be one of 'r' (relative), 'a' (absolute), 'ad' (absolute with
 180 date), or 'd' (delta).  The relative time is the time elapsed between
 181 the first packet and the current packet.  The absolute time is the
 182 actual time the packet was captured, with no date displayed; the
 183 absolute date and time is the actual time and date the packet was
 184 captured.  The delta time is the time since the previous packet was
 185 captured.  The default is relative.
 186
 187 =item -v
 188
 189 Prints the version and exits.
 190
 191 =item -V
 192
 193 Causes B<Tethereal> to print a protocol tree for each packet rather than
 194 a one-line summary of the packet.
 195
 196 =item -w
 197
 198 Writes packet data to I<savefile>.
 199
 200 =item -x
 201
 202 Causes B<Tethereal> to print a hex and ASCII dump of the packet data
 203 after printing the summary or protocol tree.
 204
 205 =back
 206
 207 =head1 CAPTURE FILTER SYNTAX
 208
 209 See manual page of tcpdump(8).
 210
 211 =head1 READ FILTER SYNTAX
 212
 213 Read filters help you remove the noise from a packet trace and let you
 214 see only the packets that interest you.  If a packet meets the
 215 requirements expressed in your read filter, then it is printed.  Read
 216 filters let you compare the fields within a protocol against a specific
 217 value, compare fields against fields, and to check the existence of
 218 specified fields or protocols.
 219
 220 The simplest read filter allows you to check for the existence of a
 221 protocol or field.  If you want to see all packets which contain the IPX
 222 protocol, the filter would be "ipx".  (Without the quotation marks) To
 223 see all packets that contain a Token-Ring RIF field, use "tr.rif".
 224
 225 Fields can also be compared against values.  The comparison operators
 226 can be expressed either through C-like symbols, or through English-like
 227 abbreviations:
 228
 229     eq, ==    Equal
 230     ne, !=    Not equal
 231     gt, >     Greater than
 232     lt, <     Less Than
 233     ge, >=    Greater than or Equal to
 234     le, <=    Less than or Equal to
 235
 236 Furthermore, each protocol field is typed. The types are:
 237
 238     Unsigned integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
 239     Signed integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
 240     Boolean
 241     Ethernet address (6 bytes)
 242     Byte string (n-number of bytes)
 243     IPv4 address
 244     IPv6 address
 245     IPX network number
 246     String (text)
 247     Double-precision floating point number
 248
 249 An integer may be expressed in decimal, octal, or hexadecimal notation.
 250 The following three read filters are equivalent:
 251
 252     frame.pkt_len > 10
 253     frame.pkt_len > 012
 254     frame.pkt_len > 0xa
 255
 256 Boolean values are either true or false.  However, a boolean field is
 257 present in a protocol decode only if its value is true.  If the value is
 258 false, the field is not presence.  You can therefore check the truth
 259 value of a boolean field by simply checking for its existence, that is,
 260 by naming the field.  For example, a token-ring packet's source route
 261 field is boolean.  To find any source-routed packets, the read filter
 262 is simply:
 263
 264     tr.sr
 265
 266 Non source-routed packets can be found with the negation of that filter:
 267
 268     ! tr.sr
 269
 270 Ethernet addresses, as well as a string of bytes, are represented in hex
 271 digits.  The hex digits may be separated by colons, periods, or hyphens:
 272
 273     fddi.dst eq ff:ff:ff:ff:ff:ff
 274     ipx.srcnode == 0.0.0.0.0.1
 275     eth.src == aa-aa-aa-aa-aa-aa
 276
 277 If a string of bytes contains only one byte, then it is represented as
 278 an unsigned integer.  That is, if you are testing for hex value 'ff' in
 279 a one-byte byte-string, you must compare it agains '0xff' and not 'ff'.
 280
 281 IPv4 addresses can be represented in either dotted decimal notation, or
 282 by using the hostname:
 283
 284     ip.dst eq www.mit.edu
 285     ip.src == 192.168.1.1
 286
 287 IPv4 address can be compared with the same logical relations as numbers:
 288 eq, ne, gt, ge, lt, and le.  The IPv4 address is stored in host order,
 289 so you do not have to worry about how the endianness of an IPv4 address
 290 when using it in a read filter.
 291
 292 Classless InterDomain Routing (CIDR) notation can be used to test if an
 293 IPv4 address is in a certain subnet.  For example, this read filter
 294 will find all packets in the 129.111 Class-B network:
 295
 296     ip.addr == 129.111.0.0/16
 297
 298 Remember, the number after the slash represents the number of bits used
 299 to represent the network.  CIDR notation can also be used with
 300 hostnames, in this example of finding IP addresses on the same Class C
 301 network as 'sneezy':
 302
 303     ip.addr eq sneezy/24
 304
 305 The CIDR notation can only be used on IP addresses or hostnames, not in
 306 variable names.  So, a read filter like "ip.src/24 == ip.dst/24" is
 307 not valid.  (yet)
 308
 309 IPX networks are represented by unsigned 32-bit integers.  Most likely
 310 you will be using hexadecimal when testing for IPX network values:
 311
 312     ipx.srcnet == 0xc0a82c00
 313
 314 A substring operator also exists.  You can check the substring
 315 (byte-string) of any protocol or field.  For example, you can filter on
 316 the vendor portion of an ethernet address (the first three bytes) like
 317 this:
 318
 319     eth.src[0:3] == 00:00:83
 320
 321 Or more simply, since the number of bytes is inherent in the byte-string
 322 you provide, you can provide just the offset.  The previous example can
 323 be stated like this:
 324
 325     eth.src[0] == 00:00:83
 326
 327 In fact, the only time you need to explicitly provide a length is when
 328 you don't provide a byte-string, and are comparing fields against
 329 fields:
 330
 331     fddi.src[0:3] == fddi.dst[0:3]
 332
 333 If the length of your byte-string is only one byte, then it must be
 334 represented in the same way as an unsigned 8-bit integer:
 335
 336     llc[3] == 0xaa
 337
 338 You can use the substring operator on a protocol name, too.  And
 339 remember, the "frame" protocol encompasses the entire packet, allowing
 340 you to look at the nth byte of a packet regardless of its frame type
 341 (Ethernet, token-ring, etc.).
 342
 343     token[0:5] ne 0.0.0.1.1
 344     ipx[0:2] == ff:ff
 345     llc[3:1] eq 0xaa
 346
 347 Offsets for byte-strings can also be negative, in which case the
 348 negative number indicates the number of bytes from the end of the field
 349 or protocol that you are testing.  Here's how to check the last 4 bytes
 350 of a frame:
 351
 352     frame[-4] == 0.1.2.3
 353
 354 or
 355
 356     frame[-4:4] == 0.1.2.3
 357
 358 All the above tests can be combined together with logical expressions.
 359 These too are expressable in C-like syntax or with English-like
 360 abbreviations:
 361
 362     and, &&   Logical AND
 363     or, ||    Logical OR
 364     xor, ^^   Logical XOR
 365     not, !    Logical NOT
 366
 367 Expressions can be grouped by parentheses as well.  The following are
 368 all valid read filter expression:
 369
 370     tcp.port == 80 and ip.src == 192.168.2.1
 371     not llc
 372     (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
 373     tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
 374
 375 A special caveat must be given regarding fields that occur more than
 376 once per packet.  "ip.addr" occurs twice per IP packet, once for the
 377 source address, and once for the destination address.  Likewise,
 378 tr.rif.ring fields can occur more than once per packet.  The following
 379 two expressions are not equivalent:
 380
 381         ip.addr ne 192.168.4.1
 382     not ip.addr eq 192.168.4.1
 383
 384 The first filter says "show me all packets where an ip.addr exists that
 385 does not equal 192.168.4.1".  That is, as long as one ip.addr in the
 386 packet does not equal 192.168.44.1, the packet passes the display
 387 filter.  The second filter "don't show me any packets that have at least
 388 one ip.addr field equal to 192.168.4.1".  If one ip.addr is 192.168.4.1,
 389 the packet does not pass.  If B<neither> ip.addr fields is 192.168.4.1,
 390 then the packet passes.
 391
 392 It is easy to think of the 'ne' and 'eq' operators as having an implict
 393 "exists" modifier when dealing with multiply-recurring fields.  "ip.addr
 394 ne 192.168.4.1" can be thought of as "there exists an ip.addr that does
 395 not equal 192.168.4.1".
 396
 397 Be careful with multiply-recurring fields; they can be confusing.
 398
 399 The following is a table of protocol and protocol fields that are
 400 filterable in B<Tethereal>.  The abbreviation of the protocol or field is
 401 given.  This abbreviation is what you use in the read filter.  The
 402 type of the field is also given.
 403
 404 =insert_dfilter_table
 405
 406 =head1 FILES
 407
 408 F</usr/local/etc/ethereal.conf> and F<$HOME/.ethereal/preferences>
 409 contain system-wide and personal preference settings, respectively.  The
 410 file contains preference settings of the form I<prefname>B<:>I<value>,
 411 one per line, where I<prefname> is the name of the preference (which is
 412 the same name that would appear in the preference file), and I<value> is
 413 the value to which it should be set; white space is allowed between B<:>
 414 and I<value>.  A preference setting can be continued on subsequent lines
 415 by indenting the continuation lines with white space.  A B<#> character
 416 starts a comment that runs to the end of the line.
 417
 418 The system-wide preference file is read first, if it exists, overriding
 419 B<Tethereal>'s default values; the personal preferences file is then
 420 read, if it exists, overriding default values and values read from the
 421 system-wide preference file.
 422
 423 F</etc/ethers> is consulted to correlate 6-byte hardware addresses to
 424 names.  If an address is not found in F</etc/ethers>, the
 425 F<$HOME/.ethereal/ethers> file is consulted next.  Each line contains
 426 one hardware address and name, separated by whitespace.  The digits of
 427 the hardware address are separated by either a colon (:), a dash (-), or
 428 a period (.).  The following three lines are valid lines of an ethers
 429 file:
 430
 431   ff:ff:ff:ff:ff:ff          Broadcast
 432   c0-00-ff-ff-ff-ff          TR_broadcast
 433   00.00.00.00.00.00          Zero_broadcast
 434
 435 F</usr/local/etc/manuf> matches the 3-byte vendor portion of a 6-byte
 436 hardware address with the manufacturer's name.  The format of the file
 437 is the same as the F</etc/ethers> file, except that each address is
 438 three bytes instead of six.
 439
 440 F</etc/ipxnets> and F<$HOME/.ethereal/ipxnets> correlate 4-byte IPX
 441 network numbers to names.  The format is the same as the F</etc/ethers>
 442 file, except that each address if four bytes instead of six.
 443 Additionally, the address can be represented a single hexadecimal
 444 number, as is more common in the IPX world, rather than four hex octets.
 445 For example, these four lines are valid lines of an ipxnets file.
 446
 447   C0.A8.2C.00              HR
 448   c0-a8-1c-00              CEO
 449   00:00:BE:EF              IT_Server1
 450   110f                     FileServer3
 451
 452 =head1 SEE ALSO
 453
 454 L<ethereal(1)>, L<tcpdump(8)>, L<pcap(3)>
 455
 456 =head1 NOTES
 457
 458 B<Tethereal> is part of the B<Ethereal> distribution.  The latest version
 459 of B<Ethereal> can be found at B<http://www.ethereal.com>.
 460
 461 =head1 AUTHORS
 462
 463 B<Tethereal> uses the same packet dissection code that B<Ethereal> does,
 464 as well as using many other modules from B<Ethereal>; see the list of
 465 authors in the B<Ethereal> man page for a list of authors of that code.