1xdp-filter(8) A simple XDP-powered packet filter xdp-filter(8)
2
6 xdp-filter - a simple XDP-powered packet filter
7
9 XDP-filter is a packet filtering utility powered by XDP. It is deliber‐
10 ately simple and so does not have the same matching capabilities as,
11 e.g., netfilter. Instead, thanks to XDP, it can achieve very high drop
12 rates: tens of millions of packets per second on a single CPU core.
13 Running xdp-filter
16 The syntax for running xdp-filter is:
17 xdp-filter COMMAND [options]
19 Where COMMAND can be one of:
21 load - load xdp-filter on an interface
22 unload - unload xdp-filter from an interface
23 port - add a port to the filter list
24 ip - add an IP address to the filter list
25 ether - add an Ethernet MAC address to the filter list
26 status - show current xdp-filter status
27 poll - poll statistics output
28 help - show the list of available commands
29 Each command, and its options are explained below. Or use xdp-filter
32 COMMAND --help to see the options for each command.
33
36 To use xdp-filter, it must first be loaded onto an interface. This is
37 accomplished with the load command, which takes the name of the inter‐
38 face as a parameter, and optionally allows specifying the features that
39 should be included. By default all features are loaded, but de-select‐
40 ing some features can speed up the packet matching, and increase per‐
41 formance by a substantial amount.
42 The syntax for the load command is:
45 xdp-filter load [options] <ifname>
48 Where <ifname> is the name of the interface to load xdp-filter onto,
51 and must be specified. The supported options are:
52 -m, --mode <mode>
55 Specifies which mode to load the XDP program to be loaded in. The valid
56 values are 'native', which is the default in-driver XDP mode, 'skb',
57 which causes the so-called skb mode (also known as generic XDP) to be
58 used, or 'hw' which causes the program to be offloaded to the hardware.
59 -p, --policy <policy>
62 This sets the policy xdp-filter applies to packets not matched by any
63 of the filter rules. The default is allow, in which packets not match‐
64 ing any rules are allowed to pass. The other option is deny, in which
65 all packets are dropped except those matched by the filter options.
66 xdp-filter cannot be loaded simultaneously in deny and allow policy
69 modes on the system. Note that loading xdp-filter in deny mode will
70 drop all traffic on the interface until suitable allow rules are in‐
71 stalled, so some care is needed to avoid being locked out of a remote
72 system.
73 -f, --features <feats>
76 Use this option to select which features to include when loaded
77 xdp-filter. The default is to load all available features. So select
78 individual features specify one or more of these:
79 • tcp: Support filtering on TCP port number
82 • udp: Support filtering on UDP port number
84 • ipv6: Support filtering on IPv6 addresses
86 • ipv4: Support filtering on IPv4 addresses
88 • ethernet: Support filtering on Ethernet MAC addresses
90 Specify multiple features by separating them with a comma. E.g.:
93 tcp,udp,ipv6.
94 -v, --verbose
97 Enable debug logging. Specify twice for even more verbosity.
98 -h, --help
101 Display a summary of the available options
102
105 The unload command unloads xdp-filter from one (or all) interfaces, and
106 cleans up the program state.
107 The syntax for the load command is:
110 xdp-filter unload [options] <ifname>
113 Where <ifname> is the name of the interface to unload xdp-filter from,
116 and must be specified unless the --all option is used. The supported
117 options are:
118 -a, --all
121 Specify this option to remove xdp-filter from all interfaces it was
122 loaded onto. If this option is specified, no <ifname> is needed.
123 This option can also be used to clean up all xdp-filter state if the
126 XDP program(s) were unloaded by other means.
127 -k, --keep-maps
130 Specify this option to prevent xdp-filter from clearing its map state.
131 By default, all BPF maps no longer needed by any loaded program are re‐
132 moved. However, this will also remove the contents of the maps (the
133 filtering rules), so this option can be used to keep the maps around so
134 the rules persist until xdp-filter is loaded again.
135 -v, --verbose
138 Enable debug logging. Specify twice for even more verbosity.
139 -h, --help
142 Display a summary of the available options
143
146 Use the port command to add a TCP or UDP port to the xdp-filter match
147 list. For this to work, xdp-filter must be loaded with either the udp
148 or the tcp feature (or both) on at least one interface.
149 The syntax for the port command is:
152 xdp-filter port [options] <port>
155 Where <port> is the port number to add (or remove if the --remove is
158 specified). The supported options are:
159 -r, --remove
162 Remove the port instead of adding it.
163 -m, --mode <mode>
166 Select filtering mode. Valid options are src and dst, both of which may
167 be specified as src,dst. If src is specified, the port number will
168 added as a source port match, while if dst is specified, the port num‐
169 ber will be added as a destination port match. If both are specified, a
170 packet will be matched if either its source or destination port is the
171 specified port number.
172 -p, --proto <proto>
175 Specify one (or both) of udp and/or tcp to match UDP or TCP ports, re‐
176 spectively.
177 -s, --status
180 If this option is specified, the current list of matched ports will be
181 printed after inserting the port number. Otherwise, nothing will be
182 printed.
183 -v, --verbose
186 Enable debug logging. Specify twice for even more verbosity.
187 -h, --help
190 Display a summary of the available options
191
195 Use the ip command to add an IPv6 or an IPv4 address to the xdp-filter
196 match list.
197 The syntax for the ip command is:
200 xdp-filter ip [options] <ip>
203 Where <ip> is the IP address to add (or remove if the --remove is spec‐
206 ified). Either IPv4 or IPv6 addresses can be specified, but xdp-filter
207 must be loaded with the corresponding features (ipv4 and ipv6, respec‐
208 tively). The supported options are:
209 -r, --remove
212 Remove the IP address instead of adding it.
213 -m, --mode <mode>
216 Select filtering mode. Valid options are src and dst, both of which may
217 be specified as src,dst. If src is specified, the IP address will added
218 as a source IP match, while if dst is specified, the IP address will be
219 added as a destination IP match. If both are specified, a packet will
220 be matched if either its source or destination IP is the specified IP
221 address.
222 -s, --status
225 If this option is specified, the current list of matched ips will be
226 printed after inserting the IP address. Otherwise, nothing will be
227 printed.
228 -v, --verbose
231 Enable debug logging. Specify twice for even more verbosity.
232 -h, --help
235 Display a summary of the available options
236
239 Use the ether command to add an Ethernet MAC address to the xdp-filter
240 match list. For this to work, xdp-filter must be loaded with either the
241 ethernet feature on at least one interface.
242 The syntax for the ether command is:
245 xdp-filter ether [options] <addr>
248 Where <addr> is the MAC address to add (or remove if the --remove is
251 specified). The supported options are:
252 -r, --remove
255 Remove the MAC address instead of adding it.
256 -m, --mode <mode>
259 Select filtering mode. Valid options are src and dst, both of which may
260 be specified as src,dst. If src is specified, the MAC address will
261 added as a source MAC match, while if dst is specified, the MAC address
262 will be added as a destination MAC match. If both are specified, a
263 packet will be matched if either its source or destination MAC is the
264 specified MAC address.
265 -s, --status
268 If this option is specified, the current list of matched ips will be
269 printed after inserting the MAC address. Otherwise, nothing will be
270 printed.
271 -v, --verbose
274 Enable debug logging. Specify twice for even more verbosity.
275 -h, --help
278 Display a summary of the available options
279
282 The status command prints the current status of xdp-filter: Which in‐
283 terfaces it is loaded on, the current list of rules, and some statis‐
284 tics for how many packets have been processed in total, and how many
285 times each rule has been hit.
286 The syntax for the status command is:
289 xdp-filter status [options]
292 Where the supported options are:
295 -v, --verbose
298 Enable debug logging. Specify twice for even more verbosity.
299 -h, --help
302 Display a summary of the available options
303
306 The poll command periodically polls the xdp-filter statistics map and
307 prints out the total number of packets and bytes processed by xdp-fil‐
308 ter, as well as the number in the last polling interval, converted to
309 packets (and bytes) per second. This can be used to inspect the perfor‐
310 mance of xdp-filter, and to compare the performance of the different
311 feature sets selectable by the load parameter.
312 The syntax for the poll command is:
315 xdp-filter poll [options]
318 Where the supported options are:
321 -i, --interval <interval>
324 The polling interval, in milliseconds. Defaults to 1000 (1 second).
325 -v, --verbose
328 Enable debug logging. Specify twice for even more verbosity.
329 -h, --help
332 Display a summary of the available options
333
336 To filter all packets arriving on port 80 on eth0, issue the following
337 commands:
338 # xdp-filter load eth0 -f tcp,udp
340 # xdp-filter port 80
341 To filter all packets except those from IP address fc00:dead:cafe::1
344 issue the following commands (careful, this can lock you out of remote
345 access!):
346 # xdp-filter load eth0 -f ipv6 -w
348 # xdp-filter ip fc00:dead:cafe::1 -m src
349 To allow packets from either IP fc00:dead:cafe::1 or arriving on port
352 22, issue the following (careful, this can lock you out of remote ac‐
353 cess!):
354 # xdp-filter load eth0 -f ipv6,tcp -w
356 # xdp-filter port 22
357 # xdp-filter ip fc00:dead:cafe::1 -m src
358
361 Please report any bugs on Github: https://github.com/xdp-project/xdp-
362 tools/issues
363
366 xdp-filter was written by Toke Høiland-Jørgensen and Jesper Dangaard
367 Brouer. This man page was written by Toke Høiland-Jørgensen.
368V1.2.6 AUGUST 16, 2022 xdp-filter(8)