1xdp-filter(8) A simple XDP-powered packet filter xdp-filter(8)
2
6 XDP-filter is a packet filtering utility powered by XDP. It is deliber‐
7 ately simple and so does not have the same matching capabilities as,
8 e.g., netfilter. Instead, thanks to XDP, it can achieve very high drop
9 rates: tens of millions of packets per second on a single CPU core.
10 Running xdp-filter
13 The syntax for running xdp-filter is:
14 xdp-filter COMMAND [options]
16 Where COMMAND can be one of:
18 load - load xdp-filter on an interface
19 unload - unload xdp-filter from an interface
20 port - add a port to the filter list
21 ip - add an IP address to the filter list
22 ether - add an Ethernet MAC address to the filter list
23 status - show current xdp-filter status
24 poll - poll statistics output
25 help - show the list of available commands
26 Each command, and its options are explained below. Or use xdp-filter
29 COMMAND --help to see the options for each command.
30
33 To use xdp-filter, it must first be loaded onto an interface. This is
34 accomplished with the load command, which takes the name of the inter‐
35 face as a parameter, and optionally allows specifying the features that
36 should be included. By default all features are loaded, but de-select‐
37 ing some features can speed up the packet matching, and increase per‐
38 formance by a substantial amount.
39 The syntax for the load command is:
42 xdp-filter load [options] <ifname>
45 Where <ifname> is the name of the interface to load xdp-filter onto,
48 and must be specified. The supported options are:
49 -m, --mode <mode>
52 Specifies which mode to load the XDP program to be loaded in. The valid
53 values are 'native', which is the default in-driver XDP mode, 'skb',
54 which causes the so-called skb mode (also known as generic XDP) to be
55 used, or 'hw' which causes the program to be offloaded to the hardware.
56 -p, --policy <policy>
59 This sets the policy xdp-filter applies to packets not matched by any
60 of the filter rules. The default is allow, in which packets not match‐
61 ing any rules are allowed to pass. The other option is deny, in which
62 all packets are dropped except those matched by the filter options.
63 xdp-filter cannot be loaded simultaneously in deny and allow policy
66 modes on the system. Note that loading xdp-filter in deny mode will
67 drop all traffic on the interface until suitable allow rules are in‐
68 stalled, so some care is needed to avoid being locked out of a remote
69 system.
70 -f, --features <feats>
73 Use this option to select which features to include when loaded
74 xdp-filter. The default is to load all available features. So select
75 individual features specify one or more of these:
76 • tcp: Support filtering on TCP port number
79 • udp: Support filtering on UDP port number
81 • ipv6: Support filtering on IPv6 addresses
83 • ipv4: Support filtering on IPv4 addresses
85 • ethernet: Support filtering on Ethernet MAC addresses
87 Specify multiple features by separating them with a comma. E.g.:
90 tcp,udp,ipv6.
91 -v, --verbose
94 Enable debug logging. Specify twice for even more verbosity.
95 -h, --help
98 Display a summary of the available options
99
102 The unload command unloads xdp-filter from one (or all) interfaces, and
103 cleans up the program state.
104 The syntax for the load command is:
107 xdp-filter unload [options] <ifname>
110 Where <ifname> is the name of the interface to unload xdp-filter from,
113 and must be specified unless the --all option is used. The supported
114 options are:
115 -a, --all
118 Specify this option to remove xdp-filter from all interfaces it was
119 loaded onto. If this option is specified, no <ifname> is needed.
120 This option can also be used to clean up all xdp-filter state if the
123 XDP program(s) were unloaded by other means.
124 -k, --keep-maps
127 Specify this option to prevent xdp-filter from clearing its map state.
128 By default, all BPF maps no longer needed by any loaded program are re‐
129 moved. However, this will also remove the contents of the maps (the
130 filtering rules), so this option can be used to keep the maps around so
131 the rules persist until xdp-filter is loaded again.
132 -v, --verbose
135 Enable debug logging. Specify twice for even more verbosity.
136 -h, --help
139 Display a summary of the available options
140
143 Use the port command to add a TCP or UDP port to the xdp-filter match
144 list. For this to work, xdp-filter must be loaded with either the udp
145 or the tcp feature (or both) on at least one interface.
146 The syntax for the port command is:
149 xdp-filter port [options] <port>
152 Where <port> is the port number to add (or remove if the --remove is
155 specified). The supported options are:
156 -r, --remove
159 Remove the port instead of adding it.
160 -m, --mode <mode>
163 Select filtering mode. Valid options are src and dst, both of which may
164 be specified as src,dst. If src is specified, the port number will
165 added as a source port match, while if dst is specified, the port num‐
166 ber will be added as a destination port match. If both are specified, a
167 packet will be matched if either its source or destination port is the
168 specified port number.
169 -p, --proto <proto>
172 Specify one (or both) of udp and/or tcp to match UDP or TCP ports, re‐
173 spectively.
174 -s, --status
177 If this option is specified, the current list of matched ports will be
178 printed after inserting the port number. Otherwise, nothing will be
179 printed.
180 -v, --verbose
183 Enable debug logging. Specify twice for even more verbosity.
184 -h, --help
187 Display a summary of the available options
188
192 Use the ip command to add an IPv6 or an IPv4 address to the xdp-filter
193 match list.
194 The syntax for the ip command is:
197 xdp-filter ip [options] <ip>
200 Where <ip> is the IP address to add (or remove if the --remove is spec‐
203 ified). Either IPv4 or IPv6 addresses can be specified, but xdp-filter
204 must be loaded with the corresponding features (ipv4 and ipv6, respec‐
205 tively). The supported options are:
206 -r, --remove
209 Remove the IP address instead of adding it.
210 -m, --mode <mode>
213 Select filtering mode. Valid options are src and dst, both of which may
214 be specified as src,dst. If src is specified, the IP address will added
215 as a source IP match, while if dst is specified, the IP address will be
216 added as a destination IP match. If both are specified, a packet will
217 be matched if either its source or destination IP is the specified IP
218 address.
219 -s, --status
222 If this option is specified, the current list of matched ips will be
223 printed after inserting the IP address. Otherwise, nothing will be
224 printed.
225 -v, --verbose
228 Enable debug logging. Specify twice for even more verbosity.
229 -h, --help
232 Display a summary of the available options
233
236 Use the ether command to add an Ethernet MAC address to the xdp-filter
237 match list. For this to work, xdp-filter must be loaded with either the
238 ethernet feature on at least one interface.
239 The syntax for the ether command is:
242 xdp-filter ether [options] <addr>
245 Where <addr> is the MAC address to add (or remove if the --remove is
248 specified). The supported options are:
249 -r, --remove
252 Remove the MAC address instead of adding it.
253 -m, --mode <mode>
256 Select filtering mode. Valid options are src and dst, both of which may
257 be specified as src,dst. If src is specified, the MAC address will
258 added as a source MAC match, while if dst is specified, the MAC address
259 will be added as a destination MAC match. If both are specified, a
260 packet will be matched if either its source or destination MAC is the
261 specified MAC address.
262 -s, --status
265 If this option is specified, the current list of matched ips will be
266 printed after inserting the MAC address. Otherwise, nothing will be
267 printed.
268 -v, --verbose
271 Enable debug logging. Specify twice for even more verbosity.
272 -h, --help
275 Display a summary of the available options
276
279 The status command prints the current status of xdp-filter: Which in‐
280 terfaces it is loaded on, the current list of rules, and some statis‐
281 tics for how many packets have been processed in total, and how many
282 times each rule has been hit.
283 The syntax for the status command is:
286 xdp-filter status [options]
289 Where the supported options are:
292 -v, --verbose
295 Enable debug logging. Specify twice for even more verbosity.
296 -h, --help
299 Display a summary of the available options
300
303 The poll command periodically polls the xdp-filter statistics map and
304 prints out the total number of packets and bytes processed by xdp-fil‐
305 ter, as well as the number in the last polling interval, converted to
306 packets (and bytes) per second. This can be used to inspect the perfor‐
307 mance of xdp-filter, and to compare the performance of the different
308 feature sets selectable by the load parameter.
309 The syntax for the poll command is:
312 xdp-filter poll [options]
315 Where the supported options are:
318 -i, --interval <interval>
321 The polling interval, in milliseconds. Defaults to 1000 (1 second).
322 -v, --verbose
325 Enable debug logging. Specify twice for even more verbosity.
326 -h, --help
329 Display a summary of the available options
330
333 To filter all packets arriving on port 80 on eth0, issue the following
334 commands:
335 # xdp-filter load eth0 -f tcp,udp
337 # xdp-filter port 80
338 To filter all packets except those from IP address fc00:dead:cafe::1
341 issue the following commands (careful, this can lock you out of remote
342 access!):
343 # xdp-filter load eth0 -f ipv6 -w
345 # xdp-filter ip fc00:dead:cafe::1 -m src
346 To allow packets from either IP fc00:dead:cafe::1 or arriving on port
349 22, issue the following (careful, this can lock you out of remote ac‐
350 cess!):
351 # xdp-filter load eth0 -f ipv6,tcp -w
353 # xdp-filter port 22
354 # xdp-filter ip fc00:dead:cafe::1 -m src
355
358 Please report any bugs on Github: https://github.com/xdp-project/xdp-
359 tools/issues
360
363 xdp-filter was written by Toke Høiland-Jørgensen and Jesper Dangaard
364 Brouer. This man page was written by Toke Høiland-Jørgensen.
365V1.2.3 FEBRUARY 17, 2022 xdp-filter(8)