winpcap/dox/language.htm

   1 <html>
   2
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
   5 <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
   6 <meta name="ProgId" content="FrontPage.Editor.Document">
   7 <title></title>
   8 </head>
   9
  10 <body>
  11 <DL COMPACT>
  12 <DT>Note: this document has been drawn from the tcpdump man page. The original version can
  13   be found at&nbsp; <a href="http://www.tcpdump.org">www.tcpdump.org</a>.
  14 <dd>&nbsp;</dd>
  15 <DT>wpcap filters are based on a declarative predicate syntax. A filter is
  16   an ASCII string containing a filtering <I>expression</I>.&nbsp;pcap_compile()
  17   takes the expression and translates it in a program for the kernel-level
  18   packet filter.
  19 </DL>
  20 <p>The expression selects which packets will be dumped.
  21 If no expression
  22 is given, all packets on the net will be accepted by the kernel-level filtering
  23 engine.
  24 Otherwise,
  25 only packets for which <I>expression</I> is `true' will be accepted.</p>
  26 <P>
  27
  28 The <I>expression</I> consists of one or more
  29 <I>primitives.</I>
  30
  31 Primitives usually consist of an
  32 <I>id</I>
  33
  34 (name or number) preceded by one or more qualifiers.
  35 There are three
  36 different kinds of qualifier:
  37 <DL COMPACT>
  38 <DT><I>type</I><DD>
  39 qualifiers say what kind of thing the id name or number refers to.
  40 Possible types are
  41 <B>host</B>,
  42
  43 <B>net</B>
  44
  45 and
  46 <B>port</B>.
  47
  48 E.g., `host foo', `net 128.3', `port 20'.
  49 If there is no type
  50 qualifier,
  51 <B>host</B>
  52
  53 is assumed.
  54 <DT><I>dir</I><DD>
  55 qualifiers specify a particular transfer direction to and/or from
  56 <I>id</I>.
  57
  58 Possible directions are
  59 <B>src</B>,
  60
  61 <B>dst</B>,
  62
  63 <B>src or dst</B>
  64
  65 and
  66 <B>src and</B>
  67
  68 <B>dst</B>.
  69
  70 E.g., `src foo', `dst net 128.3', `src or dst port ftp-data'.
  71 If
  72 there is no dir qualifier,
  73 <B>src or dst</B>
  74
  75 is assumed.
  76 For `null' link layers (i.e. point to point protocols such as slip) the
  77 <B>inbound</B>
  78
  79 and
  80 <B>outbound</B>
  81
  82 qualifiers can be used to specify a desired direction.
  83 <DT><I>proto</I><DD>
  84 qualifiers restrict the match to a particular protocol.
  85 Possible
  86 protos are:
  87 <B>ether</B>,
  88
  89 <B>fddi</B>,
  90
  91 <B>tr</B>,
  92
  93 <B>ip</B>,
  94
  95 <B>ip6</B>,
  96
  97 <B>arp</B>,
  98
  99 <B>rarp</B>,
 100
 101 <B>decnet</B>,
 102
 103 <B>tcp</B>
 104
 105 and
 106 <B>udp</B>.
 107
 108 E.g., `ether src foo', `arp net 128.3', `tcp port 21'.
 109 If there is
 110 no proto qualifier, all protocols consistent with the type are
 111 assumed.
 112 E.g., `src foo' means `(ip or arp or rarp) src foo'
 113 (except the latter is not legal syntax), `net bar' means `(ip or
 114 arp or rarp) net bar' and `port 53' means `(tcp or udp) port 53'.
 115 </DL>
 116 <P>
 117
 118 [`fddi' is actually an alias for `ether'; the parser treats them
 119 identically as meaning ``the data link level used on the specified
 120 network interface.''  FDDI headers contain Ethernet-like source
 121 and destination addresses, and often contain Ethernet-like packet
 122 types, so you can filter on these FDDI fields just as with the
 123 analogous Ethernet fields.
 124 FDDI headers also contain other fields,
 125 but you cannot name them explicitly in a filter expression.
 126 <P>
 127
 128 Similarly, `tr' is an alias for `ether'; the previous paragraph's
 129 statements about FDDI headers also apply to Token Ring headers.]
 130 <P>
 131
 132 In addition to the above, there are some special `primitive' keywords
 133 that don't follow the pattern:
 134 <B>gateway</B>,
 135
 136 <B>broadcast</B>,
 137
 138 <B>less</B>,
 139
 140 <B>greater</B>
 141
 142 and arithmetic expressions.
 143 All of these are described below.
 144 <P>
 145
 146 More complex filter expressions are built up by using the words
 147 <B>and</B>,
 148
 149 <B>or</B>
 150
 151 and
 152 <B>not</B>
 153
 154 to combine primitives.
 155 E.g., `host foo and not port ftp and not port ftp-data'.
 156 To save typing, identical qualifier lists can be omitted.
 157 E.g.,
 158 `tcp dst port ftp or ftp-data or domain' is exactly the same as
 159 `tcp dst port ftp or tcp dst port ftp-data or tcp dst port domain'.
 160 <P>
 161
 162 Allowable primitives are:
 163 <DL COMPACT>
 164 <DT><B>dst host </B><I>host</I><DD>
 165 True if the IPv4/v6 destination field of the packet is <I>host</I>,
 166 which may be either an address or a name.
 167 <DT><B>src host </B><I>host</I><DD>
 168 True if the IPv4/v6 source field of the packet is <I>host</I>.
 169 <DT><B>host </B><I>host</I><DD>
 170 True if either the IPv4/v6 source or destination of the packet is <I>host</I>.
 171 Any of the above host expressions can be prepended with the keywords,
 172 <B>ip</B>, <B>arp</B>, <B>rarp</B>, or <B>ip6</B> as in:
 173 <dl COMPACT>
 174   <dd>
 175
 176 <PRE><B>ip host </B><I>host</I></PRE>
 177
 178
 179   </dd>
 180 </dl>
 181
 182
 183 which is equivalent to:
 184 <dl COMPACT>
 185   <dd>
 186
 187 <PRE><B>ether proto </B><I>\ip</I><B> and host </B><I>host</I></PRE>
 188
 189
 190   </dd>
 191 </dl>
 192
 193
 194 If <I>host</I> is a name with multiple IP addresses, each address will
 195 be checked for a match.
 196 <DT><B>ether dst </B><I>ehost</I><DD>
 197 True if the ethernet destination address is <I>ehost</I>.
 198 <I>Ehost</I>
 199 may be either a name from /etc/ethers or a number (see
 200 <I>ethers</I>(3N)
 201
 202 for numeric format).
 203 <DT><B>ether src </B><I>ehost</I><DD>
 204 True if the ethernet source address is <I>ehost</I>.
 205 <DT><B>ether host </B><I>ehost</I><DD>
 206 True if either the ethernet source or destination address is <I>ehost</I>.
 207 <DT><B>gateway</B> <I>host</I><DD>
 208 True if the packet used <I>host</I> as a gateway.
 209 I.e., the ethernet
 210 source or destination address was <I>host</I> but neither the IP source
 211 nor the IP destination was <I>host</I>.
 212 <I>Host</I> must be a name and
 213 must be found both by the machine's host-name-to-IP-address resolution
 214 mechanisms (host name file, DNS, NIS, etc.) and by the machine's
 215 host-name-to-Ethernet-address resolution mechanism (/etc/ethers, etc.).
 216 (An equivalent expression is
 217 <dl COMPACT>
 218   <dd>
 219
 220 <PRE><B>ether host </B><I>ehost </I><B>and not host </B><I>host</I></PRE>
 221
 222
 223   </dd>
 224 </dl>
 225
 226
 227 which can be used with either names or numbers for <I>host / ehost</I>.)
 228 This syntax does not work in IPv6-enabled configuration at this moment.
 229 <DT><B>dst net </B><I>net</I><DD>
 230 True if the IPv4/v6 destination address of the packet has a network
 231 number of <I>net</I>.
 232 <I>Net</I> may be either a name from /etc/networks
 233 or a network number (see <I>networks(4)</I> for details).
 234 <DT><B>src net </B><I>net</I><DD>
 235 True if the IPv4/v6 source address of the packet has a network
 236 number of <I>net</I>.
 237 <DT><B>net </B><I>net</I><DD>
 238 True if either the IPv4/v6 source or destination address of the packet has a network
 239 number of <I>net</I>.
 240 <DT><B>net </B><I>net</I> <B>mask </B><I>netmask</I><DD>
 241 True if the IP address matches <I>net</I> with the specific <I>netmask</I>.
 242 May be qualified with <B>src</B> or <B>dst</B>.
 243 Note that this syntax is not valid for IPv6 <I>net</I>.
 244 <DT><B>net </B><I>net</I>/<I>len</I><DD>
 245 True if the IPv4/v6 address matches <I>net</I> with a netmask <I>len</I>
 246 bits wide.
 247 May be qualified with <B>src</B> or <B>dst</B>.
 248 <DT><B>dst port </B><I>port</I><DD>
 249 True if the packet is ip/tcp, ip/udp, ip6/tcp or ip6/udp and has a
 250 destination port value of <I>port</I>.
 251 The <I>port</I> can be a number or a name used in /etc/services (see
 252 <I>tcp</I>(4P)
 253
 254 and
 255 <I>udp</I>(4P)).
 256
 257 If a name is used, both the port
 258 number and protocol are checked.
 259 If a number or ambiguous name is used,
 260 only the port number is checked (e.g., <B>dst port 513</B> will print both
 261 tcp/login traffic and udp/who traffic, and <B>port domain</B> will print
 262 both tcp/domain and udp/domain traffic).
 263 <DT><B>src port </B><I>port</I><DD>
 264 True if the packet has a source port value of <I>port</I>.
 265 <DT><B>port </B><I>port</I><DD>
 266 True if either the source or destination port of the packet is <I>port</I>.
 267 Any of the above port expressions can be prepended with the keywords,
 268 <B>tcp</B> or <B>udp</B>, as in:
 269 <dl COMPACT>
 270   <dd>
 271
 272 <PRE><B>tcp src port </B><I>port</I></PRE>
 273
 274
 275   </dd>
 276 </dl>
 277
 278
 279 which matches only tcp packets whose source port is <I>port</I>.
 280 <DT><B>less </B><I>length</I><DD>
 281 True if the packet has a length less than or equal to <I>length</I>.
 282 This is equivalent to:
 283 <dl COMPACT>
 284   <dd>
 285
 286 <PRE><B>len &lt;= </B><I>length</I>.</PRE>
 287
 288
 289   </dd>
 290 </dl>
 291
 292
 293 <DT><B>greater </B><I>length</I><DD>
 294 True if the packet has a length greater than or equal to <I>length</I>.
 295 This is equivalent to:
 296 <dl COMPACT>
 297   <dd>
 298
 299 <PRE><B>len &gt;= </B><I>length</I>.</PRE>
 300
 301
 302   </dd>
 303 </dl>
 304
 305
 306 <DT><B>ip proto </B><I>protocol</I><DD>
 307 True if the packet is an IP packet (see
 308 <I>ip</I>(4P))
 309
 310 of protocol type <I>protocol</I>.
 311 <I>Protocol</I> can be a number or one of the names
 312 <I>icmp</I>, <I>icmp6</I>, <I>igmp</I>, <I>igrp</I>, <I>pim</I>, <I>ah</I>,
 313 <I>esp</I>, <I>vrrp</I>, <I>udp</I>, or <I>tcp</I>.
 314 Note that the identifiers <I>tcp</I>, <I>udp</I>, and <I>icmp</I> are also
 315 keywords and must be escaped via backslash (\), which is \\ in the C-shell.
 316 Note that this primitive does not chase the protocol header chain.
 317 <DT><B>ip6 proto </B><I>protocol</I><DD>
 318 True if the packet is an IPv6 packet of protocol type <I>protocol</I>.
 319 Note that this primitive does not chase the protocol header chain.
 320 <DT><B>ip6 protochain </B><I>protocol</I><DD>
 321 True if the packet is IPv6 packet,
 322 and contains protocol header with type <I>protocol</I>
 323 in its protocol header chain.
 324 For example,
 325 <dl COMPACT>
 326   <dd>
 327
 328 <PRE><B>ip6 protochain 6</B></PRE>
 329
 330
 331   </dd>
 332 </dl>
 333
 334
 335 matches any IPv6 packet with TCP protocol header in the protocol header chain.
 336 The packet may contain, for example,
 337 authentication header, routing header, or hop-by-hop option header,
 338 between IPv6 header and TCP header.
 339 The BPF code emitted by this primitive is complex and
 340 cannot be optimized by BPF optimizer code in <I>tcpdump</I>,
 341 so this can be somewhat slow.
 342 <DT><B>ip protochain </B><I>protocol</I><DD>
 343 Equivalent to <B>ip6 protochain </B><I>protocol</I>, but this is for IPv4.
 344 <DT><B>ether broadcast</B><DD>
 345 True if the packet is an ethernet broadcast packet.
 346 The <I>ether</I>
 347 keyword is optional.
 348 <DT><B>ip broadcast</B><DD>
 349 True if the packet is an IP broadcast packet.
 350 It checks for both
 351 the all-zeroes and all-ones broadcast conventions, and looks up
 352 the local subnet mask.
 353 <DT><B>ether multicast</B><DD>
 354 True if the packet is an ethernet multicast packet.
 355 The <I>ether</I>
 356 keyword is optional.
 357 This is shorthand for `<B>ether[0] &amp; 1 != 0</B>'.
 358 <DT><B>ip multicast</B><DD>
 359 True if the packet is an IP multicast packet.
 360 <DT><B>ip6 multicast</B><DD>
 361 True if the packet is an IPv6 multicast packet.
 362 <DT><B>ether proto </B><I>protocol</I><DD>
 363 True if the packet is of ether type <I>protocol</I>.
 364 <I>Protocol</I> can be a number or one of the names
 365 <I>ip</I>, <I>ip6</I>, <I>arp</I>, <I>rarp</I>, <I>atalk</I>, <I>aarp</I>,
 366 <I>decnet</I>, <I>sca</I>, <I>lat</I>, <I>mopdl</I>, <I>moprc</I>,
 367 <I>iso</I>, <I>stp</I>, <I>ipx</I>, or <I>netbeui</I>.
 368 Note these identifiers are also keywords
 369 and must be escaped via backslash (\).
 370 <DT><DD>
 371 [In the case of FDDI (e.g., `<B>fddi protocol arp</B>') and Token Ring
 372 (e.g., `<B>tr protocol arp</B>'), for most of those protocols, the
 373 protocol identification comes from the 802.2 Logical Link Control (LLC)
 374 header, which is usually layered on top of the FDDI or Token Ring
 375 header.
 376 <DT><DD>
 377 When filtering for most protocol identifiers on FDDI or Token Ring,
 378 <I>tcpdump</I> checks only the protocol ID field of an LLC header in
 379 so-called SNAP format with an Organizational Unit Identifier (OUI) of
 380 0x000000, for encapsulated Ethernet; it doesn't check whether the packet
 381 is in SNAP format with an OUI of 0x000000.
 382 <DT><DD>
 383 The exceptions are <I>iso</I>, for which it checks the DSAP (Destination
 384 Service Access Point) and SSAP (Source Service Access Point) fields of
 385 the LLC header, <I>stp</I> and <I>netbeui</I>, where it checks the DSAP of
 386 the LLC header, and <I>atalk</I>, where it checks for a SNAP-format
 387 packet with an OUI of 0x080007 and the Appletalk etype.
 388 <DT><DD>
 389 In the case of Ethernet, <I>tcpdump</I> checks the Ethernet type field
 390 for most of those protocols; the exceptions are <I>iso</I>, <I>sap</I>,
 391 and <I>netbeui</I>, for which it checks for an 802.3 frame and then
 392 checks the LLC header as it does for FDDI and Token Ring, <I>atalk</I>,
 393 where it checks both for the Appletalk etype in an Ethernet frame and
 394 for a SNAP-format packet as it does for FDDI and Token Ring, <I>aarp</I>,
 395 where it checks for the Appletalk ARP etype in either an Ethernet frame
 396 or an 802.2 SNAP frame with an OUI of 0x000000, and <I>ipx</I>, where it
 397 checks for the IPX etype in an Ethernet frame, the IPX DSAP in the LLC
 398 header, the 802.3 with no LLC header encapsulation of IPX, and the IPX
 399 etype in a SNAP frame.]
 400 <DT><B>decnet src </B><I>host</I><DD>
 401 True if the DECNET source address is
 402 <I>host</I>,
 403
 404 which may be an address of the form ``10.123'', or a DECNET host
 405 name.
 406 [DECNET host name support is only available on Ultrix systems
 407 that are configured to run DECNET.]
 408 <DT><B>decnet dst </B><I>host</I><DD>
 409 True if the DECNET destination address is
 410 <I>host</I>.
 411
 412 <DT><B>decnet host </B><I>host</I><DD>
 413 True if either the DECNET source or destination address is
 414 <I>host</I>.
 415
 416 <DT><B>ip</B>, <B>ip6</B>, <B>arp</B>, <B>rarp</B>, <B>atalk</B>, <B>aarp</B>, <B>decnet</B>, <B>iso</B>, <B>stp</B>, <B>ipx</B>, <I>netbeui</I><DD>
 417 Abbreviations for:
 418 <dl COMPACT>
 419   <dd>
 420
 421 <PRE><B>ether proto </B><I>p</I></PRE>
 422
 423
 424   </dd>
 425 </dl>
 426
 427
 428 where <I>p</I> is one of the above protocols.
 429 <DT><B>lat</B>, <B>moprc</B>, <B>mopdl</B><DD>
 430 Abbreviations for:
 431 <dl COMPACT>
 432   <dd>
 433
 434 <PRE><B>ether proto </B><I>p</I></PRE>
 435
 436
 437   </dd>
 438 </dl>
 439
 440
 441 where <I>p</I> is one of the above protocols.
 442 Note that
 443 <I>tcpdump</I> does not currently know how to parse these protocols.
 444 <DT><B>vlan </B><I>[vlan_id]</I><DD>
 445 True if the packet is an IEEE 802.1Q VLAN packet.
 446 If <I>[vlan_id]</I> is specified, only true is the packet has the specified
 447 <I>vlan_id</I>.
 448 Note that the first <B>vlan</B> keyword encountered in <I>expression</I>
 449 changes the decoding offsets for the remainder of <I>expression</I>
 450 on the assumption that the packet is a VLAN packet.
 451 <DT><B>tcp</B>, <B>udp</B>, <B>icmp</B><DD>
 452 Abbreviations for:
 453 <dl COMPACT>
 454   <dd>
 455
 456 <PRE><B>ip proto </B><I>p</I><B> or ip6 proto </B><I>p</I></PRE>
 457
 458
 459   </dd>
 460 </dl>
 461
 462
 463 where <I>p</I> is one of the above protocols.
 464 <DT><B>iso proto </B><I>protocol</I><DD>
 465 True if the packet is an OSI packet of protocol type <I>protocol</I>.
 466 <I>Protocol</I> can be a number or one of the names
 467 <I>clnp</I>, <I>esis</I>, or <I>isis</I>.
 468 <DT><B>clnp</B>, <B>esis</B>, <B>isis</B><DD>
 469 Abbreviations for:
 470 <dl COMPACT>
 471   <dd>
 472
 473 <PRE><B>iso proto </B><I>p</I></PRE>
 474
 475
 476   </dd>
 477 </dl>
 478
 479
 480 where <I>p</I> is one of the above protocols.
 481 Note that <I>tcpdump</I> does an incomplete job of parsing these protocols.
 482 <DT><I>expr relop expr</I><DD>
 483 True if the relation holds, where <I>relop</I> is one of &gt;, &lt;, &gt;=, &lt;=, =, !=,
 484 and <I>expr</I> is an arithmetic expression composed of integer constants
 485 (expressed in standard C syntax), the normal binary operators
 486 [+, -, *, /, &amp;, |], a length operator, and special packet data accessors.
 487 To access
 488 data inside the packet, use the following syntax:
 489
 490 <PRE>
 491 <I>proto</I><B> [ </B><I>expr</I><B> : </B><I>size</I><B> ]</B>
 492 </PRE>
 493
 494
 495 <I>Proto</I> is one of <B>ether, fddi, tr,
 496 ip, arp, rarp, tcp, udp, icmp</B> or <B>ip6</B>, and
 497 indicates the protocol layer for the index operation.
 498 Note that <I>tcp, udp</I> and other upper-layer protocol types only
 499 apply to IPv4, not IPv6 (this will be fixed in the future).
 500 The byte offset, relative to the indicated protocol layer, is
 501 given by <I>expr</I>.
 502 <I>Size</I> is optional and indicates the number of bytes in the
 503 field of interest; it can be either one, two, or four, and defaults to one.
 504 The length operator, indicated by the keyword <B>len</B>, gives the
 505 length of the packet.
 506 <P>
 507 For example, `<B>ether[0] &amp; 1 != 0</B>' catches all multicast traffic.
 508 The expression `<B>ip[0] &amp; 0xf != 5</B>'
 509 catches all IP packets with options.
 510 The expression
 511 `<B>ip[6:2] &amp; 0x1fff = 0</B>'
 512 catches only unfragmented datagrams and frag zero of fragmented datagrams.
 513 This check is implicitly applied to the <B>tcp</B> and <B>udp</B>
 514 index operations.
 515 For instance, <B>tcp[0]</B> always means the first
 516 byte of the TCP <I>header</I>, and never means the first byte of an
 517 intervening fragment.
 518 <P>
 519 Some offsets and field values may be expressed as names rather than
 520 as numeric values.
 521 The following protocol header field offsets are
 522 available: <B>icmptype</B> (ICMP type field), <B>icmpcode</B> (ICMP
 523 code field), and <B>tcpflags</B> (TCP flags field).
 524 <P>
 525 The following ICMP type field values are available: <B>icmp-echoreply</B>,
 526 <B>icmp-unreach</B>, <B>icmp-sourcequench</B>, <B>icmp-redirect</B>,
 527 <B>icmp-echo</B>, <B>icmp-routeradvert</B>, <B>icmp-routersolicit</B>,
 528 <B>icmp-timxceed</B>, <B>icmp-paramprob</B>, <B>icmp-tstamp</B>,
 529 <B>icmp-tstampreply</B>, <B>icmp-ireq</B>, <B>icmp-ireqreply</B>,
 530 <B>icmp-maskreq</B>, <B>icmp-maskreply</B>.
 531 <P>
 532 The following TCP flags field values are available: <B>tcp-fin</B>,
 533 <B>tcp-syn</B>, <B>tcp-rst</B>, <B>tcp-push</B>, <B>tcp-push</B>,
 534 <B>tcp-ack</B>, <B>tcp-urg</B>.
 535 </DL>
 536 <P>
 537
 538 Primitives may be combined using:
 539 <DL COMPACT>
 540 <DT><DD>
 541 A parenthesized group of primitives and operators
 542 (parentheses are special to the Shell and must be escaped).
 543 <DT><DD>
 544 Negation (`<B>!</B>' or `<B>not</B>').
 545 <DT><DD>
 546 Concatenation (`<B>&amp;&amp;</B>' or `<B>and</B>').
 547 <DT><DD>
 548 Alternation (`<B>||</B>' or `<B>or</B>').
 549 </DL>
 550 <P>
 551
 552 Negation has highest precedence.
 553 Alternation and concatenation have equal precedence and associate
 554 left to right.
 555 Note that explicit <B>and</B> tokens, not juxtaposition,
 556 are now required for concatenation.
 557 <P>
 558
 559 If an identifier is given without a keyword, the most recent keyword
 560 is assumed.
 561 For example,
 562
 563 <blockquote>
 564
 565 <PRE><B>not host vs and ace</B></PRE>
 566
 567
 568 </blockquote>
 569
 570
 571 is short for
 572 <blockquote>
 573
 574 <PRE><B>not host vs and host ace</B></PRE>
 575
 576
 577 </blockquote>
 578
 579
 580 which should not be confused with
 581 <blockquote>
 582
 583 <PRE><B>not ( host vs or ace )</B></PRE>
 584
 585
 586 </blockquote>
 587
 588
 589 <P>
 590
 591 Expression arguments can be passed to <I>tcpdump</I> as either a single
 592 argument or as multiple arguments, whichever is more convenient.
 593 Generally, if the expression contains Shell metacharacters, it is
 594 easier to pass it as a single, quoted argument.
 595 Multiple arguments are concatenated with spaces before being parsed.
 596 <p>
 597
 598 </body>
 599
 600 </html>