1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
#+EXPORT_FILE_NAME: xdp-loader
#+TITLE: xdp-loader
#+OPTIONS: ^:nil
#+MAN_CLASS_OPTIONS: :section-id "8\" \"DATE\" \"VERSION\" \"XDP program loader"
# This file serves both as a README on github, and as the source for the man
# page; the latter through the org-mode man page export support.
# .
# To export the man page, simply use the org-mode exporter; (require 'ox-man) if
# it's not available. There's also a Makefile rule to export it.
* xdp-loader - an XDP program loader
XDP-loader is a simple loader for XDP programs with support for attaching
multiple programs to the same interface. To achieve this it exposes the same
load and unload semantics exposed by the libxdp library. See the =libxdp(3)= man
page for details of how this works, and what kernel features it relies on.
** Running xdp-loader
The syntax for running xdp-loader is:
#+begin_src sh
xdp-loader COMMAND [options]
Where COMMAND can be one of:
load - load an XDP program on an interface
unload - unload an XDP program from an interface
status - show current XDP program status
clean - clean up detached program links in XDP bpffs directory
help - show the list of available commands
#+end_src
Each command, and its options are explained below. Or use =xdp-loader COMMAND
--help= to see the options for each command.
* The LOAD command
The =load= command loads one or more XDP programs onto an interface.
The syntax for the =load= command is:
=xdp-loader load [options] <ifname> <programs>=
Where =<ifname>= is the name of the interface to load the programs onto, and the
=<programs>= is one or more file names containing XDP programs. The programs
will be loaded onto the interface in the order of their preference, as
specified by the program metadata (see *libxdp(3)*).
The supported options are:
** -m, --mode <mode>
Specifies which mode to load the XDP program to be loaded in. The valid values
are 'native', which is the default in-driver XDP mode, 'skb', which causes the
so-called /skb mode/ (also known as /generic XDP/) to be used, 'hw' which causes
the program to be offloaded to the hardware, or 'unspecified' which leaves it up
to the kernel to pick a mode (which it will do by picking native mode if the
driver supports it, or generic mode otherwise). Note that using 'unspecified'
can make it difficult to predict what mode a program will end up being loaded
in. For this reason, the default is 'native'. Note that hardware with support
for the 'hw' mode is rare: Solarflare cards (using the 'sfc' driver) are the
only devices with support for this in the mainline Linux kernel.
** -p, --pin-path <path>
This specifies a root path under which to pin any maps that define the 'pinning'
attribute in their definitions. This path must be located on a =bpffs= file
system. If not set, maps will not be pinned, even if they specify pinning in
their definitions. When pinning maps, if the pinned location for a map already
exist, the map pinned there will be reused if it is compatible with the type of
the map being loaded.
** -s, --section <section>
Specify which ELF section to load the XDP program(s) from in each file. The
default is to use the first program in each file. If this option is set, it
applies to all programs being loaded.
** -n, --prog-name <prog_name>
Specify which BPF program with the name to load the XDP program(s) from in each
file. The default is to use the first program in each file. Only one of
--section and --prog-name may be specified. If this option is set, it applies to
all programs being loaded.
** -P, --prio <priority>
Specify the priority to load the XDP program(s) with (this affects the order of
programs running on the interface). The default is to use the value from the metadata
in the program ELF file, or a value of 50 if the program has no such metadata.
If this option is set, it applies to all programs being loaded.
** -A, --actions <actions>
Specify the "chain call actions" of the loaded XDP program(s). These are the XDP
actions that will cause the next program loaded on the interface to be called,
instead of returning immediately. The default is to use the value set in the metadata
in the program ELF file, or XDP_PASS if no such metadata is set. If this option is set,
it applies to all programs being loaded.
** -v, --verbose
Enable debug logging. Specify twice for even more verbosity.
** -h, --help
Display a summary of the available options
* The UNLOAD command
The =unload= command is used for unloading programs from an interface.
The syntax for the =unload= command is:
=xdp-loader unload [options] <ifname>=
Where =<ifname>= is the name of the interface to load the programs onto. Either
the =--all= or =--id= options must be used to specify which program(s) to unload.
The supported options are:
** -i, --id <id>
Unload a single program from the interface by ID. Use =xdp-loader status= to
obtain the ID of the program being unloaded. If this program is the last program
loaded on the interface, the dispatcher program will also be removed, which
makes the operation equivalent to specifying =--all=.
** -a, --all
Unload all XDP programs on the interface, as well as the multi-program
dispatcher.
** -v, --verbose
Enable debug logging. Specify twice for even more verbosity.
** -h, --help
Display a summary of the available options
* The STATUS command
The =status= command displays a list of interfaces in the system, and the XDP
program(s) loaded on each interface. For each interface, a list of programs are
shown, with the run priority and "chain actions" for each program. See the
section on program metadata for the meaning of this metadata.
** -v, --verbose
Enable debug logging. Specify twice for even more verbosity.
** -h, --help
Display a summary of the available options
* The CLEAN command
The syntax for the =clean= command is:
=xdp-loader clean [options] [ifname]=
The =clean= command cleans up any detached program links in the XDP bpffs
directory. When a network interface disappears, any programs loaded in software
mode (e.g. skb, native) remain pinned in the bpffs directory, but become
detached from the interface. These need to be unlinked from the filesystem. The
=clean= command takes an optional interface parameter to only unlink detached
programs corresponding to the interface. By default, all detached programs for
all interfaces are unlinked.
The supported options are:
** -v, --verbose
Enable debug logging. Specify twice for even more verbosity.
** -h, --help
Display a summary of the available options
* Examples
To load an XDP program on the eth0 interface simply do:
#+begin_src sh
# xdp-loader load eth0 xdp_drop.o
# xdp-loader status
CURRENT XDP PROGRAM STATUS:
Interface Prio Program name Mode ID Tag Chain actions
-------------------------------------------------------------------------------------
lo <no XDP program>
eth0 xdp_dispatcher native 50 d51e469e988d81da
=> 50 xdp_drop 55 57cd311f2e27366b XDP_PASS
#+end_src
Which shows that a dispatcher program was loaded on the interface, and the
xdp_drop program was installed as the first (and only) component program after
it. In this instance, the program does not specify any of the metadata above, so
the defaults (priority 50 and XDP_PASS as its chain call action) was used.
To use the automatic map pinning, include the =pinning= attribute into the map
definition in the program, something like:
#+begin_src c
struct {
__uint(type, BPF_MAP_TYPE_ARRAY);
__uint(max_entries, 10);
__type(key, __u32);
__type(value, __u64);
__uint(pinning, LIBBPF_PIN_BY_NAME);
} my_map SEC(".maps");
#+end_src
And load it with the =--pin-path= attribute:
#+begin_src sh
# xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
#+end_src
This will pin the map at =/sys/fs/bpf/my-prog/my_map=. If this already exists,
the pinned map will be reused instead of creating a new one, which allows
different BPF programs to share the map.
* SEE ALSO
=libxdp(3)= for details on the XDP loading semantics and kernel compatibility
requirements.
* BUGS
Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues
* AUTHOR
xdp-loader and this man page were written by Toke Høiland-Jørgensen.
|
