On Sun, Sep 05, 2021 at 04:43:34PM +0200, Denis Fondras wrote: > Le Sat, Sep 04, 2021 at 09:57:10PM +0100, Jason McIntyre a ?crit : > > the diff looks ok to me. but run any doc changes through "mandoc > > -Tlint", and look at any issues your diff may have introduced. in this > > case it's just trailing whitespace, but it's super helpful to check your > > work. > > > > Thank you Jason. There is still a warning in tcpdump.8. > > Here is a new version including changes to pcap-filter.5 and tcpdump.8 > I did not change the examples though as tcpdump examples are broader than > filters. >
hi. the warning in tcpdump is fine. the diff reads ok to me, but let's wait for a technical ok ;) jmc > Index: lib/libpcap/pcap-filter.5 > =================================================================== > RCS file: /cvs/src/lib/libpcap/pcap-filter.5,v > retrieving revision 1.9 > diff -u -p -r1.9 pcap-filter.5 > --- lib/libpcap/pcap-filter.5 2 Sep 2021 10:59:13 -0000 1.9 > +++ lib/libpcap/pcap-filter.5 5 Sep 2021 13:35:41 -0000 > @@ -40,27 +40,31 @@ or > .Pp > The filter expression consists of one or more > .Em primitives . > -Primitives usually consist of an ID (name or number) > +Primitives usually consist of an > +.Ar id > +.Pq name or number > preceded by one or more qualifiers. > There are three different kinds of qualifier: > .Bl -tag -width "proto" > -.It type > -Type qualifiers say what kind of thing the ID name or number refers to. > +.It Ar type > +Specify which kind of address component the > +.Ar id > +name or number refers to. > Possible types are > .Cm host , > -.Cm net , > +.Cm net > and > .Cm port . > -For example, > +E.g., > .Dq host foo , > .Dq net 128.3 , > -and > .Dq port 20 . > If there is no type qualifier, > .Cm host > is assumed. > -.It dir > -Dir qualifiers specify a particular transfer direction to and/or from an ID. > +.It Ar dir > +Specify a particular transfer direction to and/or from > +.Ar id . > Possible directions are > .Cm src , > .Cm dst , > @@ -73,11 +77,13 @@ Possible directions are > .Cm addr3 , > and > .Cm addr4 . > -For example, > -.Cm src foo , > -.Cm dst net 128.3 , > -.Cm src or dst port ftp-data . > -If there is no dir qualifier, > +E.g., > +.Dq src foo , > +.Dq dst net 128.3 , > +.Dq src or dst port ftp-data . > +If there is no > +.Ar dir > +qualifier, > .Cm src or dst > is assumed. > The > @@ -89,57 +95,85 @@ The > and > .Cm addr4 > qualifiers are only valid for IEEE 802.11 Wireless LAN link layers. > -For some link layers, such as SLIP and the "cooked" Linux capture mode > -used for the "any" device and for some other device types, the > +For null link layers (i.e., point-to-point protocols such as SLIP > +.Pq Serial Line Internet Protocol > +or the > +.Xr pflog 4 > +header), the > .Cm inbound > and > .Cm outbound > qualifiers can be used to specify a desired direction. > -.It proto > -Proto qualifiers restrict the match to a particular protocol. > -Possible > -protos are: > +.It Ar proto > +Restrict the match to a particular protocol. > +Possible protocols are: > +.Cm ah , > +.Cm arp , > +.Cm atalk , > +.Cm decnet , > +.Cm esp , > .Cm ether , > .Cm fddi , > -.Cm tr , > -.Cm wlan , > +.Cm icmp , > +.Cm icmp6 , > +.Cm igmp , > +.Cm igrp , > .Cm ip , > .Cm ip6 , > -.Cm arp , > +.Cm lat , > +.Cm mopdl , > +.Cm moprc , > +.Cm pim , > .Cm rarp , > -.Cm decnet , > +.Cm sca , > +.Cm stp , > .Cm tcp , > +.Cm udp , > and > -.Cm udp . > -For example, > +.Cm wlan . > +E.g., > .Dq ether src foo , > .Dq arp net 128.3 , > .Dq tcp port 21 , > and > .Dq wlan addr2 0:2:3:4:5:6 . > -If there is no proto qualifier, > +If there is no protocol qualifier, > all protocols consistent with the type are assumed. > -For example, > +E.g., > .Dq src foo > means > -.Dq (ip or arp or rarp) src foo > -(except the latter is not legal syntax); > +.Do > +.Pq ip or arp or rarp > +src foo > +.Dc > +.Pq except the latter is not legal syntax ; > .Dq net bar > means > -.Dq (ip or arp or rarp) net bar ; > +.Do > +.Pq ip or arp or rarp > +net bar > +.Dc ; > and > .Dq port 53 > means > -.Dq (tcp or udp) port 53 . > +.Do > +.Pq TCP or UDP > +port 53 > +.Dc . > .Pp > .Cm fddi > is actually an alias for > .Cm ether ; > the parser treats them identically as meaning > -"the data link level used on the specified network interface". > -FDDI headers contain Ethernet-like source and destination addresses, > +.Qo > +the data link level used on the specified network interface > +.Qc . > +FDDI > +.Pq Fiber Distributed Data Interface > +headers contain Ethernet-like source and destination addresses, > and often contain Ethernet-like packet types, > -so it's possible to filter these FDDI fields just as with the analogous > Ethernet fields. > +so it's possible to filter these FDDI fields just as with the analogous > +Ethernet fields. > FDDI headers also contain other fields, > but they cannot be named explicitly in a filter expression. > .Pp > @@ -156,8 +190,8 @@ and the source address is the SA field; > the BSSID, RA, and TA fields aren't tested. > .El > .Pp > -In addition to the above, > -there are some special primitives that don't follow the pattern: > +In addition to the above, there are some special primitive > +keywords that don't follow the pattern: > .Cm gateway , > .Cm broadcast , > .Cm less , > @@ -170,14 +204,18 @@ More complex filter expressions are buil > .Cm or , > and > .Cm not > -to combine primitives. > -For example, > -.Dq host foo and not port ftp and not port ftp-data . > -To save typing, identical qualifier lists can be omitted, > -so that > +to combine primitives > +e.g., > +.Do > +host foo and not port ftp and not port ftp-data > +.Dc . > +To save typing, identical qualifier lists can be omitted > +e.g., > .Dq tcp dst port ftp or ftp-data or domain > is exactly the same as > -.Dq tcp dst port ftp or tcp dst port ftp-data or tcp dst port domain . > +.Do > +tcp dst port ftp or tcp dst port ftp-data or tcp dst port domain > +.Dc . > .Pp > Allowable primitives are: > .Bl -tag -width "ether proto proto" > @@ -192,7 +230,9 @@ True if the IPv4/v6 source field of the > True if either the IPv4/v6 source or destination of the packet is > .Ar host . > .Pp > -Any of the above host expressions can be prepended with the keywords, > +Any of the above > +.Ar host > +expressions can be prepended with the keywords, > .Cm ip , arp , rarp , > or > .Cm ip6 , > @@ -210,35 +250,33 @@ which is equivalent to: > .Pp > If > .Ar host > -is a name with multiple IP addresses, > -each address will be checked for a match. > +is a name with multiple IP addresses, each address will be checked for a > match. > .It Cm ether dst Ar ehost > True if the Ethernet destination address is > -.Ar ehost , > -which may be either a name from > +.Ar ehost . > +.Ar ehost > +may be either a name from > .Pa /etc/ethers > or a number (see > .Xr ether_aton 3 > -for numeric format). > +for a numeric format). > .It Cm ether src Ar ehost > True if the Ethernet source address is > .Ar ehost . > .It Cm ether host Ar ehost > True if either the Ethernet source or destination address is > .Ar ehost . > -.It Cm gateway host > +.It Cm gateway Ar host > True if the packet used > .Ar host > -as a gateway. > -That is, > -the Ethernet source or destination address was > +as a gateway; i.e., the Ethernet source or destination address was > .Ar host > but neither the IP source nor the IP destination was > .Ar host . > .Ar host > -must be a name and must be found both by the machine's > host-name-to-IP-address resolution > -mechanisms (host name file, DNS, NIS, etc.) and by the machine's > -host-name-to-Ethernet-address resolution mechanism > +must be a name and must be found both by the machine's > +host-name-to-IP-address resolution mechanisms (host name file, DNS, NIS, > +etc.) and by the machine's host-name-to-Ethernet-address resolution mechanism > (such as > .Pa /etc/ethers ) . > An equivalent expression is: > @@ -267,7 +305,7 @@ the netmask is 255.255.255.255 for a dot > 255.255.255.0 for a dotted triple, 255.255.0.0 for a dotted pair, > or 255.0.0.0 for a single number. > An IPv6 network number must be written out fully; > -the netmask is ff:ff:ff:ff:ff:ff:ff:ff, > +the netmask is ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff, > so IPv6 "network" matches are really always host matches, > and a network match requires a netmask length. > .It Cm src net Ar net > @@ -323,16 +361,29 @@ True if the packet has a source port val > .It Cm port Ar port > True if either the source or destination port of the packet is > .Ar port . > +.Pp > +Any of the above port expressions can be prepended with the keywords > +.Cm tcp > +or > +.Cm udp , > +as in: > +.Pp > +.D1 Cm tcp src port Ar port > +.Pp > +which matches only TCP packets whose source port is > +.Ar port . > .It Cm less Ar length > True if the packet has a length less than or equal to > .Ar length . > -This is equivalent to > -.Cm len <= Ar length . > +This is equivalent to: > +.Pp > +.D1 Cm len <= Ar length > .It Cm greater Ar length > True if the packet has a length greater than or equal to > .Ar length . > -This is equivalent to > -.Cm len >= Ar length . > +This is equivalent to: > +.Pp > +.D1 Cm len >= Ar length > .It Cm sample Ar samplerate > True if the packet has been randomly selected or sampled at a rate of 1 per > .Ar samplerate . > @@ -342,7 +393,9 @@ True if the packet is an IPv4 packet (se > of protocol type > .Ar protocol . > .Ar protocol > -can be a number, or one of the names > +can be a number, or one of the names from > +.Xr protocols 5 , > +such as > .Cm icmp , > .Cm icmp6 , > .Cm igmp , > @@ -402,21 +455,34 @@ can be a number, or one of the names > .Cm arp , > .Cm rarp , > .Cm atalk , > +.Cm atalkarp , > .Cm decnet , > -.Cm sca , > +.Cm decdts , > +.Cm decdns , > +.Cm lanbridge , > .Cm lat , > -or > -.Cm stp . > -Note these identifiers are also keywords > -and must be escaped using a backslash character > -.Pq \e . > -.Pp > -In the case of FDDI (such as "fddi protocol arp") > -and IEEE 802.11 wireless LANS (such as "wlan protocol arp"), > +.Cm mopdl , > +.Cm moprc , > +.Cm pup , > +.Cm sca , > +.Cm sprite , > +.Cm stp , > +.Cm vexp , > +.Cm vprod , > +or > +.Cm xns . > +These identifiers are also keywords and must be escaped > +using a backslash character > +.Pq Sq \e . > +.Pp > +In the case of FDDI (e.g., > +.Dq fddi protocol arp ) , > +and IEEE 802.11 wireless LANS (such as > +.Dq wlan protocol arp ) , > for most of those protocols > -the protocol identification comes from > -the 802.2 Logical Link Control (LLC) header, > -which is usually layered on top of the FDDI or 802.11 header. > +the protocol identification comes from the 802.2 Logical Link Control > +.Pq LLC > +header, which is usually layered on top of the FDDI or 802.11 header. > .Pp > When filtering for most protocol identifiers on FDDI or 802.11, > the filter checks only the protocol ID field of an LLC header > @@ -449,9 +515,11 @@ for a SNAP-format packet as it does for > .It Cm decnet src Ar host > True if the DECNET source address is > .Ar host , > -which may be an address of the form "10.123", or a DECNET hostname. > -DECNET hostname support is only available on ULTRIX systems > -that are configured to run DECNET. > +which may be an address of the form > +.Dq 10.123 , > +or a DECNET host name. > +DECNET host name support is only available on systems that are > +configured to run DECNET. > .It Cm decnet dst Ar host > True if the DECNET destination address is > .Ar host . > @@ -468,24 +536,33 @@ Synonymous with the > modifier. > .It Cm rnr Ar num > True if the packet was logged as matching the specified PF rule number > -(applies only to packets logged by > -.Xr pf 4 ) . > +in the main ruleset (applies only to packets logged by > +.Xr pf 4 ) . > .It Cm rulenum Ar num > Synonymous with the > .Cm rnr > modifier. > .It Cm reason Ar code > True if the packet was logged with the specified PF reason code. > -The known codes are: > +Known codes are: > .Cm match , > .Cm bad-offset , > .Cm fragment , > .Cm short , > .Cm normalize , > +.Cm memory , > +.Cm bad-timestamp , > +.Cm congestion , > +.Cm ip-option , > +.Cm proto-cksum , > +.Cm state-mismatch , > +.Cm state-insert , > +.Cm state-limit , > +.Cm src-limit , > and > -.Cm memory > +.Cm synproxy > (applies only to packets logged by > -.Xr pf 4 ) . > +.Xr pf 4 ) . > .It Cm rset Ar name > True if the packet was logged as matching the specified PF ruleset > name of an anchored ruleset (applies only to packets logged by > @@ -497,7 +574,7 @@ modifier. > .It Cm srnr Ar num > True if the packet was logged as matching the specified PF rule number > of an anchored ruleset (applies only to packets logged by > -.Xr pf 4 ) . > +.Xr pf 4 ) . > .It Cm subrulenum Ar num > Synonymous with the > .Cm srnr > @@ -507,12 +584,11 @@ True if PF took the specified action whe > Known actions are: > .Cm pass > and > -.Cm block > -and, with later versions of > -.Xr pf 4 , > +.Cm block , > .Cm nat , > .Cm rdr , > -.Cm binat > +.Cm binat , > +.Cm match > and > .Cm scrub > (applies only to packets logged by > @@ -531,15 +607,52 @@ where > is one of the above protocols. > Note that not all applications using > .Xr pcap_open_live 3 > -currently know how to parse these protocols. > +currently know how to parse these protocols (ie. > +.Xr tcpdump 8 ) . > +.It Xo > +.Cm ah , > +.Cm esp , > +.Cm icmp , > +.Cm icmp6 , > +.Cm igmp , > +.Cm igrp , > +.Cm pim , > +.Cm tcp , > +.Cm udp > +.Xc > +Abbreviations for > +.Cm ip proto Ar p > +or > +.Cm ip6 proto Ar p , > +where > +.Ar p > +is one of the above protocols. > +.It Cm wlan addr1 Ar ehost > +True if the first IEEE 802.11 address is > +.Ar ehost . > +.It Cm wlan addr2 Ar ehost > +True if the second IEEE 802.11 address is > +.Ar ehost . > +.It Cm wlan addr3 Ar ehost > +True if the third IEEE 802.11 address is > +.Ar ehost . > +.It Cm wlan addr4 Ar ehost > +True if the fourth IEEE 802.11 address is > +.Ar ehost . > +The fourth address field is only used for > +WDS (Wireless Distribution System) frames. > +.It Cm wlan host Ar ehost > +True if either the first, second, third, or fourth > +IEEE 802.11 address is > +.Ar ehost . > .It Cm type Ar wlan_type > True if the IEEE 802.11 frame type matches the specified > .Ar wlan_type . > Valid types are: > .Cm mgt , > .Cm ctl , > -and > -.Cm data . > +.Cm data , > +or a numeric value. > .It Cm type Ar wlan_type Cm subtype Ar wlan_subtype > True if the IEEE 802.11 frame type matches the specified > .Ar wlan_type > @@ -643,7 +756,7 @@ To filter IPv4 protocols encapsulated in > higher order VLAN: > .Pp > .Dl vlan && vlan 300 && ip > -.It mpls Op Ar label > +.It Cm mpls Op Ar label > True if the packet is an MPLS (Multi-Protocol Label Switching) packet. > If > .Ar label > @@ -666,14 +779,6 @@ to filter on MPLS label 42 first and req > To filter on network 192.0.2.0/24 transported inside packets with label 42: > .Pp > .Dl mpls 42 && net 192.0.2.0/24 > -.It Cm tcp , udp , icmp > -Abbreviations for > -.Cm ip proto Ar p > -or > -.Cm ip6 proto Ar p , > -where > -.Ar p > -is one of the above protocols. > .It Ar expr relop expr > True if the relation holds, where > .Ar relop > @@ -744,10 +849,10 @@ The byte offset, relative to the indicat > is optional and indicates the number of bytes in the field of interest; > it can be either one, two, or four, and defaults to one. > The length operator, indicated by the keyword > -.Ar len , > +.Cm len , > gives the length of the packet. > The random operator, indicated by the keyword > -.Ar random , > +.Cm random , > generates a random number. > .Pp > For example, > @@ -767,8 +872,7 @@ and > index operations. > For instance, > .Dq tcp[0] > -always means the first byte of the TCP > -.Ar header , > +always means the first byte of the TCP header, > and never means the first byte of an intervening fragment. > .Pp > Some offsets and field values may be expressed as names rather than > @@ -811,6 +915,7 @@ The following TCP flags field values are > Primitives may be combined using > a parenthesized group of primitives and operators. > Parentheses are special to the shell and must be escaped. > +Allowable primitives and operators are: > .Bd -ragged -offset indent > Negation > .Po > @@ -837,7 +942,7 @@ or > Negation has highest precedence. > Alternation and concatenation have equal precedence and associate > left to right. > -Note that explicit > +Explicit > .Cm and > tokens, not juxtaposition, > are now required for concatenation. > @@ -845,11 +950,27 @@ are now required for concatenation. > If an identifier is given without a keyword, the most recent keyword > is assumed. > For example, > -.Dq not host vs and ace > +For example, > +.Bd -ragged -offset indent > +.Cm not host > +vs > +.Cm and > +ace > +.Ed > +.Pp > is short for > -.Dq not host vs and host ace , > -which shouldn't be confused with > -.Dq not (\& host vs or ace )\& . > +.Bd -ragged -offset indent > +.Cm not host > +vs > +.Cm and host > +ace > +.Ed > +.Pp > +which should not be confused with > +.Bd -ragged -offset indent > +.Cm not > +.Pq Cm host No vs Cm or No ace > +.Ed > .Sh EXAMPLES > To select all packets arriving at or departing from > .Dq sundown : > @@ -914,7 +1035,8 @@ that were not sent via Ethernet broadcas > .Pp > .Dl ether[0] & 1 = 0 and ip[16] >= 224 > .Pp > -To select all ICMP packets that are not echo requests/replies (i.e. not ping > packets): > +To select all ICMP packets that are not echo requests/replies > +(i.e. not ping packets): > .Pp > .Dl icmp[icmptype] != icmp-echo and icmp[icmptype] != icmp-echoreply > .Sh SEE ALSO > Index: usr.sbin/tcpdump/tcpdump.8 > =================================================================== > RCS file: /cvs/src/usr.sbin/tcpdump/tcpdump.8,v > retrieving revision 1.111 > diff -u -p -r1.111 tcpdump.8 > --- usr.sbin/tcpdump/tcpdump.8 17 Aug 2020 06:29:29 -0000 1.111 > +++ usr.sbin/tcpdump/tcpdump.8 5 Sep 2021 13:35:43 -0000 > @@ -336,14 +336,13 @@ Otherwise, only packets satisfying > .Ar expression > will be dumped. > .Pp > -The > -.Ar expression > -consists of one or more primitives. > +The filter expression consists of one or more > +.Em primitives . > Primitives usually consist of an > .Ar id > .Pq name or number > preceded by one or more qualifiers. > -There are three different kinds of qualifiers: > +There are three different kinds of qualifier: > .Bl -tag -width "proto" > .It Ar type > Specify which kind of address component the > @@ -369,6 +368,8 @@ Possible directions are > .Cm dst , > .Cm src or dst , > .Cm src and dst , > +.Cm ra , > +.Cm ta , > .Cm addr1 , > .Cm addr2 , > .Cm addr3 , > @@ -384,6 +385,8 @@ qualifier, > .Cm src or dst > is assumed. > The > +.Cm ra , > +.Cm ta , > .Cm addr1 , > .Cm addr2 , > .Cm addr3 , > @@ -430,7 +433,8 @@ E.g., > .Dq ether src foo , > .Dq arp net 128.3 , > .Dq tcp port 21 , > -.Dq wlan addr1 0:2:3:4:5:6 . > +and > +.Dq wlan addr2 0:2:3:4:5:6 . > If there is no protocol qualifier, > all protocols consistent with the type are assumed. > E.g., > @@ -466,10 +470,22 @@ FDDI > .Pq Fiber Distributed Data Interface > headers contain Ethernet-like source and destination addresses, > and often contain Ethernet-like packet types, > -so you can filter on these FDDI fields just as with the analogous > +so it's possible to filter these FDDI fields just as with the analogous > Ethernet fields. > FDDI headers also contain other fields, > -but you cannot name them explicitly in a filter expression. > +but they cannot be named explicitly in a filter expression. > +.Pp > +Similarly, > +.Cm tr > +and > +.Cm wlan > +are aliases for > +.Cm ether ; > +the previous paragraph's statements about FDDI headers also apply to Token > Ring > +and 802.11 wireless LAN headers. > +For 802.11 headers, the destination address is the DA field > +and the source address is the SA field; > +the BSSID, RA, and TA fields aren't tested. > .El > .Pp > In addition to the above, there are some special primitive > @@ -502,23 +518,22 @@ tcp dst port ftp or tcp dst port ftp-dat > Allowable primitives are: > .Bl -tag -width "ether proto proto" > .It Cm dst host Ar host > -True if the IP destination field of the packet is > +True if the IPv4/v6 destination field of the packet is > .Ar host , > which may be either an address or a name. > .It Cm src host Ar host > -True if the IP source field of the packet is > +True if the IPv4/v6 source field of the packet is > .Ar host . > .It Cm host Ar host > -True if either the IP source or destination of the packet is > +True if either the IPv4/v6 source or destination of the packet is > .Ar host . > .Pp > Any of the above > .Ar host > expressions can be prepended with the keywords, > -.Cm ip , > -.Cm arp , > +.Cm ip , arp , rarp , > or > -.Cm rarp > +.Cm ip6 , > as in: > .Pp > .D1 Cm ip host Ar host > @@ -557,11 +572,12 @@ as a gateway; i.e., the Ethernet source > but neither the IP source nor the IP destination was > .Ar host . > .Ar host > -must be a name and must be found in both > -.Pa /etc/hosts > -and > -.Pa /etc/ethers . > -An equivalent expression is > +must be a name and must be found both by the machine's > +host-name-to-IP-address resolution mechanisms (host name file, DNS, NIS, > +etc.) and by the machine's host-name-to-Ethernet-address resolution mechanism > +(such as > +.Pa /etc/ethers ) . > +An equivalent expression is: > .Bd -ragged -offset indent > .Cm ether host > .Ar ehost > @@ -569,42 +585,74 @@ An equivalent expression is > .Ar host > .Ed > .Pp > -which can be used with either names or numbers for > -.Ar host Ns / Ns Ar ehost . > +which can be used with either names or numbers for host/ehost. > +This syntax does not work in an IPv6-enabled configuration at this moment. > .It Cm dst net Ar net > -True if the IP destination address of the packet has a network number of > -.Ar net . > -.Ar net > -may be either a name from > -.Pa /etc/hosts > -or a network number (see > -.Xr hosts 5 > -for details). > +True if the IPv4/v6 destination address of the packet has a network > +number of > +.Ar net , > +which may be either a name from the networks database > +(such as > +.Pa /etc/networks ) > +or a network number. > +An IPv4 network number can be written as a dotted quad (e.g. 192.168.1.0), > +dotted triple (e.g. 192.168.1), dotted pair (e.g 172.16), > +or single number (e.g. 10); > +the netmask is 255.255.255.255 for a dotted quad > +(which means that it's really a host match), > +255.255.255.0 for a dotted triple, 255.255.0.0 for a dotted pair, > +or 255.0.0.0 for a single number. > +An IPv6 network number must be written out fully; > +the netmask is ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff, > +so IPv6 "network" matches are really always host matches, > +and a network match requires a netmask length. > .It Cm src net Ar net > -True if the IP source address of the packet has a network number of > +True if the IPv4/v6 source address of the packet has a network number of > .Ar net . > .It Cm net Ar net > -True if either the IP source or destination address of the packet > +True if either the IPv4/v6 source or destination address of the packet > has a network number of > .Ar net . > +.It Cm net Ar net Cm mask Ar netmask > +True if the IPv4 address matches > +.Ar net > +with the specific > +.Ar netmask . > +May be qualified with > +.Cm src > +or > +.Cm dst . > +Note that this syntax is not valid for IPv6 networks. > +.It Cm net Ar net Ns / Ns Ar len > +True if the IPv4/v6 address matches > +.Ar net > +with a netmask > +.Ar len > +bits wide. > +May be qualified with > +.Cm src > +or > +.Cm dst . > .It Cm dst port Ar port > -True if the packet is IP/TCP or IP/UDP and has a destination port value of > +True if the packet is IP/TCP, IP/UDP, IP6/TCP or IP6/UDP > +and has a destination port value of > .Ar port . > The > .Ar port > -can be a number or name from > -.Xr services 5 > +can be a number or a name used in > +.Pa /etc/services > (see > .Xr tcp 4 > and > .Xr udp 4 ) . > If a name is used, both the port number and protocol are checked. > -If a number or ambiguous name is used, only the port number is checked; > -e.g., > -.Dq Cm dst port No 513 > -will print both TCP/login traffic and UDP/who traffic, and > -.Dq Cm dst port No domain > -will print both TCP/domain and UDP/domain traffic. > +If a number or ambiguous name is used, > +only the port number is checked (e.g.\& > +.Dq dst port 513 > +will print both > +TCP/login traffic and UDP/who traffic, and > +.Dq port domain > +will print both TCP/domain and UDP/domain traffic). > .It Cm src port Ar port > True if the packet has a source port value of > .Ar port . > @@ -634,47 +682,72 @@ True if the packet has a length greater > This is equivalent to: > .Pp > .D1 Cm len >= Ar length > -.It Cm ip proto Ar proto > -True if the packet is an IP packet (see > +.It Cm sample Ar samplerate > +True if the packet has been randomly selected or sampled at a rate of 1 per > +.Ar samplerate . > +.It Cm ip proto Ar protocol > +True if the packet is an IPv4 packet (see > .Xr ip 4 ) > of protocol type > -.Ar proto . > -.Ar proto > -can be a number or name from > +.Ar protocol . > +.Ar protocol > +can be a number, or one of the names from > .Xr protocols 5 , > such as > .Cm icmp , > +.Cm icmp6 , > +.Cm igmp , > +.Cm igrp , > +.Cm pim , > +.Cm ah , > +.Cm esp , > +.Cm vrrp , > .Cm udp , > or > .Cm tcp . > -These identifiers are also keywords and must be escaped > -using a backslash character > -.Pq Sq \e . > +Note that the identifiers > +.Cm tcp , > +.Cm udp , > +and > +.Cm icmp > +are also keywords and must be escaped using a backslash character > +.Pq \e . > +Note that this primitive does not chase the protocol header chain. > +.It Cm ip6 proto Ar protocol > +True if the packet is an IPv6 packet of protocol type > +.Ar protocol . > +Note that this primitive does not chase the protocol header chain. > .It Cm ether broadcast > True if the packet is an Ethernet broadcast packet. > The > .Cm ether > keyword is optional. > .It Cm ip broadcast > -True if the packet is an IP broadcast packet. > -It checks for both the all-zeroes and all-ones broadcast conventions > -and looks up the local subnet mask. > +True if the packet is an IPv4 broadcast packet. > +It checks for both the all-zeroes and all-ones broadcast conventions, > +and looks up the subnet mask on the interface on which the capture is > +being done. > +.Pp > +If the subnet mask of the interface on which the capture is being done > +is not known, a value of PCAP_NETMASK_UNKNOWN can be supplied; > +tests for IPv4 broadcast addresses will fail to compile, > +but all other tests in the filter program will be OK. > .It Cm ether multicast > True if the packet is an Ethernet multicast packet. > The > .Cm ether > keyword is optional. > This is shorthand for > -.Do > -.Cm ether Ns [0] & 1 != 0 > -.Dc . > +.Dq ether[0] & 1 != 0 . > .It Cm ip multicast > -True if the packet is an IP multicast packet. > -.It Cm ether proto Ar proto > +True if the packet is an IPv4 multicast packet. > +.It Cm ip6 multicast > +True if the packet is an IPv6 multicast packet. > +.It Cm ether proto Ar protocol > True if the packet is of ether type > -.Ar proto . > -.Ar proto > -can be a number or one of the names > +.Ar protocol . > +.Ar protocol > +can be a number, or one of the names > .Cm ip , > .Cm ip6 , > .Cm arp , > @@ -699,14 +772,44 @@ or > These identifiers are also keywords and must be escaped > using a backslash character > .Pq Sq \e . > +.Pp > In the case of FDDI (e.g., > -.Dq Cm fddi protocol arp ) , > +.Dq fddi protocol arp ) , > +and IEEE 802.11 wireless LANS (such as > +.Dq wlan protocol arp ) , > +for most of those protocols > the protocol identification comes from the 802.2 Logical Link Control > .Pq LLC > -header, which is usually layered on top of the FDDI header. > -.Nm > -assumes, when filtering on the protocol identifier, that all FDDI packets > -include an LLC header, and that the LLC header is in so-called SNAP format. > +header, which is usually layered on top of the FDDI or 802.11 header. > +.Pp > +When filtering for most protocol identifiers on FDDI or 802.11, > +the filter checks only the protocol ID field of an LLC header > +in so-called SNAP format with an Organizational Unit Identifier (OUI) of > +0x000000, for encapsulated Ethernet; it doesn't check whether the packet > +is in SNAP format with an OUI of 0x000000. > +The exceptions are: > +.Bl -tag -width "atalk" > +.It iso > +The filter checks the DSAP (Destination Service Access Point) and > +SSAP (Source Service Access Point) fields of the LLC header. > +.It stp > +The filter checks the DSAP of the LLC header. > +.It atalk > +The filter checks for a SNAP-format packet with an OUI of 0x080007 > +and the AppleTalk etype. > +.El > +.Pp > +In the case of Ethernet, the filter checks the Ethernet type field > +for most of those protocols. > +The exceptions are: > +.Bl -tag -width "iso and stp" > +.It iso and stp > +The filter checks for an 802.3 frame and then checks the LLC header as > +it does for FDDI and 802.11. > +.It atalk > +The filter checks both for the AppleTalk etype in an Ethernet frame and > +for a SNAP-format packet as it does for FDDI, Token Ring, and 802.11. > +.El > .It Cm decnet src Ar host > True if the DECNET source address is > .Ar host , > @@ -727,7 +830,7 @@ True if the packet was logged as coming > .Xr pf 4 ) . > .It Cm on Ar interface > Synonymous with the > -.Ar ifname > +.Cm ifname > modifier. > .It Cm rnr Ar num > True if the packet was logged as matching the specified PF rule number > @@ -735,27 +838,27 @@ in the main ruleset (applies only to pac > .Xr pf 4 ) . > .It Cm rulenum Ar num > Synonymous with the > -.Ar rnr > +.Cm rnr > modifier. > .It Cm reason Ar code > True if the packet was logged with the specified PF reason code. > -The known codes are: > -.Ar match , > -.Ar bad-offset , > -.Ar fragment , > -.Ar short , > -.Ar normalize , > -.Ar memory , > -.Ar bad-timestamp , > -.Ar congestion , > -.Ar ip-option , > -.Ar proto-cksum , > -.Ar state-mismatch , > -.Ar state-insert , > -.Ar state-limit , > -.Ar src-limit , > +Known codes are: > +.Cm match , > +.Cm bad-offset , > +.Cm fragment , > +.Cm short , > +.Cm normalize , > +.Cm memory , > +.Cm bad-timestamp , > +.Cm congestion , > +.Cm ip-option , > +.Cm proto-cksum , > +.Cm state-mismatch , > +.Cm state-insert , > +.Cm state-limit , > +.Cm src-limit , > and > -.Ar synproxy > +.Cm synproxy > (applies only to packets logged by > .Xr pf 4 ) . > .It Cm rset Ar name > @@ -764,7 +867,7 @@ name of an anchored ruleset (applies onl > .Xr pf 4 ) . > .It Cm ruleset Ar name > Synonymous with the > -.Ar rset > +.Cm rset > modifier. > .It Cm srnr Ar num > True if the packet was logged as matching the specified PF rule number > @@ -772,17 +875,54 @@ of an anchored ruleset (applies only to > .Xr pf 4 ) . > .It Cm subrulenum Ar num > Synonymous with the > -.Ar srnr > +.Cm srnr > modifier. > .It Cm action Ar act > True if PF took the specified action when the packet was logged. > -Valid actions are: > -.Ar pass , > -.Ar block , > +Known actions are: > +.Cm pass > +and > +.Cm block , > +.Cm nat , > +.Cm rdr , > +.Cm binat , > +.Cm match > and > -.Ar match > +.Cm scrub > (applies only to packets logged by > .Xr pf 4 ) . > +.It Cm ip , ip6 , arp , rarp , atalk , decnet , iso , stp > +Abbreviations for > +.Cm ether proto Ar p , > +where > +.Ar p > +is one of the above protocols. > +.It Cm lat , moprc , mopdl > +Abbreviations for > +.Cm ether proto Ar p , > +where > +.Ar p > +is one of the above protocols. > +.Cm tcpdump > +does not currently know how to parse these. > +.It Xo > +.Cm ah , > +.Cm esp , > +.Cm icmp , > +.Cm icmp6 , > +.Cm igmp , > +.Cm igrp , > +.Cm pim , > +.Cm tcp , > +.Cm udp > +.Xc > +Abbreviations for > +.Cm ip proto Ar p > +or > +.Cm ip6 proto Ar p , > +where > +.Ar p > +is one of the above protocols. > .It Cm wlan addr1 Ar ehost > True if the first IEEE 802.11 address is > .Ar ehost . > @@ -801,120 +941,204 @@ WDS (Wireless Distribution System) frame > True if either the first, second, third, or fourth > IEEE 802.11 address is > .Ar ehost . > -.It Cm type Ar type > +.It Cm type Ar wlan_type > True if the IEEE 802.11 frame type matches the specified > -.Ar type . > +.Ar wlan_type . > Valid types are: > -.Ar data , > -.Ar mgt , > -.Ar ctl , > +.Cm mgt , > +.Cm ctl , > +.Cm data , > or a numeric value. > -.It Cm subtype Ar subtype > +.It Cm type Ar wlan_type Cm subtype Ar wlan_subtype > +True if the IEEE 802.11 frame type matches the specified > +.Ar wlan_type > +and frame subtype matches the specified > +.Ar wlan_subtype . > +.Pp > +If the specified > +.Ar wlan_type > +is > +.Cm mgtv , > +then valid values for > +.Ar wlan_subtype > +are > +.Cm assoc-req , > +.Cm assoc-resp , > +.Cm reassoc-req , > +.Cm reassoc-resp , > +.Cm probe-req , > +.Cm probe-resp , > +.Cm beacon , > +.Cm atim , > +.Cm disassoc , > +.Cm auth , > +and > +.Cm deauth . > +.Pp > +If the specified > +.Ar wlan_type > +is > +.Cm ctl , > +then valid values for > +.Ar wlan_subtype > +are > +.Cm ps-poll , > +.Cm rts , > +.Cm cts , > +.Cm ack , > +.Cm cf-end , > +and > +.Cm cf-end-ack . > +.Pp > +If the specified > +.Ar wlan_type > +is > +.Cm data , > +then valid values for > +.Ar wlan_subtype > +are > +.Cm data , > +.Cm data-cf-ack , > +.Cm data-cf-poll , > +.Cm data-cf-ack-poll , > +.Cm null , > +.Cm cf-ack , > +.Cm cf-poll , > +.Cm cf-ack-poll , > +.Cm qos-data , > +.Cm qos-data-cf-ack , > +.Cm qos-data-cf-poll , > +.Cm qos-data-cf-ack-poll , > +.Cm qos , > +.Cm qos-cf-poll , > +and > +.Cm qos-cf-ack-poll . > +.It Cm subtype Ar wlan_subtype > True if the IEEE 802.11 frame subtype matches the specified > -.Ar subtype . > -Valid subtypes are: > -.Ar assocreq , > -.Ar assocresp , > -.Ar reassocreq , > -.Ar reassocresp , > -.Ar probereq , > -.Ar proberesp , > -.Ar beacon , > -.Ar atim , > -.Ar disassoc , > -.Ar auth , > -.Ar deauth , > -.Ar data , > -or a numeric value. > +.Ar wlan_subtype > +and frame has the type to which the specified > +.Ar wlan_subtype > +belongs. > .It Cm dir Ar dir > True if the IEEE 802.11 frame direction matches the specified > -.Ar dir . > +.Cm dir . > Valid directions are: > -.Ar nods , > -.Ar tods , > -.Ar fromds , > -.Ar dstods , > +.Cm nods , > +.Cm tods , > +.Cm fromds , > +.Cm dstods , > or a numeric value. > -.It Xo > -.Cm atalk , > -.Cm ip , > -.Cm ip6 , > -.Cm arp , > -.Cm decnet , > -.Cm lat , > -.Cm moprc , > -.Cm mopdl , > -.Cm rarp , > -.Cm sca > -.Xc > -Abbreviations for: > -.Cm ether proto Ar p > -where > -.Ar p > -is one of the above protocols. > -.Nm > -does not currently know how to parse > -.Cm lat , > -.Cm moprc , > -or > -.Cm mopdl . > -.It Xo > -.Cm ah , > -.Cm esp , > -.Cm icmp , > -.Cm icmp6 , > -.Cm igmp , > -.Cm igrp , > -.Cm pim , > -.Cm tcp , > -.Cm udp > -.Xc > -Abbreviations for: > -.Cm ip proto Ar p > -where > -.Ar p > -is one of the above protocols. > +.It Cm vlan Op Ar vlan_id > +True if the packet is an IEEE 802.1Q VLAN packet. > +If > +.Ar vlan_id > +is specified, only true if the packet has the specified ID. > +Note that the first > +.Cm vlan > +keyword encountered in > +.Ar expression > +changes the decoding offsets for the remainder of > +.Ar expression > +on the assumption that the packet is a VLAN packet. > +This expression may be used more than once, to filter on VLAN hierarchies. > +Each use of that expression increments the filter offsets by 4. > +.Pp > +For example, > +to filter on VLAN 200 encapsulated within VLAN 100: > +.Pp > +.Dl vlan 100 && vlan 200 > +.Pp > +To filter IPv4 protocols encapsulated in VLAN 300 encapsulated within any > +higher order VLAN: > +.Pp > +.Dl vlan && vlan 300 && ip > +.It Cm mpls Op Ar label > +True if the packet is an MPLS (Multi-Protocol Label Switching) packet. > +If > +.Ar label > +is specified, only true if the packet has the specified label. > +Note that the first > +.Cm mpls > +keyword encountered in > +.Ar expression > +changes the decoding offsets for the remainder of > +.Ar expression > +on the assumption that the packet is an MPLS packet. > +This expression may be used more than once, to filter on MPLS labels. > +Each use of that expression increments the filter offsets by 4. > +.Pp > +For example, > +to filter on MPLS label 42 first and requires the next label to be 12: > +.Pp > +.Dl mpls 42 && mpls 12 > +.Pp > +To filter on network 192.0.2.0/24 transported inside packets with label 42: > +.Pp > +.Dl mpls 42 && net 192.0.2.0/24 > .It Ar expr relop expr > True if the relation holds, where > .Ar relop > is one of > -.Ql > , > -.Ql < , > -.Ql >= , > -.Ql <= , > -.Ql = , > -.Ql != , > +.Sq > , > +.Sq < , > +.Sq >= , > +.Sq <= , > +.Sq = , > +.Sq != , > and > .Ar expr > is an arithmetic expression composed of integer constants > -.Pq expressed in standard C syntax , > -the normal binary operators > -.Ql ( + , > -.Ql - , > -.Ql * , > -.Ql / , > -.Ql & , > -.Ql | ) , > -a length operator, and special packet data accessors. > +(expressed in standard C syntax), the normal binary operators > +.Pf ( Sq + , > +.Sq - , > +.Sq * , > +.Sq / , > +.Sq & , > +.Sq | , > +.Sq << , > +.Sq >> ) , > +a length operator, a random operator, and special packet data accessors. > +Note that all comparisons are unsigned, so that, for example, > +0x80000000 and 0xffffffff are > 0. > To access data inside the packet, use the following syntax: > -.Sm off > -.Bd -ragged -offset indent > -.Ar proto Op Ar expr : Ar size > -.Ed > -.Sm on > +.Pp > +.D1 Ar proto Ns Op Ar expr : Ns Ar size > .Pp > .Ar proto > is one of > .Cm ether , > .Cm fddi , > +.Cm tr , > +.Cm wlan , > +.Cm ppp , > +.Cm slip , > +.Cm link , > .Cm ip , > .Cm arp , > .Cm rarp , > .Cm tcp , > .Cm udp , > -or > .Cm icmp , > -and indicates the protocol layer for the index operation. > +.Cm ip6 , > +or > +.Cm radio , > +and indicates the protocol layer for the index operation > +.Pf ( Cm ether , > +.Cm fddi , > +.Cm wlan , > +.Cm tr , > +.Cm ppp , > +.Cm slip , > +and > +.Cm link > +all refer to the link layer; > +.Cm radio > +refers to the "radio header" added to some 802.11 captures). > +Note that > +.Cm tcp , > +.Cm udp , > +and other upper-layer protocol types only apply to IPv4, not IPv6 > +(this will be fixed in the future). > The byte offset, relative to the indicated protocol layer, is given by > .Ar expr . > .Ar size > @@ -923,29 +1147,69 @@ it can be either one, two, or four, and > The length operator, indicated by the keyword > .Cm len , > gives the length of the packet. > +The random operator, indicated by the keyword > +.Cm random , > +generates a random number. > .Pp > For example, > -.Dq Cm ether Ns [0] & 1 != 0 > +.Dq ether[0] & 1 != 0 > catches all multicast traffic. > The expression > -.Dq Cm ip Ns [0] & 0xf != 5 > -catches all IP packets with options. > +.Dq ip[0] & 0xf != 5 > +catches all IPv4 packets with options. > The expression > -.Dq Cm ip Ns [6:2] & 0x1fff = 0 > -catches only unfragmented datagrams and frag zero of fragmented datagrams. > +.Dq ip[6:2] & 0x1fff = 0 > +catches only unfragmented IPv4 datagrams and frag zero of fragmented > +IPv4 datagrams. > This check is implicitly applied to the > .Cm tcp > and > .Cm udp > index operations. > For instance, > -.Dq Cm tcp Ns [0] > +.Dq tcp[0] > always means the first byte of the TCP header, > and never means the first byte of an intervening fragment. > +.Pp > +Some offsets and field values may be expressed as names rather than > +as numeric values. > +The following protocol header field offsets are available: > +.Cm icmptype > +(ICMP type field), > +.Cm icmpcode > +(ICMP code field), and > +.Cm tcpflags > +(TCP flags field). > +.Pp > +The following ICMP type field values are available: > +.Cm icmp-echoreply , > +.Cm icmp-unreach , > +.Cm icmp-sourcequench , > +.Cm icmp-redirect , > +.Cm icmp-echo , > +.Cm icmp-routeradvert , > +.Cm icmp-routersolicit , > +.Cm icmp-timxceed , > +.Cm icmp-paramprob , > +.Cm icmp-tstamp , > +.Cm icmp-tstampreply , > +.Cm icmp-ireq , > +.Cm icmp-ireqreply , > +.Cm icmp-maskreq , > +.Cm and > +.Cm icmp-maskreply . > +.Pp > +The following TCP flags field values are available: > +.Cm tcp-fin , > +.Cm tcp-syn , > +.Cm tcp-rst , > +.Cm tcp-push , > +.Cm tcp-ack , > +.Cm tcp-urg . > .El > .Pp > -Primitives may be combined using a parenthesized group of primitives and > -operators. > +Primitives may be combined using > +a parenthesized group of primitives and operators. > Parentheses are special to the shell and must be escaped. > Allowable primitives and operators are: > .Bd -ragged -offset indent > @@ -972,13 +1236,16 @@ or > .Ed > .Pp > Negation has highest precedence. > -Alternation and concatenation have equal precedence and associate left to > right. > +Alternation and concatenation have equal precedence and associate > +left to right. > Explicit > .Cm and > tokens, not juxtaposition, > are now required for concatenation. > .Pp > -If an identifier is given without a keyword, the most recent keyword is > assumed. > +If an identifier is given without a keyword, the most recent keyword > +is assumed. > +For example, > For example, > .Bd -ragged -offset indent > .Cm not host > @@ -1000,14 +1267,6 @@ which should not be confused with > .Cm not > .Pq Cm host No vs Cm or No ace > .Ed > -.Pp > -Expression arguments can be passed to > -.Nm > -as either a single argument or as multiple arguments, > -whichever is more convenient. > -Generally, if the expression contains shell metacharacters, > -it is easier to pass it as a single, quoted argument. > -Multiple arguments are concatenated with spaces before being parsed. > .Sh EXAMPLES > To print all packets arriving at or departing from sundown: > .Pp >
