| 1 |
.\" Copyright 2015, Alexei Starovoitov <[email protected]> |
| 2 |
.\" Copyright 2015, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH bpf 2 2026-02-10 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
bpf \- perform a command on an extended BPF map or program |
| 10 |
.SH SYNOPSIS |
| 11 |
.nf |
| 12 |
.B #include <linux/bpf.h> |
| 13 |
.P |
| 14 |
.BI "int bpf(int " cmd ", union bpf_attr *" attr ", unsigned int " size ); |
| 15 |
.fi |
| 16 |
.SH DESCRIPTION |
| 17 |
The |
| 18 |
.BR bpf () |
| 19 |
system call performs a range of operations related to extended |
| 20 |
Berkeley Packet Filters. |
| 21 |
Extended BPF (or eBPF) is similar to |
| 22 |
the original ("classic") BPF (cBPF) used to filter network packets. |
| 23 |
For both cBPF and eBPF programs, |
| 24 |
the kernel statically analyzes the programs before loading them, |
| 25 |
in order to ensure that they cannot harm the running system. |
| 26 |
.P |
| 27 |
eBPF extends cBPF in multiple ways, including the ability to call |
| 28 |
a fixed set of in-kernel helper functions |
| 29 |
.\" See 'enum bpf_func_id' in include/uapi/linux/bpf.h |
| 30 |
(via the |
| 31 |
.B BPF_CALL |
| 32 |
opcode extension provided by eBPF) |
| 33 |
and access shared data structures such as eBPF maps. |
| 34 |
.\" |
| 35 |
.SS Extended BPF Design/Architecture |
| 36 |
eBPF maps are a generic data structure for storage of different data types. |
| 37 |
Data types are generally treated as binary blobs, so a user just specifies |
| 38 |
the size of the key and the size of the value at map-creation time. |
| 39 |
In other words, a key/value for a given map can have an arbitrary structure. |
| 40 |
.P |
| 41 |
A user process can create multiple maps (with key/value-pairs being |
| 42 |
opaque bytes of data) and access them via file descriptors. |
| 43 |
Different eBPF programs can access the same maps in parallel. |
| 44 |
It's up to the user process and eBPF program to decide what they store |
| 45 |
inside maps. |
| 46 |
.P |
| 47 |
There's one special map type, called a program array. |
| 48 |
This type of map stores file descriptors referring to other eBPF programs. |
| 49 |
When a lookup in the map is performed, the program flow is |
| 50 |
redirected in-place to the beginning of another eBPF program and does not |
| 51 |
return back to the calling program. |
| 52 |
The level of nesting has a fixed limit of 32, |
| 53 |
.\" Defined by the kernel constant MAX_TAIL_CALL_CNT in include/linux/bpf.h |
| 54 |
so that infinite loops cannot be crafted. |
| 55 |
At run time, the program file descriptors stored in the map can be modified, |
| 56 |
so program functionality can be altered based on specific requirements. |
| 57 |
All programs referred to in a program-array map must |
| 58 |
have been previously loaded into the kernel via |
| 59 |
.BR bpf (). |
| 60 |
If a map lookup fails, the current program continues its execution. |
| 61 |
See |
| 62 |
.B BPF_MAP_TYPE_PROG_ARRAY |
| 63 |
below for further details. |
| 64 |
.P |
| 65 |
Generally, eBPF programs are loaded by the user process and automatically |
| 66 |
unloaded when the process exits. |
| 67 |
In some cases, for example, |
| 68 |
.BR tc\-bpf (8), |
| 69 |
the program will continue to stay alive inside the kernel even after the |
| 70 |
process that loaded the program exits. |
| 71 |
In that case, |
| 72 |
the tc subsystem holds a reference to the eBPF program after the |
| 73 |
file descriptor has been closed by the user-space program. |
| 74 |
Thus, whether a specific program continues to live inside the kernel |
| 75 |
depends on how it is further attached to a given kernel subsystem |
| 76 |
after it was loaded via |
| 77 |
.BR bpf (). |
| 78 |
.P |
| 79 |
Each eBPF program is a set of instructions that is safe to run until |
| 80 |
its completion. |
| 81 |
An in-kernel verifier statically determines that the eBPF program |
| 82 |
terminates and is safe to execute. |
| 83 |
During verification, the kernel increments reference counts for each of |
| 84 |
the maps that the eBPF program uses, |
| 85 |
so that the attached maps can't be removed until the program is unloaded. |
| 86 |
.P |
| 87 |
eBPF programs can be attached to different events. |
| 88 |
These events can be the arrival of network packets, tracing |
| 89 |
events, classification events by network queueing disciplines |
| 90 |
(for eBPF programs attached to a |
| 91 |
.BR tc (8) |
| 92 |
classifier), and other types that may be added in the future. |
| 93 |
A new event triggers execution of the eBPF program, which |
| 94 |
may store information about the event in eBPF maps. |
| 95 |
Beyond storing data, eBPF programs may call a fixed set of |
| 96 |
in-kernel helper functions. |
| 97 |
.P |
| 98 |
The same eBPF program can be attached to multiple events and different |
| 99 |
eBPF programs can access the same map: |
| 100 |
.P |
| 101 |
.in +4n |
| 102 |
.EX |
| 103 |
tracing tracing tracing packet packet packet |
| 104 |
event A event B event C on eth0 on eth1 on eth2 |
| 105 |
| | | | | \[ha] |
| 106 |
| | | | v | |
| 107 |
\-\-> tracing <\-\- tracing socket tc ingress tc egress |
| 108 |
prog_1 prog_2 prog_3 classifier action |
| 109 |
| | | | prog_4 prog_5 |
| 110 |
|\-\-\- \-\-\-\-\-| |\-\-\-\-\-\-| map_3 | | |
| 111 |
map_1 map_2 \-\-| map_4 |\-\- |
| 112 |
.EE |
| 113 |
.in |
| 114 |
.\" |
| 115 |
.SS Arguments |
| 116 |
The operation to be performed by the |
| 117 |
.BR bpf () |
| 118 |
system call is determined by the |
| 119 |
.I cmd |
| 120 |
argument. |
| 121 |
Each operation takes an accompanying argument, |
| 122 |
provided via |
| 123 |
.IR attr , |
| 124 |
which is a pointer to a union of type |
| 125 |
.I bpf_attr |
| 126 |
(see below). |
| 127 |
The unused fields and padding must be zeroed out before the call. |
| 128 |
The |
| 129 |
.I size |
| 130 |
argument is the size of the union pointed to by |
| 131 |
.IR attr . |
| 132 |
.P |
| 133 |
The value provided in |
| 134 |
.I cmd |
| 135 |
is one of the following: |
| 136 |
.TP |
| 137 |
.B BPF_MAP_CREATE |
| 138 |
Create a map and return a file descriptor that refers to the map. |
| 139 |
The close-on-exec file descriptor flag (see |
| 140 |
.BR fcntl (2)) |
| 141 |
is automatically enabled for the new file descriptor. |
| 142 |
.TP |
| 143 |
.B BPF_MAP_LOOKUP_ELEM |
| 144 |
Look up an element by key in a specified map and return its value. |
| 145 |
.TP |
| 146 |
.B BPF_MAP_UPDATE_ELEM |
| 147 |
Create or update an element (key/value pair) in a specified map. |
| 148 |
.TP |
| 149 |
.B BPF_MAP_DELETE_ELEM |
| 150 |
Look up and delete an element by key in a specified map. |
| 151 |
.TP |
| 152 |
.B BPF_MAP_GET_NEXT_KEY |
| 153 |
Look up an element by key in a specified map and return the key |
| 154 |
of the next element. |
| 155 |
.TP |
| 156 |
.B BPF_PROG_LOAD |
| 157 |
Verify and load an eBPF program, |
| 158 |
returning a new file descriptor associated with the program. |
| 159 |
The close-on-exec file descriptor flag (see |
| 160 |
.BR fcntl (2)) |
| 161 |
is automatically enabled for the new file descriptor. |
| 162 |
.IP |
| 163 |
The |
| 164 |
.I bpf_attr |
| 165 |
union consists of various anonymous structures that are used by different |
| 166 |
.BR bpf () |
| 167 |
commands: |
| 168 |
.P |
| 169 |
.in +4n |
| 170 |
.EX |
| 171 |
union bpf_attr { |
| 172 |
struct { /* Used by BPF_MAP_CREATE */ |
| 173 |
__u32 map_type; |
| 174 |
__u32 key_size; /* size of key in bytes */ |
| 175 |
__u32 value_size; /* size of value in bytes */ |
| 176 |
__u32 max_entries; /* maximum number of entries |
| 177 |
in a map */ |
| 178 |
}; |
| 179 |
\& |
| 180 |
struct { /* Used by BPF_MAP_*_ELEM and BPF_MAP_GET_NEXT_KEY |
| 181 |
commands */ |
| 182 |
__u32 map_fd; |
| 183 |
__aligned_u64 key; |
| 184 |
union { |
| 185 |
__aligned_u64 value; |
| 186 |
__aligned_u64 next_key; |
| 187 |
}; |
| 188 |
__u64 flags; |
| 189 |
}; |
| 190 |
\& |
| 191 |
struct { /* Used by BPF_PROG_LOAD */ |
| 192 |
__u32 prog_type; |
| 193 |
__u32 insn_cnt; |
| 194 |
__aligned_u64 insns; /* \[aq]const struct bpf_insn *\[aq] */ |
| 195 |
__aligned_u64 license; /* \[aq]const char *\[aq] */ |
| 196 |
__u32 log_level; /* verbosity level of verifier */ |
| 197 |
__u32 log_size; /* size of user buffer */ |
| 198 |
__aligned_u64 log_buf; /* user supplied \[aq]char *\[aq] |
| 199 |
buffer */ |
| 200 |
__u32 kern_version; |
| 201 |
/* checked when prog_type=kprobe |
| 202 |
(since Linux 4.1) */ |
| 203 |
.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 |
| 204 |
}; |
| 205 |
} __attribute__((aligned(8))); |
| 206 |
.EE |
| 207 |
.in |
| 208 |
.\" |
| 209 |
.SS eBPF maps |
| 210 |
Maps are a generic data structure for storage of different types of data. |
| 211 |
They allow sharing of data between eBPF kernel programs, |
| 212 |
and also between kernel and user-space applications. |
| 213 |
.P |
| 214 |
Each map type has the following attributes: |
| 215 |
.IP \[bu] 3 |
| 216 |
type |
| 217 |
.IP \[bu] |
| 218 |
maximum number of elements |
| 219 |
.IP \[bu] |
| 220 |
key size in bytes |
| 221 |
.IP \[bu] |
| 222 |
value size in bytes |
| 223 |
.P |
| 224 |
The following wrapper functions demonstrate how various |
| 225 |
.BR bpf () |
| 226 |
commands can be used to access the maps. |
| 227 |
The functions use the |
| 228 |
.I cmd |
| 229 |
argument to invoke different operations. |
| 230 |
.TP |
| 231 |
.B BPF_MAP_CREATE |
| 232 |
The |
| 233 |
.B BPF_MAP_CREATE |
| 234 |
command creates a new map, |
| 235 |
returning a new file descriptor that refers to the map. |
| 236 |
.IP |
| 237 |
.in +4n |
| 238 |
.EX |
| 239 |
int |
| 240 |
bpf_create_map(enum bpf_map_type map_type, |
| 241 |
unsigned int key_size, |
| 242 |
unsigned int value_size, |
| 243 |
unsigned int max_entries) |
| 244 |
{ |
| 245 |
union bpf_attr attr = { |
| 246 |
.map_type = map_type, |
| 247 |
.key_size = key_size, |
| 248 |
.value_size = value_size, |
| 249 |
.max_entries = max_entries |
| 250 |
}; |
| 251 |
\& |
| 252 |
return bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); |
| 253 |
} |
| 254 |
.EE |
| 255 |
.in |
| 256 |
.IP |
| 257 |
The new map has the type specified by |
| 258 |
.IR map_type , |
| 259 |
and attributes as specified in |
| 260 |
.IR key_size , |
| 261 |
.IR value_size , |
| 262 |
and |
| 263 |
.IR max_entries . |
| 264 |
On success, this operation returns a file descriptor. |
| 265 |
On error, \-1 is returned and |
| 266 |
.I errno |
| 267 |
is set to |
| 268 |
.BR EINVAL , |
| 269 |
.BR EPERM , |
| 270 |
or |
| 271 |
.BR ENOMEM . |
| 272 |
.IP |
| 273 |
The |
| 274 |
.I key_size |
| 275 |
and |
| 276 |
.I value_size |
| 277 |
attributes will be used by the verifier during program loading |
| 278 |
to check that the program is calling |
| 279 |
.BR bpf_map_*_elem () |
| 280 |
helper functions with a correctly initialized |
| 281 |
.I key |
| 282 |
and to check that the program doesn't access the map element |
| 283 |
.I value |
| 284 |
beyond the specified |
| 285 |
.IR value_size . |
| 286 |
For example, when a map is created with a |
| 287 |
.I key_size |
| 288 |
of 8 and the eBPF program calls |
| 289 |
.IP |
| 290 |
.in +4n |
| 291 |
.EX |
| 292 |
bpf_map_lookup_elem(map_fd, fp \- 4) |
| 293 |
.EE |
| 294 |
.in |
| 295 |
.IP |
| 296 |
the program will be rejected, |
| 297 |
since the in-kernel helper function |
| 298 |
.IP |
| 299 |
.in +4n |
| 300 |
.EX |
| 301 |
bpf_map_lookup_elem(map_fd, void *key) |
| 302 |
.EE |
| 303 |
.in |
| 304 |
.IP |
| 305 |
expects to read 8 bytes from the location pointed to by |
| 306 |
.IR key , |
| 307 |
but the |
| 308 |
.I fp\ \-\ 4 |
| 309 |
(where |
| 310 |
.I fp |
| 311 |
is the top of the stack) |
| 312 |
starting address will cause out-of-bounds stack access. |
| 313 |
.IP |
| 314 |
Similarly, when a map is created with a |
| 315 |
.I value_size |
| 316 |
of 1 and the eBPF program contains |
| 317 |
.IP |
| 318 |
.in +4n |
| 319 |
.EX |
| 320 |
value = bpf_map_lookup_elem(...); |
| 321 |
*(u32 *) value = 1; |
| 322 |
.EE |
| 323 |
.in |
| 324 |
.IP |
| 325 |
the program will be rejected, since it accesses the |
| 326 |
.I value |
| 327 |
pointer beyond the specified 1 byte |
| 328 |
.I value_size |
| 329 |
limit. |
| 330 |
.IP |
| 331 |
Currently, the following values are supported for |
| 332 |
.IR map_type : |
| 333 |
.IP |
| 334 |
.in +4n |
| 335 |
.EX |
| 336 |
enum bpf_map_type { |
| 337 |
BPF_MAP_TYPE_UNSPEC, /* Reserve 0 as invalid map type */ |
| 338 |
BPF_MAP_TYPE_HASH, |
| 339 |
BPF_MAP_TYPE_ARRAY, |
| 340 |
BPF_MAP_TYPE_PROG_ARRAY, |
| 341 |
BPF_MAP_TYPE_PERF_EVENT_ARRAY, |
| 342 |
BPF_MAP_TYPE_PERCPU_HASH, |
| 343 |
BPF_MAP_TYPE_PERCPU_ARRAY, |
| 344 |
BPF_MAP_TYPE_STACK_TRACE, |
| 345 |
BPF_MAP_TYPE_CGROUP_ARRAY, |
| 346 |
BPF_MAP_TYPE_LRU_HASH, |
| 347 |
BPF_MAP_TYPE_LRU_PERCPU_HASH, |
| 348 |
BPF_MAP_TYPE_LPM_TRIE, |
| 349 |
BPF_MAP_TYPE_ARRAY_OF_MAPS, |
| 350 |
BPF_MAP_TYPE_HASH_OF_MAPS, |
| 351 |
BPF_MAP_TYPE_DEVMAP, |
| 352 |
BPF_MAP_TYPE_SOCKMAP, |
| 353 |
BPF_MAP_TYPE_CPUMAP, |
| 354 |
BPF_MAP_TYPE_XSKMAP, |
| 355 |
BPF_MAP_TYPE_SOCKHASH, |
| 356 |
BPF_MAP_TYPE_CGROUP_STORAGE, |
| 357 |
BPF_MAP_TYPE_REUSEPORT_SOCKARRAY, |
| 358 |
BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE, |
| 359 |
BPF_MAP_TYPE_QUEUE, |
| 360 |
BPF_MAP_TYPE_STACK, |
| 361 |
/* See /usr/include/linux/bpf.h for the full list. */ |
| 362 |
}; |
| 363 |
.EE |
| 364 |
.in |
| 365 |
.IP |
| 366 |
.I map_type |
| 367 |
selects one of the available map implementations in the kernel. |
| 368 |
.\" FIXME We need an explanation of why one might choose each of |
| 369 |
.\" these map implementations |
| 370 |
For all map types, |
| 371 |
eBPF programs access maps with the same |
| 372 |
.BR bpf_map_lookup_elem () |
| 373 |
and |
| 374 |
.BR bpf_map_update_elem () |
| 375 |
helper functions. |
| 376 |
Further details of the various map types are given below. |
| 377 |
.TP |
| 378 |
.B BPF_MAP_LOOKUP_ELEM |
| 379 |
The |
| 380 |
.B BPF_MAP_LOOKUP_ELEM |
| 381 |
command looks up an element with a given |
| 382 |
.I key |
| 383 |
in the map referred to by the file descriptor |
| 384 |
.IR fd . |
| 385 |
.IP |
| 386 |
.in +4n |
| 387 |
.EX |
| 388 |
int |
| 389 |
bpf_lookup_elem(int fd, const void *key, void *value) |
| 390 |
{ |
| 391 |
union bpf_attr attr = { |
| 392 |
.map_fd = fd, |
| 393 |
.key = ptr_to_u64(key), |
| 394 |
.value = ptr_to_u64(value), |
| 395 |
}; |
| 396 |
\& |
| 397 |
return bpf(BPF_MAP_LOOKUP_ELEM, &attr, sizeof(attr)); |
| 398 |
} |
| 399 |
.EE |
| 400 |
.in |
| 401 |
.IP |
| 402 |
If an element is found, |
| 403 |
the operation returns zero and stores the element's value into |
| 404 |
.IR value , |
| 405 |
which must point to a buffer of |
| 406 |
.I value_size |
| 407 |
bytes. |
| 408 |
.IP |
| 409 |
If no element is found, the operation returns \-1 and sets |
| 410 |
.I errno |
| 411 |
to |
| 412 |
.BR ENOENT . |
| 413 |
.TP |
| 414 |
.B BPF_MAP_UPDATE_ELEM |
| 415 |
The |
| 416 |
.B BPF_MAP_UPDATE_ELEM |
| 417 |
command |
| 418 |
creates or updates an element with a given |
| 419 |
.I key/value |
| 420 |
in the map referred to by the file descriptor |
| 421 |
.IR fd . |
| 422 |
.IP |
| 423 |
.in +4n |
| 424 |
.EX |
| 425 |
int |
| 426 |
bpf_update_elem(int fd, const void *key, const void *value, |
| 427 |
uint64_t flags) |
| 428 |
{ |
| 429 |
union bpf_attr attr = { |
| 430 |
.map_fd = fd, |
| 431 |
.key = ptr_to_u64(key), |
| 432 |
.value = ptr_to_u64(value), |
| 433 |
.flags = flags, |
| 434 |
}; |
| 435 |
\& |
| 436 |
return bpf(BPF_MAP_UPDATE_ELEM, &attr, sizeof(attr)); |
| 437 |
} |
| 438 |
.EE |
| 439 |
.in |
| 440 |
.IP |
| 441 |
The |
| 442 |
.I flags |
| 443 |
argument should be specified as one of the following: |
| 444 |
.RS |
| 445 |
.TP |
| 446 |
.B BPF_ANY |
| 447 |
Create a new element or update an existing element. |
| 448 |
.TP |
| 449 |
.B BPF_NOEXIST |
| 450 |
Create a new element only if it did not exist. |
| 451 |
.TP |
| 452 |
.B BPF_EXIST |
| 453 |
Update an existing element. |
| 454 |
.RE |
| 455 |
.IP |
| 456 |
On success, the operation returns zero. |
| 457 |
On error, \-1 is returned and |
| 458 |
.I errno |
| 459 |
is set to |
| 460 |
.BR EINVAL , |
| 461 |
.BR EPERM , |
| 462 |
.BR ENOMEM , |
| 463 |
or |
| 464 |
.BR E2BIG . |
| 465 |
.B E2BIG |
| 466 |
indicates that the number of elements in the map reached the |
| 467 |
.I max_entries |
| 468 |
limit specified at map creation time. |
| 469 |
.B EEXIST |
| 470 |
will be returned if |
| 471 |
.I flags |
| 472 |
specifies |
| 473 |
.B BPF_NOEXIST |
| 474 |
and the element with |
| 475 |
.I key |
| 476 |
already exists in the map. |
| 477 |
.B ENOENT |
| 478 |
will be returned if |
| 479 |
.I flags |
| 480 |
specifies |
| 481 |
.B BPF_EXIST |
| 482 |
and the element with |
| 483 |
.I key |
| 484 |
doesn't exist in the map. |
| 485 |
.TP |
| 486 |
.B BPF_MAP_DELETE_ELEM |
| 487 |
The |
| 488 |
.B BPF_MAP_DELETE_ELEM |
| 489 |
command |
| 490 |
deletes the element whose key is |
| 491 |
.I key |
| 492 |
from the map referred to by the file descriptor |
| 493 |
.IR fd . |
| 494 |
.IP |
| 495 |
.in +4n |
| 496 |
.EX |
| 497 |
int |
| 498 |
bpf_delete_elem(int fd, const void *key) |
| 499 |
{ |
| 500 |
union bpf_attr attr = { |
| 501 |
.map_fd = fd, |
| 502 |
.key = ptr_to_u64(key), |
| 503 |
}; |
| 504 |
\& |
| 505 |
return bpf(BPF_MAP_DELETE_ELEM, &attr, sizeof(attr)); |
| 506 |
} |
| 507 |
.EE |
| 508 |
.in |
| 509 |
.IP |
| 510 |
On success, zero is returned. |
| 511 |
If the element is not found, \-1 is returned and |
| 512 |
.I errno |
| 513 |
is set to |
| 514 |
.BR ENOENT . |
| 515 |
.TP |
| 516 |
.B BPF_MAP_GET_NEXT_KEY |
| 517 |
The |
| 518 |
.B BPF_MAP_GET_NEXT_KEY |
| 519 |
command looks up an element by |
| 520 |
.I key |
| 521 |
in the map referred to by the file descriptor |
| 522 |
.I fd |
| 523 |
and sets the |
| 524 |
.I next_key |
| 525 |
pointer to the key of the next element. |
| 526 |
.IP |
| 527 |
.in +4n |
| 528 |
.EX |
| 529 |
int |
| 530 |
bpf_get_next_key(int fd, const void *key, void *next_key) |
| 531 |
{ |
| 532 |
union bpf_attr attr = { |
| 533 |
.map_fd = fd, |
| 534 |
.key = ptr_to_u64(key), |
| 535 |
.next_key = ptr_to_u64(next_key), |
| 536 |
}; |
| 537 |
\& |
| 538 |
return bpf(BPF_MAP_GET_NEXT_KEY, &attr, sizeof(attr)); |
| 539 |
} |
| 540 |
.EE |
| 541 |
.in |
| 542 |
.IP |
| 543 |
If |
| 544 |
.I key |
| 545 |
is found, the operation returns zero and sets the |
| 546 |
.I next_key |
| 547 |
pointer to the key of the next element. |
| 548 |
If |
| 549 |
.I key |
| 550 |
is not found, the operation returns zero and sets the |
| 551 |
.I next_key |
| 552 |
pointer to the key of the first element. |
| 553 |
If |
| 554 |
.I key |
| 555 |
is the last element, \-1 is returned and |
| 556 |
.I errno |
| 557 |
is set to |
| 558 |
.BR ENOENT . |
| 559 |
Other possible |
| 560 |
.I errno |
| 561 |
values are |
| 562 |
.BR ENOMEM , |
| 563 |
.BR EFAULT , |
| 564 |
.BR EPERM , |
| 565 |
and |
| 566 |
.BR EINVAL . |
| 567 |
This method can be used to iterate over all elements in the map. |
| 568 |
.TP |
| 569 |
.B close(map_fd) |
| 570 |
Delete the map referred to by the file descriptor |
| 571 |
.IR map_fd . |
| 572 |
When the user-space program that created a map exits, all maps will |
| 573 |
be deleted automatically (but see NOTES). |
| 574 |
.\" |
| 575 |
.SS eBPF map types |
| 576 |
The following map types are supported: |
| 577 |
.TP |
| 578 |
.B BPF_MAP_TYPE_HASH |
| 579 |
.\" commit 0f8e4bd8a1fc8c4185f1630061d0a1f2d197a475 |
| 580 |
Hash-table maps have the following characteristics: |
| 581 |
.RS |
| 582 |
.IP \[bu] 3 |
| 583 |
Maps are created and destroyed by user-space programs. |
| 584 |
Both user-space and eBPF programs |
| 585 |
can perform lookup, update, and delete operations. |
| 586 |
.IP \[bu] |
| 587 |
The kernel takes care of allocating and freeing key/value pairs. |
| 588 |
.IP \[bu] |
| 589 |
The |
| 590 |
.BR map_update_elem () |
| 591 |
helper will fail to insert new element when the |
| 592 |
.I max_entries |
| 593 |
limit is reached. |
| 594 |
(This ensures that eBPF programs cannot exhaust memory.) |
| 595 |
.IP \[bu] |
| 596 |
.BR map_update_elem () |
| 597 |
replaces existing elements atomically. |
| 598 |
.RE |
| 599 |
.IP |
| 600 |
Hash-table maps are |
| 601 |
optimized for speed of lookup. |
| 602 |
.TP |
| 603 |
.B BPF_MAP_TYPE_ARRAY |
| 604 |
.\" commit 28fbcfa08d8ed7c5a50d41a0433aad222835e8e3 |
| 605 |
Array maps have the following characteristics: |
| 606 |
.RS |
| 607 |
.IP \[bu] 3 |
| 608 |
Optimized for fastest possible lookup. |
| 609 |
In the future the verifier/JIT compiler |
| 610 |
may recognize lookup() operations that employ a constant key |
| 611 |
and optimize it into constant pointer. |
| 612 |
It is possible to optimize a non-constant |
| 613 |
key into direct pointer arithmetic as well, since pointers and |
| 614 |
.I value_size |
| 615 |
are constant for the life of the eBPF program. |
| 616 |
In other words, |
| 617 |
.BR array_map_lookup_elem () |
| 618 |
may be 'inlined' by the verifier/JIT compiler |
| 619 |
while preserving concurrent access to this map from user space. |
| 620 |
.IP \[bu] |
| 621 |
All array elements pre-allocated and zero initialized at init time |
| 622 |
.IP \[bu] |
| 623 |
The key is an array index, and must be exactly four bytes. |
| 624 |
.IP \[bu] |
| 625 |
.BR map_delete_elem () |
| 626 |
fails with the error |
| 627 |
.BR EINVAL , |
| 628 |
since elements cannot be deleted. |
| 629 |
.IP \[bu] |
| 630 |
.BR map_update_elem () |
| 631 |
replaces elements in a |
| 632 |
.B nonatomic |
| 633 |
fashion; |
| 634 |
for atomic updates, a hash-table map should be used instead. |
| 635 |
There is however one special case that can also be used with arrays: |
| 636 |
the atomic built-in |
| 637 |
.B __sync_fetch_and_add() |
| 638 |
can be used on 32 and 64 bit atomic counters. |
| 639 |
For example, it can be |
| 640 |
applied on the whole value itself if it represents a single counter, |
| 641 |
or in case of a structure containing multiple counters, it could be |
| 642 |
used on individual counters. |
| 643 |
This is quite often useful for aggregation and accounting of events. |
| 644 |
.RE |
| 645 |
.IP |
| 646 |
Among the uses for array maps are the following: |
| 647 |
.RS |
| 648 |
.IP \[bu] 3 |
| 649 |
As "global" eBPF variables: an array of 1 element whose key is (index) 0 |
| 650 |
and where the value is a collection of 'global' variables which |
| 651 |
eBPF programs can use to keep state between events. |
| 652 |
.IP \[bu] |
| 653 |
Aggregation of tracing events into a fixed set of buckets. |
| 654 |
.IP \[bu] |
| 655 |
Accounting of networking events, for example, number of packets and packet |
| 656 |
sizes. |
| 657 |
.RE |
| 658 |
.TP |
| 659 |
.BR BPF_MAP_TYPE_PROG_ARRAY " (since Linux 4.2)" |
| 660 |
A program array map is a special kind of array map whose map values |
| 661 |
contain only file descriptors referring to other eBPF programs. |
| 662 |
Thus, both the |
| 663 |
.I key_size |
| 664 |
and |
| 665 |
.I value_size |
| 666 |
must be exactly four bytes. |
| 667 |
This map is used in conjunction with the |
| 668 |
.BR bpf_tail_call () |
| 669 |
helper. |
| 670 |
.IP |
| 671 |
This means that an eBPF program with a program array map attached to it |
| 672 |
can call from kernel side into |
| 673 |
.IP |
| 674 |
.in +4n |
| 675 |
.EX |
| 676 |
void bpf_tail_call(void *context, void *prog_map, |
| 677 |
unsigned int index); |
| 678 |
.EE |
| 679 |
.in |
| 680 |
.IP |
| 681 |
and therefore replace its own program flow with the one from the program |
| 682 |
at the given program array slot, if present. |
| 683 |
This can be regarded as kind of a jump table to a different eBPF program. |
| 684 |
The invoked program will then reuse the same stack. |
| 685 |
When a jump into the new program has been performed, |
| 686 |
it won't return to the old program anymore. |
| 687 |
.IP |
| 688 |
If no eBPF program is found at the given index of the program array |
| 689 |
(because the map slot doesn't contain a valid program file descriptor, |
| 690 |
the specified lookup index/key is out of bounds, |
| 691 |
or the limit of 32 |
| 692 |
.\" MAX_TAIL_CALL_CNT |
| 693 |
nested calls has been exceed), |
| 694 |
execution continues with the current eBPF program. |
| 695 |
This can be used as a fall-through for default cases. |
| 696 |
.IP |
| 697 |
A program array map is useful, for example, in tracing or networking, to |
| 698 |
handle individual system calls or protocols in their own subprograms and |
| 699 |
use their identifiers as an individual map index. |
| 700 |
This approach may result in performance benefits, |
| 701 |
and also makes it possible to overcome the maximum |
| 702 |
instruction limit of a single eBPF program. |
| 703 |
In dynamic environments, |
| 704 |
a user-space daemon might atomically replace individual subprograms |
| 705 |
at run-time with newer versions to alter overall program behavior, |
| 706 |
for instance, if global policies change. |
| 707 |
.\" |
| 708 |
.SS eBPF programs |
| 709 |
The |
| 710 |
.B BPF_PROG_LOAD |
| 711 |
command is used to load an eBPF program into the kernel. |
| 712 |
The return value for this command is a new file descriptor associated |
| 713 |
with this eBPF program. |
| 714 |
.P |
| 715 |
.in +4n |
| 716 |
.EX |
| 717 |
char bpf_log_buf[LOG_BUF_SIZE]; |
| 718 |
\& |
| 719 |
int |
| 720 |
bpf_prog_load(enum bpf_prog_type type, |
| 721 |
const struct bpf_insn *insns, int insn_cnt, |
| 722 |
const char *license) |
| 723 |
{ |
| 724 |
union bpf_attr attr = { |
| 725 |
.prog_type = type, |
| 726 |
.insns = ptr_to_u64(insns), |
| 727 |
.insn_cnt = insn_cnt, |
| 728 |
.license = ptr_to_u64(license), |
| 729 |
.log_buf = ptr_to_u64(bpf_log_buf), |
| 730 |
.log_size = LOG_BUF_SIZE, |
| 731 |
.log_level = 1, |
| 732 |
}; |
| 733 |
\& |
| 734 |
return bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); |
| 735 |
} |
| 736 |
.EE |
| 737 |
.in |
| 738 |
.P |
| 739 |
.I prog_type |
| 740 |
is one of the available program types: |
| 741 |
.IP |
| 742 |
.in +4n |
| 743 |
.EX |
| 744 |
enum bpf_prog_type { |
| 745 |
BPF_PROG_TYPE_UNSPEC, /* Reserve 0 as invalid |
| 746 |
program type */ |
| 747 |
BPF_PROG_TYPE_SOCKET_FILTER, |
| 748 |
BPF_PROG_TYPE_KPROBE, |
| 749 |
BPF_PROG_TYPE_SCHED_CLS, |
| 750 |
BPF_PROG_TYPE_SCHED_ACT, |
| 751 |
BPF_PROG_TYPE_TRACEPOINT, |
| 752 |
BPF_PROG_TYPE_XDP, |
| 753 |
BPF_PROG_TYPE_PERF_EVENT, |
| 754 |
BPF_PROG_TYPE_CGROUP_SKB, |
| 755 |
BPF_PROG_TYPE_CGROUP_SOCK, |
| 756 |
BPF_PROG_TYPE_LWT_IN, |
| 757 |
BPF_PROG_TYPE_LWT_OUT, |
| 758 |
BPF_PROG_TYPE_LWT_XMIT, |
| 759 |
BPF_PROG_TYPE_SOCK_OPS, |
| 760 |
BPF_PROG_TYPE_SK_SKB, |
| 761 |
BPF_PROG_TYPE_CGROUP_DEVICE, |
| 762 |
BPF_PROG_TYPE_SK_MSG, |
| 763 |
BPF_PROG_TYPE_RAW_TRACEPOINT, |
| 764 |
BPF_PROG_TYPE_CGROUP_SOCK_ADDR, |
| 765 |
BPF_PROG_TYPE_LWT_SEG6LOCAL, |
| 766 |
BPF_PROG_TYPE_LIRC_MODE2, |
| 767 |
BPF_PROG_TYPE_SK_REUSEPORT, |
| 768 |
BPF_PROG_TYPE_FLOW_DISSECTOR, |
| 769 |
/* See /usr/include/linux/bpf.h for the full list. */ |
| 770 |
}; |
| 771 |
.EE |
| 772 |
.in |
| 773 |
.P |
| 774 |
For further details of eBPF program types, see below. |
| 775 |
.P |
| 776 |
The remaining fields of |
| 777 |
.I bpf_attr |
| 778 |
are set as follows: |
| 779 |
.IP \[bu] 3 |
| 780 |
.I insns |
| 781 |
is an array of |
| 782 |
.I "struct bpf_insn" |
| 783 |
instructions. |
| 784 |
.IP \[bu] |
| 785 |
.I insn_cnt |
| 786 |
is the number of instructions in the program referred to by |
| 787 |
.IR insns . |
| 788 |
.IP \[bu] |
| 789 |
.I license |
| 790 |
is a license string, which must be GPL compatible to call helper functions |
| 791 |
marked |
| 792 |
.IR gpl_only . |
| 793 |
(The licensing rules are the same as for kernel modules, |
| 794 |
so that also dual licenses, such as "Dual BSD/GPL", may be used.) |
| 795 |
.IP \[bu] |
| 796 |
.I log_buf |
| 797 |
is a pointer to a caller-allocated buffer in which the in-kernel |
| 798 |
verifier can store the verification log. |
| 799 |
This log is a multi-line string that can be checked by |
| 800 |
the program author in order to understand how the verifier came to |
| 801 |
the conclusion that the eBPF program is unsafe. |
| 802 |
The format of the output can change at any time as the verifier evolves. |
| 803 |
.IP \[bu] |
| 804 |
.I log_size |
| 805 |
size of the buffer pointed to by |
| 806 |
.IR log_buf . |
| 807 |
If the size of the buffer is not large enough to store all |
| 808 |
verifier messages, \-1 is returned and |
| 809 |
.I errno |
| 810 |
is set to |
| 811 |
.BR ENOSPC . |
| 812 |
.IP \[bu] |
| 813 |
.I log_level |
| 814 |
verbosity level of the verifier. |
| 815 |
A value of zero means that the verifier will not provide a log; |
| 816 |
in this case, |
| 817 |
.I log_buf |
| 818 |
must be a null pointer, and |
| 819 |
.I log_size |
| 820 |
must be zero. |
| 821 |
.P |
| 822 |
Applying |
| 823 |
.BR close (2) |
| 824 |
to the file descriptor returned by |
| 825 |
.B BPF_PROG_LOAD |
| 826 |
will unload the eBPF program (but see NOTES). |
| 827 |
.P |
| 828 |
Maps are accessible from eBPF programs and are used to exchange data between |
| 829 |
eBPF programs and between eBPF programs and user-space programs. |
| 830 |
For example, |
| 831 |
eBPF programs can process various events (like kprobe, packets) and |
| 832 |
store their data into a map, |
| 833 |
and user-space programs can then fetch data from the map. |
| 834 |
Conversely, user-space programs can use a map as a configuration mechanism, |
| 835 |
populating the map with values checked by the eBPF program, |
| 836 |
which then modifies its behavior on the fly according to those values. |
| 837 |
.\" |
| 838 |
.\" |
| 839 |
.SS eBPF program types |
| 840 |
The eBPF program type |
| 841 |
.RI ( prog_type ) |
| 842 |
determines the subset of kernel helper functions that the program |
| 843 |
may call. |
| 844 |
The program type also determines the program input (context)\[em]the |
| 845 |
format of |
| 846 |
.I "struct bpf_context" |
| 847 |
(which is the data blob passed into the eBPF program as the first argument). |
| 848 |
.\" |
| 849 |
.\" FIXME |
| 850 |
.\" Somewhere in this page we need a general introduction to the |
| 851 |
.\" bpf_context. For example, how does a BPF program access the |
| 852 |
.\" context? |
| 853 |
.P |
| 854 |
For example, a tracing program does not have the exact same |
| 855 |
subset of helper functions as a socket filter program |
| 856 |
(though they may have some helpers in common). |
| 857 |
Similarly, |
| 858 |
the input (context) for a tracing program is a set of register values, |
| 859 |
while for a socket filter it is a network packet. |
| 860 |
.P |
| 861 |
The set of functions available to eBPF programs of a given type may increase |
| 862 |
in the future. |
| 863 |
.P |
| 864 |
The following program types are supported: |
| 865 |
.TP |
| 866 |
.BR BPF_PROG_TYPE_SOCKET_FILTER " (since Linux 3.19)" |
| 867 |
Currently, the set of functions for |
| 868 |
.B BPF_PROG_TYPE_SOCKET_FILTER |
| 869 |
is: |
| 870 |
.IP |
| 871 |
.in +4n |
| 872 |
.EX |
| 873 |
bpf_map_lookup_elem(map_fd, void *key) |
| 874 |
/* look up key in a map_fd */ |
| 875 |
bpf_map_update_elem(map_fd, void *key, void *value) |
| 876 |
/* update key/value */ |
| 877 |
bpf_map_delete_elem(map_fd, void *key) |
| 878 |
/* delete key in a map_fd */ |
| 879 |
.EE |
| 880 |
.in |
| 881 |
.IP |
| 882 |
The |
| 883 |
.I bpf_context |
| 884 |
argument is a pointer to a |
| 885 |
.IR "struct __sk_buff" . |
| 886 |
.\" FIXME: We need some text here to explain how the program |
| 887 |
.\" accesses __sk_buff. |
| 888 |
.\" See 'struct __sk_buff' and commit 9bac3d6d548e5 |
| 889 |
.\" |
| 890 |
.\" Alexei commented: |
| 891 |
.\" Actually now in case of SOCKET_FILTER, SCHED_CLS, SCHED_ACT |
| 892 |
.\" the program can now access skb fields. |
| 893 |
.\" |
| 894 |
.TP |
| 895 |
.BR BPF_PROG_TYPE_KPROBE " (since Linux 4.1)" |
| 896 |
.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 |
| 897 |
[To be documented] |
| 898 |
.\" FIXME Document this program type |
| 899 |
.\" Describe allowed helper functions for this program type |
| 900 |
.\" Describe bpf_context for this program type |
| 901 |
.\" |
| 902 |
.\" FIXME We need text here to describe 'kern_version' |
| 903 |
.TP |
| 904 |
.BR BPF_PROG_TYPE_SCHED_CLS " (since Linux 4.1)" |
| 905 |
.\" commit 96be4325f443dbbfeb37d2a157675ac0736531a1 |
| 906 |
.\" commit e2e9b6541dd4b31848079da80fe2253daaafb549 |
| 907 |
[To be documented] |
| 908 |
.\" FIXME Document this program type |
| 909 |
.\" Describe allowed helper functions for this program type |
| 910 |
.\" Describe bpf_context for this program type |
| 911 |
.TP |
| 912 |
.BR BPF_PROG_TYPE_SCHED_ACT " (since Linux 4.1)" |
| 913 |
.\" commit 94caee8c312d96522bcdae88791aaa9ebcd5f22c |
| 914 |
.\" commit a8cb5f556b567974d75ea29c15181c445c541b1f |
| 915 |
[To be documented] |
| 916 |
.\" FIXME Document this program type |
| 917 |
.\" Describe allowed helper functions for this program type |
| 918 |
.\" Describe bpf_context for this program type |
| 919 |
.SS Events |
| 920 |
Once a program is loaded, it can be attached to an event. |
| 921 |
Various kernel subsystems have different ways to do so. |
| 922 |
.P |
| 923 |
Since Linux 3.19, |
| 924 |
.\" commit 89aa075832b0da4402acebd698d0411dcc82d03e |
| 925 |
the following call will attach the program |
| 926 |
.I prog_fd |
| 927 |
to the socket |
| 928 |
.IR sockfd , |
| 929 |
which was created by an earlier call to |
| 930 |
.BR socket (2): |
| 931 |
.P |
| 932 |
.in +4n |
| 933 |
.EX |
| 934 |
setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF, |
| 935 |
&prog_fd, sizeof(prog_fd)); |
| 936 |
.EE |
| 937 |
.in |
| 938 |
.P |
| 939 |
Since Linux 4.1, |
| 940 |
.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 |
| 941 |
the following call may be used to attach |
| 942 |
the eBPF program referred to by the file descriptor |
| 943 |
.I prog_fd |
| 944 |
to a perf event file descriptor, |
| 945 |
.IR event_fd , |
| 946 |
that was created by a previous call to |
| 947 |
.BR perf_event_open (2): |
| 948 |
.P |
| 949 |
.in +4n |
| 950 |
.EX |
| 951 |
ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd); |
| 952 |
.EE |
| 953 |
.in |
| 954 |
.\" |
| 955 |
.\" |
| 956 |
.SH RETURN VALUE |
| 957 |
For a successful call, the return value depends on the operation: |
| 958 |
.TP |
| 959 |
.B BPF_MAP_CREATE |
| 960 |
The new file descriptor associated with the eBPF map. |
| 961 |
.TP |
| 962 |
.B BPF_PROG_LOAD |
| 963 |
The new file descriptor associated with the eBPF program. |
| 964 |
.TP |
| 965 |
All other commands |
| 966 |
Zero. |
| 967 |
.P |
| 968 |
On error, \-1 is returned, and |
| 969 |
.I errno |
| 970 |
is set to indicate the error. |
| 971 |
.SH ERRORS |
| 972 |
.TP |
| 973 |
.B E2BIG |
| 974 |
The eBPF program is too large or a map reached the |
| 975 |
.I max_entries |
| 976 |
limit (maximum number of elements). |
| 977 |
.TP |
| 978 |
.B EACCES |
| 979 |
For |
| 980 |
.BR BPF_PROG_LOAD , |
| 981 |
even though all program instructions are valid, the program has been |
| 982 |
rejected because it was deemed unsafe. |
| 983 |
This may be because it may have |
| 984 |
accessed a disallowed memory region or an uninitialized stack/register or |
| 985 |
because the function constraints don't match the actual types or because |
| 986 |
there was a misaligned memory access. |
| 987 |
In this case, it is recommended to call |
| 988 |
.BR bpf () |
| 989 |
again with |
| 990 |
.I log_level = 1 |
| 991 |
and examine |
| 992 |
.I log_buf |
| 993 |
for the specific reason provided by the verifier. |
| 994 |
.TP |
| 995 |
.B EAGAIN |
| 996 |
For |
| 997 |
.BR BPF_PROG_LOAD , |
| 998 |
indicates that needed resources are blocked. |
| 999 |
This happens when the verifier detects pending signals |
| 1000 |
while it is checking the validity of the bpf program. |
| 1001 |
In this case, just call |
| 1002 |
.BR bpf () |
| 1003 |
again with the same parameters. |
| 1004 |
.TP |
| 1005 |
.B EBADF |
| 1006 |
.I fd |
| 1007 |
is not an open file descriptor. |
| 1008 |
.TP |
| 1009 |
.B EFAULT |
| 1010 |
One of the pointers |
| 1011 |
.RI ( key |
| 1012 |
or |
| 1013 |
.I value |
| 1014 |
or |
| 1015 |
.I log_buf |
| 1016 |
or |
| 1017 |
.IR insns ) |
| 1018 |
is outside the accessible address space. |
| 1019 |
.TP |
| 1020 |
.B EINVAL |
| 1021 |
The value specified in |
| 1022 |
.I cmd |
| 1023 |
is not recognized by this kernel. |
| 1024 |
.TP |
| 1025 |
.B EINVAL |
| 1026 |
For |
| 1027 |
.BR BPF_MAP_CREATE , |
| 1028 |
either |
| 1029 |
.I map_type |
| 1030 |
or attributes are invalid. |
| 1031 |
.TP |
| 1032 |
.B EINVAL |
| 1033 |
For |
| 1034 |
.B BPF_MAP_*_ELEM |
| 1035 |
commands, |
| 1036 |
some of the fields of |
| 1037 |
.I "union bpf_attr" |
| 1038 |
that are not used by this command |
| 1039 |
are not set to zero. |
| 1040 |
.TP |
| 1041 |
.B EINVAL |
| 1042 |
For |
| 1043 |
.BR BPF_PROG_LOAD , |
| 1044 |
indicates an attempt to load an invalid program. |
| 1045 |
eBPF programs can be deemed |
| 1046 |
invalid due to unrecognized instructions, the use of reserved fields, jumps |
| 1047 |
out of range, infinite loops or calls of unknown functions. |
| 1048 |
.TP |
| 1049 |
.B ENOENT |
| 1050 |
For |
| 1051 |
.B BPF_MAP_LOOKUP_ELEM |
| 1052 |
or |
| 1053 |
.BR BPF_MAP_DELETE_ELEM , |
| 1054 |
indicates that the element with the given |
| 1055 |
.I key |
| 1056 |
was not found. |
| 1057 |
.TP |
| 1058 |
.B ENOMEM |
| 1059 |
Cannot allocate sufficient memory. |
| 1060 |
.TP |
| 1061 |
.B EPERM |
| 1062 |
The call was made without sufficient privilege |
| 1063 |
(without the |
| 1064 |
.B CAP_SYS_ADMIN |
| 1065 |
capability). |
| 1066 |
.SH STANDARDS |
| 1067 |
Linux. |
| 1068 |
.SH HISTORY |
| 1069 |
Linux 3.18. |
| 1070 |
.SH NOTES |
| 1071 |
Prior to Linux 4.4, all |
| 1072 |
.BR bpf () |
| 1073 |
commands require the caller to have the |
| 1074 |
.B CAP_SYS_ADMIN |
| 1075 |
capability. |
| 1076 |
From Linux 4.4 onwards, |
| 1077 |
.\" commit 1be7f75d1668d6296b80bf35dcf6762393530afc |
| 1078 |
an unprivileged user may create limited programs of type |
| 1079 |
.B BPF_PROG_TYPE_SOCKET_FILTER |
| 1080 |
and associated maps. |
| 1081 |
However they may not store kernel pointers within |
| 1082 |
the maps and are presently limited to the following helper functions: |
| 1083 |
.\" [Linux 5.6] mtk: The list of available functions is, I think, governed |
| 1084 |
.\" by the check in net/core/filter.c::bpf_base_func_proto(). |
| 1085 |
.IP \[bu] 3 |
| 1086 |
get_random |
| 1087 |
.PD 0 |
| 1088 |
.IP \[bu] |
| 1089 |
get_smp_processor_id |
| 1090 |
.IP \[bu] |
| 1091 |
tail_call |
| 1092 |
.IP \[bu] |
| 1093 |
ktime_get_ns |
| 1094 |
.PD |
| 1095 |
.P |
| 1096 |
Unprivileged access may be blocked by writing the value 1 to the file |
| 1097 |
.IR /proc/sys/kernel/unprivileged_bpf_disabled . |
| 1098 |
.P |
| 1099 |
eBPF objects (maps and programs) can be shared between processes. |
| 1100 |
For example, after |
| 1101 |
.BR fork (2), |
| 1102 |
the child inherits file descriptors referring to the same eBPF objects. |
| 1103 |
In addition, file descriptors referring to eBPF objects can be |
| 1104 |
transferred over UNIX domain sockets. |
| 1105 |
File descriptors referring to eBPF objects can be duplicated |
| 1106 |
in the usual way, using |
| 1107 |
.BR dup (2) |
| 1108 |
and similar calls. |
| 1109 |
An eBPF object is deallocated only after all file descriptors |
| 1110 |
referring to the object have been closed. |
| 1111 |
.P |
| 1112 |
eBPF programs can be written in a restricted C that is compiled (using the |
| 1113 |
.B clang |
| 1114 |
compiler) into eBPF bytecode. |
| 1115 |
Various features are omitted from this restricted C, such as loops, |
| 1116 |
global variables, variadic functions, floating-point numbers, |
| 1117 |
and passing structures as function arguments. |
| 1118 |
Some examples can be found in the |
| 1119 |
.I samples/bpf/*_kern.c |
| 1120 |
files in the kernel source tree. |
| 1121 |
.\" There are also examples for the tc classifier, in the iproute2 |
| 1122 |
.\" project, in examples/bpf |
| 1123 |
.P |
| 1124 |
The kernel contains a just-in-time (JIT) compiler that translates |
| 1125 |
eBPF bytecode into native machine code for better performance. |
| 1126 |
Before Linux 4.15, |
| 1127 |
the JIT compiler is disabled by default, |
| 1128 |
but its operation can be controlled by writing one of the |
| 1129 |
following integer strings to the file |
| 1130 |
.IR /proc/sys/net/core/bpf_jit_enable : |
| 1131 |
.TP |
| 1132 |
.B 0 |
| 1133 |
Disable JIT compilation (default). |
| 1134 |
.TP |
| 1135 |
.B 1 |
| 1136 |
Normal compilation. |
| 1137 |
.TP |
| 1138 |
.B 2 |
| 1139 |
Debugging mode. |
| 1140 |
The generated opcodes are dumped in hexadecimal into the kernel log. |
| 1141 |
These opcodes can then be disassembled using the program |
| 1142 |
.I tools/net/bpf_jit_disasm.c |
| 1143 |
provided in the kernel source tree. |
| 1144 |
.P |
| 1145 |
Since Linux 4.15, |
| 1146 |
.\" commit 290af86629b25ffd1ed6232c4e9107da031705cb |
| 1147 |
the kernel may be configured with the |
| 1148 |
.B CONFIG_BPF_JIT_ALWAYS_ON |
| 1149 |
option. |
| 1150 |
In this case, the JIT compiler is always enabled, and the |
| 1151 |
.I bpf_jit_enable |
| 1152 |
is initialized to 1 and is immutable. |
| 1153 |
(This kernel configuration option was provided as a mitigation for |
| 1154 |
one of the Spectre attacks against the BPF interpreter.) |
| 1155 |
.P |
| 1156 |
The JIT compiler for eBPF is currently |
| 1157 |
available for the following architectures: |
| 1158 |
.IP \[bu] 3 |
| 1159 |
x86-64 |
| 1160 |
(since Linux 3.18; |
| 1161 |
cBPF since Linux 3.0); |
| 1162 |
.\" commit 0a14842f5a3c0e88a1e59fac5c3025db39721f74 |
| 1163 |
.PD 0 |
| 1164 |
.IP \[bu] |
| 1165 |
ARM32 |
| 1166 |
(since Linux 3.18; |
| 1167 |
cBPF since Linux 3.4); |
| 1168 |
.\" commit ddecdfcea0ae891f782ae853771c867ab51024c2 |
| 1169 |
.IP \[bu] |
| 1170 |
SPARC 32 |
| 1171 |
(since Linux 3.18; |
| 1172 |
cBPF since Linux 3.5); |
| 1173 |
.\" commit 2809a2087cc44b55e4377d7b9be3f7f5d2569091 |
| 1174 |
.IP \[bu] |
| 1175 |
ARM-64 |
| 1176 |
(since Linux 3.18); |
| 1177 |
.\" commit e54bcde3d69d40023ae77727213d14f920eb264a |
| 1178 |
.IP \[bu] |
| 1179 |
s390 |
| 1180 |
(since Linux 4.1; |
| 1181 |
cBPF since Linux 3.7); |
| 1182 |
.\" commit c10302efe569bfd646b4c22df29577a4595b4580 |
| 1183 |
.IP \[bu] |
| 1184 |
PowerPC 64 |
| 1185 |
(since Linux 4.8; |
| 1186 |
cBPF since Linux 3.1); |
| 1187 |
.\" commit 0ca87f05ba8bdc6791c14878464efc901ad71e99 |
| 1188 |
.\" commit 156d0e290e969caba25f1851c52417c14d141b24 |
| 1189 |
.IP \[bu] |
| 1190 |
SPARC 64 |
| 1191 |
(since Linux 4.12); |
| 1192 |
.\" commit 7a12b5031c6b947cc13918237ae652b536243b76 |
| 1193 |
.IP \[bu] |
| 1194 |
x86-32 |
| 1195 |
(since Linux 4.18); |
| 1196 |
.\" commit 03f5781be2c7b7e728d724ac70ba10799cc710d7 |
| 1197 |
.IP \[bu] |
| 1198 |
MIPS 64 |
| 1199 |
(since Linux 4.18; |
| 1200 |
cBPF since Linux 3.16); |
| 1201 |
.\" commit c6610de353da5ca6eee5b8960e838a87a90ead0c |
| 1202 |
.\" commit f381bf6d82f032b7410185b35d000ea370ac706b |
| 1203 |
.IP \[bu] |
| 1204 |
riscv |
| 1205 |
(since Linux 5.1). |
| 1206 |
.\" commit 2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2 |
| 1207 |
.PD |
| 1208 |
.SH EXAMPLES |
| 1209 |
.\" SRC BEGIN (bpf.c) |
| 1210 |
.EX |
| 1211 |
#include <stdcountof.h> |
| 1212 |
\& |
| 1213 |
/* bpf+sockets example: |
| 1214 |
* 1. create array map of 256 elements |
| 1215 |
* 2. load program that counts number of packets received |
| 1216 |
* r0 = skb\->data[ETH_HLEN + offsetof(struct iphdr, protocol)] |
| 1217 |
* map[r0]++ |
| 1218 |
* 3. attach prog_fd to raw socket via setsockopt() |
| 1219 |
* 4. print number of received TCP/UDP packets every second |
| 1220 |
*/ |
| 1221 |
int |
| 1222 |
main(int argc, char *argv[]) |
| 1223 |
{ |
| 1224 |
int sock, map_fd, prog_fd, key; |
| 1225 |
long long value = 0, tcp_cnt, udp_cnt; |
| 1226 |
\& |
| 1227 |
map_fd = bpf_create_map(BPF_MAP_TYPE_ARRAY, sizeof(key), |
| 1228 |
sizeof(value), 256); |
| 1229 |
if (map_fd < 0) { |
| 1230 |
printf("failed to create map \[aq]%s\[aq]\[rs]n", strerror(errno)); |
| 1231 |
/* likely not run as root */ |
| 1232 |
return 1; |
| 1233 |
} |
| 1234 |
\& |
| 1235 |
struct bpf_insn prog[] = { |
| 1236 |
BPF_MOV64_REG(BPF_REG_6, BPF_REG_1), /* r6 = r1 */ |
| 1237 |
BPF_LD_ABS(BPF_B, ETH_HLEN + offsetof(struct iphdr, protocol)), |
| 1238 |
/* r0 = ip\->proto */ |
| 1239 |
BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_0, \-4), |
| 1240 |
/* *(u32 *) (fp \- 4) = r0 */ |
| 1241 |
BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), /* r2 = fp */ |
| 1242 |
BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, \-4), /* r2 = r2 \- 4 */ |
| 1243 |
BPF_LD_MAP_FD(BPF_REG_1, map_fd), /* r1 = map_fd */ |
| 1244 |
BPF_CALL_FUNC(BPF_FUNC_map_lookup_elem), |
| 1245 |
/* r0 = map_lookup(r1, r2) */ |
| 1246 |
BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), |
| 1247 |
/* if (r0 == 0) goto pc+2 */ |
| 1248 |
BPF_MOV64_IMM(BPF_REG_1, 1), /* r1 = 1 */ |
| 1249 |
BPF_XADD(BPF_DW, BPF_REG_0, BPF_REG_1, 0, 0), |
| 1250 |
/* lock *(u64 *) r0 += r1 */ |
| 1251 |
.\" == atomic64_add |
| 1252 |
BPF_MOV64_IMM(BPF_REG_0, 0), /* r0 = 0 */ |
| 1253 |
BPF_EXIT_INSN(), /* return r0 */ |
| 1254 |
}; |
| 1255 |
\& |
| 1256 |
prog_fd = bpf_prog_load(BPF_PROG_TYPE_SOCKET_FILTER, prog, |
| 1257 |
countof(prog), "GPL"); |
| 1258 |
\& |
| 1259 |
sock = open_raw_sock("lo"); |
| 1260 |
\& |
| 1261 |
assert(setsockopt(sock, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, |
| 1262 |
sizeof(prog_fd)) == 0); |
| 1263 |
\& |
| 1264 |
for (;;) { |
| 1265 |
key = IPPROTO_TCP; |
| 1266 |
assert(bpf_lookup_elem(map_fd, &key, &tcp_cnt) == 0); |
| 1267 |
key = IPPROTO_UDP; |
| 1268 |
assert(bpf_lookup_elem(map_fd, &key, &udp_cnt) == 0); |
| 1269 |
printf("TCP %lld UDP %lld packets\[rs]n", tcp_cnt, udp_cnt); |
| 1270 |
sleep(1); |
| 1271 |
} |
| 1272 |
\& |
| 1273 |
return 0; |
| 1274 |
} |
| 1275 |
.EE |
| 1276 |
.\" SRC END |
| 1277 |
.P |
| 1278 |
Some complete working code can be found in the |
| 1279 |
.I samples/bpf |
| 1280 |
directory in the kernel source tree. |
| 1281 |
.SH SEE ALSO |
| 1282 |
.BR seccomp (2), |
| 1283 |
.BR bpf\-helpers (7), |
| 1284 |
.BR socket (7), |
| 1285 |
.BR tc (8), |
| 1286 |
.BR tc\-bpf (8) |
| 1287 |
.P |
| 1288 |
Both classic and extended BPF are explained in the kernel source file |
| 1289 |
.IR Documentation/networking/filter.rst . |