1xdp-loader(8)                 XDP program loader                 xdp-loader(8)
2
3
4

XDP-loader - an XDP program loader

6       XDP-loader is a simple loader for XDP programs with support for attach‐
7       ing multiple programs to the same interface. To achieve this it exposes
8       the same load and unload semantics exposed by the libxdp library.
9
10
11
12   Running xdp-loader
13       The syntax for running xdp-loader is:
14
15              xdp-loader COMMAND [options]
16
17              Where COMMAND can be one of:
18                     load        - load an XDP program on an interface
19                     unload      - unload an XDP program from an interface
20                     status      - show current XDP program status
21                     clean       - clean up detached program links in XDP bpffs directory
22                     help        - show the list of available commands
23
24
25       Each  command,  and  its options are explained below. Or use xdp-loader
26       COMMAND --help to see the options for each command.
27
28

The LOAD command

30       The load command loads one or more XDP programs onto an interface.
31
32
33       The syntax for the load command is:
34
35
36       xdp-loader load [options] <ifname> <programs>
37
38
39       Where <ifname> is the name of the interface to load the programs  onto,
40       and  the  <programs> is one or more file names containing XDP programs.
41       The programs will be loaded onto the interface in the  order  of  their
42       preference, as specified by the program metadata (see libxdp(3)).
43
44
45       The supported options are:
46
47
48   -m, --mode <mode>
49       Specifies which mode to load the XDP program to be loaded in. The valid
50       values are 'native', which is the default in-driver  XDP  mode,  'skb',
51       which  causes  the so-called skb mode (also known as generic XDP) to be
52       used, 'hw' which causes the program to be offloaded to the hardware, or
53       'unspecified' which leaves it up to the kernel to pick a mode (which it
54       will do by picking native mode if the driver supports  it,  or  generic
55       mode otherwise). Note that using 'unspecified' can make it difficult to
56       predict what mode a program will end up being loaded in. For this  rea‐
57       son, the default is 'native'.
58
59
60   -p, --pin-path <path>
61       This  specifies a root path under which to pin any maps that define the
62       'pinning' attribute in their definitions. This path must be located  on
63       a  bpffs file system. If not set, maps will not be pinned, even if they
64       specify pinning in their definitions. When pinning maps, if the  pinned
65       location  for  a map already exist, the map pinned there will be reused
66       if it is compatible with the type of the map being loaded.
67
68
69   -s, --section <section>
70       Specify which ELF section to load the XDP program(s) from in each file.
71       The default is to use the first program in each file. If this option is
72       set, it applies to all programs being loaded.
73
74
75   -v, --verbose
76       Enable debug logging. Specify twice for even more verbosity.
77
78
79   -h, --help
80       Display a summary of the available options
81
82

The UNLOAD command

84       The unload command is used for unloading programs from an interface.
85
86
87       The syntax for the unload command is:
88
89
90       xdp-loader unload [options] <ifname>
91
92
93       Where <ifname> is the name of the interface to load the programs  onto.
94       Either  the  --all  or  --id options must be used to specify which pro‐
95       gram(s) to unload.
96
97
98       The supported options are:
99
100
101   -i, --id <id>
102       Unload a single program from the interface by ID. Use xdp-loader status
103       to  obtain the ID of the program being unloaded. If this program is the
104       last program loaded on the interface, the dispatcher program will  also
105       be removed, which makes the operation equivalent to specifying --all.
106
107
108   -a, --all
109       Unload  all XDP programs on the interface, as well as the multi-program
110       dispatcher.
111
112
113   -v, --verbose
114       Enable debug logging. Specify twice for even more verbosity.
115
116
117   -h, --help
118       Display a summary of the available options
119
120

The STATUS command

122       The status command displays a list of interfaces in the system, and the
123       XDP  program(s) loaded on each interface. For each interface, a list of
124       programs are shown, with the run priority and "chain actions" for  each
125       program.  See  the  section on program metadata for the meaning of this
126       metadata.
127
128
129   -v, --verbose
130       Enable debug logging. Specify twice for even more verbosity.
131
132
133   -h, --help
134       Display a summary of the available options
135
136

The CLEAN command

138       The syntax for the clean command is:
139
140
141       xdp-loader clean [options] [ifname]
142
143
144       The clean command cleans up any detached program links in the XDP bpffs
145       directory.  When a network interface disappears, any programs loaded in
146       software mode (e.g. skb, native) remain pinned in the bpffs  directory,
147       but  become detached from the interface. These need to be unlinked from
148       the filesystem. The clean command takes an optional interface parameter
149       to  only  unlink  detached programs corresponding to the interface.  By
150       default, all detached programs for all interfaces are unlinked.
151
152
153       The supported options are:
154
155
156   -v, --verbose
157       Enable debug logging. Specify twice for even more verbosity.
158
159
160   -h, --help
161       Display a summary of the available options
162
163

Examples

165       To load an XDP program on the eth0 interface simply do:
166
167              # xdp-loader load eth0 xdp_drop.o
168              # xdp-loader status
169
170              CURRENT XDP PROGRAM STATUS:
171
172              Interface        Prio  Program name     Mode     ID   Tag               Chain actions
173              -------------------------------------------------------------------------------------
174              lo               <no XDP program>
175              eth0                   xdp_dispatcher   native   50   d51e469e988d81da
176               =>              50    xdp_drop                  55   57cd311f2e27366b  XDP_PASS
177
178
179
180       Which shows that a dispatcher program was loaded on the interface,  and
181       the  xdp_drop  program  was installed as the first (and only) component
182       program after it. In this instance, the program does not specify any of
183       the  metadata  above,  so the defaults (priority 50 and XDP_PASS as its
184       chain call action) was used.
185
186
187       To use the automatic map pinning, include the  pinning  attribute  into
188       the map definition in the program, something like:
189
190              struct {
191                   __uint(type, BPF_MAP_TYPE_ARRAY);
192                   __uint(max_entries, 10);
193                   __type(key, __u32);
194                   __type(value, __u64);
195                   __uint(pinning, LIBBPF_PIN_BY_NAME);
196              } my_map SEC(".maps");
197
198
199       And load it with the --pin-path attribute:
200
201              # xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
202
203
204       This  will  pin  the map at /sys/fs/bpf/my-prog/my_map. If this already
205       exists, the pinned map will be reused instead of creating  a  new  one,
206       which allows different BPF programs to share the map.
207
208

BUGS

210       Please  report  any bugs on Github: https://github.com/xdp-project/xdp-
211       tools/issues
212
213

AUTHOR

215       xdp-loader and this man page were written by Toke Høiland-Jørgensen.
216
217
218
219V1.2.0                           JULY 24, 2021                   xdp-loader(8)
Impressum