1xdp-filter(8)         A simple XDP-powered packet filter         xdp-filter(8)
2
3
4

XDP-filter - a simple XDP-powered packet filter

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
11
12   Running xdp-filter
13       The syntax for running xdp-filter is:
14
15              xdp-filter COMMAND [options]
16
17              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
27
28       Each command, and its options are explained below.  Or  use  xdp-filter
29       COMMAND --help to see the options for each command.
30
31

The LOAD command

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
40
41       The syntax for the load command is:
42
43
44       xdp-filter load [options] <ifname>
45
46
47       Where <ifname> is the name of the interface to  load  xdp-filter  onto,
48       and must be specified. The supported options are:
49
50
51   -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
57
58   -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
64
65       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
71
72   -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
77
78tcp: Support filtering on TCP port number
79
80udp: Support filtering on UDP port number
81
82ipv6: Support filtering on IPv6 addresses
83
84ipv4: Support filtering on IPv4 addresses
85
86ethernet: Support filtering on Ethernet MAC addresses
87
88
89       Specify  multiple  features  by  separating  them  with  a comma. E.g.:
90       tcp,udp,ipv6.
91
92
93   -v, --verbose
94       Enable debug logging. Specify twice for even more verbosity.
95
96
97   -h, --help
98       Display a summary of the available options
99
100

The UNLOAD command

102       The unload command unloads xdp-filter from one (or all) interfaces, and
103       cleans up the program state.
104
105
106       The syntax for the load command is:
107
108
109       xdp-filter unload [options] <ifname>
110
111
112       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
116
117   -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
121
122       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
125
126   -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
133
134   -v, --verbose
135       Enable debug logging. Specify twice for even more verbosity.
136
137
138   -h, --help
139       Display a summary of the available options
140
141

The PORT command

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
147
148       The syntax for the port command is:
149
150
151       xdp-filter port [options] <port>
152
153
154       Where  <port>  is  the port number to add (or remove if the --remove is
155       specified). The supported options are:
156
157
158   -r, --remove
159       Remove the port instead of adding it.
160
161
162   -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
170
171   -p, --proto <proto>
172       Specify  one (or both) of udp and/or tcp to match UDP or TCP ports, re‐
173       spectively.
174
175
176   -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
181
182   -v, --verbose
183       Enable debug logging. Specify twice for even more verbosity.
184
185
186   -h, --help
187       Display a summary of the available options
188
189
190

The IP command

192       Use the ip command to add an IPv6 or an IPv4 address to the  xdp-filter
193       match list.
194
195
196       The syntax for the ip command is:
197
198
199       xdp-filter ip [options] <ip>
200
201
202       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
207
208   -r, --remove
209       Remove the IP address instead of adding it.
210
211
212   -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
220
221   -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
226
227   -v, --verbose
228       Enable debug logging. Specify twice for even more verbosity.
229
230
231   -h, --help
232       Display a summary of the available options
233
234

The ETHER command

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
240
241       The syntax for the ether command is:
242
243
244       xdp-filter ether [options] <addr>
245
246
247       Where  <addr>  is  the MAC address to add (or remove if the --remove is
248       specified). The supported options are:
249
250
251   -r, --remove
252       Remove the MAC address instead of adding it.
253
254
255   -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
263
264   -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
269
270   -v, --verbose
271       Enable debug logging. Specify twice for even more verbosity.
272
273
274   -h, --help
275       Display a summary of the available options
276
277

The STATUS command

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
284
285       The syntax for the status command is:
286
287
288       xdp-filter status [options]
289
290
291       Where the supported options are:
292
293
294   -v, --verbose
295       Enable debug logging. Specify twice for even more verbosity.
296
297
298   -h, --help
299       Display a summary of the available options
300
301

The POLL command

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
310
311       The syntax for the poll command is:
312
313
314       xdp-filter poll [options]
315
316
317       Where the supported options are:
318
319
320   -i, --interval <interval>
321       The polling interval, in milliseconds. Defaults to 1000 (1 second).
322
323
324   -v, --verbose
325       Enable debug logging. Specify twice for even more verbosity.
326
327
328   -h, --help
329       Display a summary of the available options
330
331

Examples

333       To  filter all packets arriving on port 80 on eth0, issue the following
334       commands:
335
336              # xdp-filter load eth0 -f tcp,udp
337              # xdp-filter port 80
338
339
340       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
344              # xdp-filter load eth0 -f ipv6 -w
345              # xdp-filter ip fc00:dead:cafe::1 -m src
346
347
348       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
352              # xdp-filter load eth0 -f ipv6,tcp -w
353              # xdp-filter port 22
354              # xdp-filter ip fc00:dead:cafe::1 -m src
355
356

BUGS

358       Please report any bugs on  Github:  https://github.com/xdp-project/xdp-
359       tools/issues
360
361

AUTHOR

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.
365
366
367
368V1.2.0                           JULY 24, 2021                   xdp-filter(8)
Impressum