1xdp-filter(1) A simple XDP-powered packet filter xdp-filter(1)
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 blacklist
21 ip - add an IP address to the blacklist
22 ether - add an Ethernet MAC address to the blacklist
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 unto 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 unto,
48 and must be specified. The supported options are:
49 -F, --force
52 Specifying this option causes xdp-filter to unload any XDP program
53 already loaded on the interface.
54 -s, --skb-mode
57 Specifying this option causes the XDP program to be loaded in the so-
58 called skb mode (also known as generic XDP). This is a compatibility
59 mode that results in lower performance, but can be used on all network
60 interfaces (whereas the default native XDP mode requires specific
61 driver support).
62 -w, --whitelist
65 This option causes xdp-filter to run in whitelist mode instead of the
66 default blacklist mode. In whitelist mode, all packets are dropped
67 except those matched by the filter options, whereas in blacklist mode,
68 only the packets matched by the specified rules are dropped.
69 xdp-filter cannot be loaded simultaneously in whitelist and blacklist
72 mode on the 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 unto. 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
132 removed. 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,
176 respectively.
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
283 interfaces 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 Please report any bugs on Github: https://github.com/xdp-project/xdp-
337 tools/issues
338
341 xdp-filter was written by Toke Høiland-Jørgensen and Jesper Dangaard
342 Brouer. This man page was written by Toke Høiland-Jørgensen.
343v0.0.1 November 19, 2019 xdp-filter(1)