1BPF(2) Linux Programmer's Manual BPF(2)
2
6 bpf - perform a command on an extended BPF map or program
7
9 #include <linux/bpf.h>
10 int bpf(int cmd, union bpf_attr *attr, unsigned int size);
12
14 The bpf() system call performs a range of operations related to ex‐
15 tended Berkeley Packet Filters. Extended BPF (or eBPF) is similar to
16 the original ("classic") BPF (cBPF) used to filter network packets.
17 For both cBPF and eBPF programs, the kernel statically analyzes the
18 programs before loading them, in order to ensure that they cannot harm
19 the running system.
20 eBPF extends cBPF in multiple ways, including the ability to call a
22 fixed set of in-kernel helper functions (via the BPF_CALL opcode exten‐
23 sion provided by eBPF) and access shared data structures such as eBPF
24 maps.
25 Extended BPF Design/Architecture
27 eBPF maps are a generic data structure for storage of different data
28 types. Data types are generally treated as binary blobs, so a user
29 just specifies the size of the key and the size of the value at map-
30 creation time. In other words, a key/value for a given map can have an
31 arbitrary structure.
32 A user process can create multiple maps (with key/value-pairs being
34 opaque bytes of data) and access them via file descriptors. Different
35 eBPF programs can access the same maps in parallel. It's up to the
36 user process and eBPF program to decide what they store inside maps.
37 There's one special map type, called a program array. This type of map
39 stores file descriptors referring to other eBPF programs. When a
40 lookup in the map is performed, the program flow is redirected in-place
41 to the beginning of another eBPF program and does not return back to
42 the calling program. The level of nesting has a fixed limit of 32, so
43 that infinite loops cannot be crafted. At run time, the program file
44 descriptors stored in the map can be modified, so program functionality
45 can be altered based on specific requirements. All programs referred
46 to in a program-array map must have been previously loaded into the
47 kernel via bpf(). If a map lookup fails, the current program continues
48 its execution. See BPF_MAP_TYPE_PROG_ARRAY below for further details.
49 Generally, eBPF programs are loaded by the user process and automati‐
51 cally unloaded when the process exits. In some cases, for example,
52 tc-bpf(8), the program will continue to stay alive inside the kernel
53 even after the process that loaded the program exits. In that case,
54 the tc subsystem holds a reference to the eBPF program after the file
55 descriptor has been closed by the user-space program. Thus, whether a
56 specific program continues to live inside the kernel depends on how it
57 is further attached to a given kernel subsystem after it was loaded via
58 bpf().
59 Each eBPF program is a set of instructions that is safe to run until
61 its completion. An in-kernel verifier statically determines that the
62 eBPF program terminates and is safe to execute. During verification,
63 the kernel increments reference counts for each of the maps that the
64 eBPF program uses, so that the attached maps can't be removed until the
65 program is unloaded.
66 eBPF programs can be attached to different events. These events can be
68 the arrival of network packets, tracing events, classification events
69 by network queueing disciplines (for eBPF programs attached to a tc(8)
70 classifier), and other types that may be added in the future. A new
71 event triggers execution of the eBPF program, which may store informa‐
72 tion about the event in eBPF maps. Beyond storing data, eBPF programs
73 may call a fixed set of in-kernel helper functions.
74 The same eBPF program can be attached to multiple events and different
76 eBPF programs can access the same map:
77 tracing tracing tracing packet packet packet
79 event A event B event C on eth0 on eth1 on eth2
80 | | | | | ^
81 | | | | v |
82 --> tracing <-- tracing socket tc ingress tc egress
83 prog_1 prog_2 prog_3 classifier action
84 | | | | prog_4 prog_5
85 |--- -----| |------| map_3 | |
86 map_1 map_2 --| map_4 |--
87 Arguments
89 The operation to be performed by the bpf() system call is determined by
90 the cmd argument. Each operation takes an accompanying argument, pro‐
91 vided via attr, which is a pointer to a union of type bpf_attr (see be‐
92 low). The size argument is the size of the union pointed to by attr.
93 The value provided in cmd is one of the following:
95 BPF_MAP_CREATE
97 Create a map and return a file descriptor that refers to the
98 map. The close-on-exec file descriptor flag (see fcntl(2)) is
99 automatically enabled for the new file descriptor.
100 BPF_MAP_LOOKUP_ELEM
102 Look up an element by key in a specified map and return its
103 value.
104 BPF_MAP_UPDATE_ELEM
106 Create or update an element (key/value pair) in a specified map.
107 BPF_MAP_DELETE_ELEM
109 Look up and delete an element by key in a specified map.
110 BPF_MAP_GET_NEXT_KEY
112 Look up an element by key in a specified map and return the key
113 of the next element.
114 BPF_PROG_LOAD
116 Verify and load an eBPF program, returning a new file descriptor
117 associated with the program. The close-on-exec file descriptor
118 flag (see fcntl(2)) is automatically enabled for the new file
119 descriptor.
120 The bpf_attr union consists of various anonymous structures that
122 are used by different bpf() commands:
123 union bpf_attr {
125 struct { /* Used by BPF_MAP_CREATE */
126 __u32 map_type;
127 __u32 key_size; /* size of key in bytes */
128 __u32 value_size; /* size of value in bytes */
129 __u32 max_entries; /* maximum number of entries
130 in a map */
131 };
132 struct { /* Used by BPF_MAP_*_ELEM and BPF_MAP_GET_NEXT_KEY
134 commands */
135 __u32 map_fd;
136 __aligned_u64 key;
137 union {
138 __aligned_u64 value;
139 __aligned_u64 next_key;
140 };
141 __u64 flags;
142 };
143 struct { /* Used by BPF_PROG_LOAD */
145 __u32 prog_type;
146 __u32 insn_cnt;
147 __aligned_u64 insns; /* 'const struct bpf_insn *' */
148 __aligned_u64 license; /* 'const char *' */
149 __u32 log_level; /* verbosity level of verifier */
150 __u32 log_size; /* size of user buffer */
151 __aligned_u64 log_buf; /* user supplied 'char *'
152 buffer */
153 __u32 kern_version;
154 /* checked when prog_type=kprobe
155 (since Linux 4.1) */
156 };
157 } __attribute__((aligned(8)));
158 eBPF maps
160 Maps are a generic data structure for storage of different types of
161 data. They allow sharing of data between eBPF kernel programs, and
162 also between kernel and user-space applications.
163 Each map type has the following attributes:
165 * type
167 * maximum number of elements
169 * key size in bytes
171 * value size in bytes
173 The following wrapper functions demonstrate how various bpf() commands
175 can be used to access the maps. The functions use the cmd argument to
176 invoke different operations.
177 BPF_MAP_CREATE
179 The BPF_MAP_CREATE command creates a new map, returning a new
180 file descriptor that refers to the map.
181 int
183 bpf_create_map(enum bpf_map_type map_type,
184 unsigned int key_size,
185 unsigned int value_size,
186 unsigned int max_entries)
187 {
188 union bpf_attr attr = {
189 .map_type = map_type,
190 .key_size = key_size,
191 .value_size = value_size,
192 .max_entries = max_entries
193 };
194 return bpf(BPF_MAP_CREATE, &attr, sizeof(attr));
196 }
197 The new map has the type specified by map_type, and attributes
199 as specified in key_size, value_size, and max_entries. On suc‐
200 cess, this operation returns a file descriptor. On error, -1 is
201 returned and errno is set to EINVAL, EPERM, or ENOMEM.
202 The key_size and value_size attributes will be used by the veri‐
204 fier during program loading to check that the program is calling
205 bpf_map_*_elem() helper functions with a correctly initialized
206 key and to check that the program doesn't access the map element
207 value beyond the specified value_size. For example, when a map
208 is created with a key_size of 8 and the eBPF program calls
209 bpf_map_lookup_elem(map_fd, fp - 4)
211 the program will be rejected, since the in-kernel helper func‐
213 tion
214 bpf_map_lookup_elem(map_fd, void *key)
216 expects to read 8 bytes from the location pointed to by key, but
218 the fp - 4 (where fp is the top of the stack) starting address
219 will cause out-of-bounds stack access.
220 Similarly, when a map is created with a value_size of 1 and the
222 eBPF program contains
223 value = bpf_map_lookup_elem(...);
225 *(u32 *) value = 1;
226 the program will be rejected, since it accesses the value
228 pointer beyond the specified 1 byte value_size limit.
229 Currently, the following values are supported for map_type:
231 enum bpf_map_type {
233 BPF_MAP_TYPE_UNSPEC, /* Reserve 0 as invalid map type */
234 BPF_MAP_TYPE_HASH,
235 BPF_MAP_TYPE_ARRAY,
236 BPF_MAP_TYPE_PROG_ARRAY,
237 BPF_MAP_TYPE_PERF_EVENT_ARRAY,
238 BPF_MAP_TYPE_PERCPU_HASH,
239 BPF_MAP_TYPE_PERCPU_ARRAY,
240 BPF_MAP_TYPE_STACK_TRACE,
241 BPF_MAP_TYPE_CGROUP_ARRAY,
242 BPF_MAP_TYPE_LRU_HASH,
243 BPF_MAP_TYPE_LRU_PERCPU_HASH,
244 BPF_MAP_TYPE_LPM_TRIE,
245 BPF_MAP_TYPE_ARRAY_OF_MAPS,
246 BPF_MAP_TYPE_HASH_OF_MAPS,
247 BPF_MAP_TYPE_DEVMAP,
248 BPF_MAP_TYPE_SOCKMAP,
249 BPF_MAP_TYPE_CPUMAP,
250 BPF_MAP_TYPE_XSKMAP,
251 BPF_MAP_TYPE_SOCKHASH,
252 BPF_MAP_TYPE_CGROUP_STORAGE,
253 BPF_MAP_TYPE_REUSEPORT_SOCKARRAY,
254 BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE,
255 BPF_MAP_TYPE_QUEUE,
256 BPF_MAP_TYPE_STACK,
257 /* See /usr/include/linux/bpf.h for the full list. */
258 };
259 map_type selects one of the available map implementations in the
261 kernel. For all map types, eBPF programs access maps with the
262 same bpf_map_lookup_elem() and bpf_map_update_elem() helper
263 functions. Further details of the various map types are given
264 below.
265 BPF_MAP_LOOKUP_ELEM
267 The BPF_MAP_LOOKUP_ELEM command looks up an element with a given
268 key in the map referred to by the file descriptor fd.
269 int
271 bpf_lookup_elem(int fd, const void *key, void *value)
272 {
273 union bpf_attr attr = {
274 .map_fd = fd,
275 .key = ptr_to_u64(key),
276 .value = ptr_to_u64(value),
277 };
278 return bpf(BPF_MAP_LOOKUP_ELEM, &attr, sizeof(attr));
280 }
281 If an element is found, the operation returns zero and stores
283 the element's value into value, which must point to a buffer of
284 value_size bytes.
285 If no element is found, the operation returns -1 and sets errno
287 to ENOENT.
288 BPF_MAP_UPDATE_ELEM
290 The BPF_MAP_UPDATE_ELEM command creates or updates an element
291 with a given key/value in the map referred to by the file de‐
292 scriptor fd.
293 int
295 bpf_update_elem(int fd, const void *key, const void *value,
296 uint64_t flags)
297 {
298 union bpf_attr attr = {
299 .map_fd = fd,
300 .key = ptr_to_u64(key),
301 .value = ptr_to_u64(value),
302 .flags = flags,
303 };
304 return bpf(BPF_MAP_UPDATE_ELEM, &attr, sizeof(attr));
306 }
307 The flags argument should be specified as one of the following:
309 BPF_ANY
311 Create a new element or update an existing element.
312 BPF_NOEXIST
314 Create a new element only if it did not exist.
315 BPF_EXIST
317 Update an existing element.
318 On success, the operation returns zero. On error, -1 is re‐
320 turned and errno is set to EINVAL, EPERM, ENOMEM, or E2BIG.
321 E2BIG indicates that the number of elements in the map reached
322 the max_entries limit specified at map creation time. EEXIST
323 will be returned if flags specifies BPF_NOEXIST and the element
324 with key already exists in the map. ENOENT will be returned if
325 flags specifies BPF_EXIST and the element with key doesn't exist
326 in the map.
327 BPF_MAP_DELETE_ELEM
329 The BPF_MAP_DELETE_ELEM command deletes the element whose key is
330 key from the map referred to by the file descriptor fd.
331 int
333 bpf_delete_elem(int fd, const void *key)
334 {
335 union bpf_attr attr = {
336 .map_fd = fd,
337 .key = ptr_to_u64(key),
338 };
339 return bpf(BPF_MAP_DELETE_ELEM, &attr, sizeof(attr));
341 }
342 On success, zero is returned. If the element is not found, -1
344 is returned and errno is set to ENOENT.
345 BPF_MAP_GET_NEXT_KEY
347 The BPF_MAP_GET_NEXT_KEY command looks up an element by key in
348 the map referred to by the file descriptor fd and sets the
349 next_key pointer to the key of the next element.
350 int
352 bpf_get_next_key(int fd, const void *key, void *next_key)
353 {
354 union bpf_attr attr = {
355 .map_fd = fd,
356 .key = ptr_to_u64(key),
357 .next_key = ptr_to_u64(next_key),
358 };
359 return bpf(BPF_MAP_GET_NEXT_KEY, &attr, sizeof(attr));
361 }
362 If key is found, the operation returns zero and sets the
364 next_key pointer to the key of the next element. If key is not
365 found, the operation returns zero and sets the next_key pointer
366 to the key of the first element. If key is the last element, -1
367 is returned and errno is set to ENOENT. Other possible errno
368 values are ENOMEM, EFAULT, EPERM, and EINVAL. This method can
369 be used to iterate over all elements in the map.
370 close(map_fd)
372 Delete the map referred to by the file descriptor map_fd. When
373 the user-space program that created a map exits, all maps will
374 be deleted automatically (but see NOTES).
375 eBPF map types
377 The following map types are supported:
378 BPF_MAP_TYPE_HASH
380 Hash-table maps have the following characteristics:
381 * Maps are created and destroyed by user-space programs. Both
383 user-space and eBPF programs can perform lookup, update, and
384 delete operations.
385 * The kernel takes care of allocating and freeing key/value
387 pairs.
388 * The map_update_elem() helper will fail to insert new element
390 when the max_entries limit is reached. (This ensures that
391 eBPF programs cannot exhaust memory.)
392 * map_update_elem() replaces existing elements atomically.
394 Hash-table maps are optimized for speed of lookup.
396 BPF_MAP_TYPE_ARRAY
398 Array maps have the following characteristics:
399 * Optimized for fastest possible lookup. In the future the
401 verifier/JIT compiler may recognize lookup() operations that
402 employ a constant key and optimize it into constant pointer.
403 It is possible to optimize a non-constant key into direct
404 pointer arithmetic as well, since pointers and value_size are
405 constant for the life of the eBPF program. In other words,
406 array_map_lookup_elem() may be 'inlined' by the verifier/JIT
407 compiler while preserving concurrent access to this map from
408 user space.
409 * All array elements pre-allocated and zero initialized at init
411 time
412 * The key is an array index, and must be exactly four bytes.
414 * map_delete_elem() fails with the error EINVAL, since elements
416 cannot be deleted.
417 * map_update_elem() replaces elements in a nonatomic fashion;
419 for atomic updates, a hash-table map should be used instead.
420 There is however one special case that can also be used with
421 arrays: the atomic built-in __sync_fetch_and_add() can be
422 used on 32 and 64 bit atomic counters. For example, it can
423 be applied on the whole value itself if it represents a sin‐
424 gle counter, or in case of a structure containing multiple
425 counters, it could be used on individual counters. This is
426 quite often useful for aggregation and accounting of events.
427 Among the uses for array maps are the following:
429 * As "global" eBPF variables: an array of 1 element whose key
431 is (index) 0 and where the value is a collection of 'global'
432 variables which eBPF programs can use to keep state between
433 events.
434 * Aggregation of tracing events into a fixed set of buckets.
436 * Accounting of networking events, for example, number of pack‐
438 ets and packet sizes.
439 BPF_MAP_TYPE_PROG_ARRAY (since Linux 4.2)
441 A program array map is a special kind of array map whose map
442 values contain only file descriptors referring to other eBPF
443 programs. Thus, both the key_size and value_size must be ex‐
444 actly four bytes. This map is used in conjunction with the
445 bpf_tail_call() helper.
446 This means that an eBPF program with a program array map at‐
448 tached to it can call from kernel side into
449 void bpf_tail_call(void *context, void *prog_map,
451 unsigned int index);
452 and therefore replace its own program flow with the one from the
454 program at the given program array slot, if present. This can
455 be regarded as kind of a jump table to a different eBPF program.
456 The invoked program will then reuse the same stack. When a jump
457 into the new program has been performed, it won't return to the
458 old program anymore.
459 If no eBPF program is found at the given index of the program
461 array (because the map slot doesn't contain a valid program file
462 descriptor, the specified lookup index/key is out of bounds, or
463 the limit of 32 nested calls has been exceed), execution contin‐
464 ues with the current eBPF program. This can be used as a fall-
465 through for default cases.
466 A program array map is useful, for example, in tracing or net‐
468 working, to handle individual system calls or protocols in their
469 own subprograms and use their identifiers as an individual map
470 index. This approach may result in performance benefits, and
471 also makes it possible to overcome the maximum instruction limit
472 of a single eBPF program. In dynamic environments, a user-space
473 daemon might atomically replace individual subprograms at run-
474 time with newer versions to alter overall program behavior, for
475 instance, if global policies change.
476 eBPF programs
478 The BPF_PROG_LOAD command is used to load an eBPF program into the ker‐
479 nel. The return value for this command is a new file descriptor asso‐
480 ciated with this eBPF program.
481 char bpf_log_buf[LOG_BUF_SIZE];
483 int
485 bpf_prog_load(enum bpf_prog_type type,
486 const struct bpf_insn *insns, int insn_cnt,
487 const char *license)
488 {
489 union bpf_attr attr = {
490 .prog_type = type,
491 .insns = ptr_to_u64(insns),
492 .insn_cnt = insn_cnt,
493 .license = ptr_to_u64(license),
494 .log_buf = ptr_to_u64(bpf_log_buf),
495 .log_size = LOG_BUF_SIZE,
496 .log_level = 1,
497 };
498 return bpf(BPF_PROG_LOAD, &attr, sizeof(attr));
500 }
501 prog_type is one of the available program types:
503 enum bpf_prog_type {
505 BPF_PROG_TYPE_UNSPEC, /* Reserve 0 as invalid
506 program type */
507 BPF_PROG_TYPE_SOCKET_FILTER,
508 BPF_PROG_TYPE_KPROBE,
509 BPF_PROG_TYPE_SCHED_CLS,
510 BPF_PROG_TYPE_SCHED_ACT,
511 BPF_PROG_TYPE_TRACEPOINT,
512 BPF_PROG_TYPE_XDP,
513 BPF_PROG_TYPE_PERF_EVENT,
514 BPF_PROG_TYPE_CGROUP_SKB,
515 BPF_PROG_TYPE_CGROUP_SOCK,
516 BPF_PROG_TYPE_LWT_IN,
517 BPF_PROG_TYPE_LWT_OUT,
518 BPF_PROG_TYPE_LWT_XMIT,
519 BPF_PROG_TYPE_SOCK_OPS,
520 BPF_PROG_TYPE_SK_SKB,
521 BPF_PROG_TYPE_CGROUP_DEVICE,
522 BPF_PROG_TYPE_SK_MSG,
523 BPF_PROG_TYPE_RAW_TRACEPOINT,
524 BPF_PROG_TYPE_CGROUP_SOCK_ADDR,
525 BPF_PROG_TYPE_LWT_SEG6LOCAL,
526 BPF_PROG_TYPE_LIRC_MODE2,
527 BPF_PROG_TYPE_SK_REUSEPORT,
528 BPF_PROG_TYPE_FLOW_DISSECTOR,
529 /* See /usr/include/linux/bpf.h for the full list. */
530 };
531 For further details of eBPF program types, see below.
533 The remaining fields of bpf_attr are set as follows:
535 * insns is an array of struct bpf_insn instructions.
537 * insn_cnt is the number of instructions in the program referred to by
539 insns.
540 * license is a license string, which must be GPL compatible to call
542 helper functions marked gpl_only. (The licensing rules are the same
543 as for kernel modules, so that also dual licenses, such as "Dual
544 BSD/GPL", may be used.)
545 * log_buf is a pointer to a caller-allocated buffer in which the in-
547 kernel verifier can store the verification log. This log is a
548 multi-line string that can be checked by the program author in order
549 to understand how the verifier came to the conclusion that the eBPF
550 program is unsafe. The format of the output can change at any time
551 as the verifier evolves.
552 * log_size size of the buffer pointed to by log_buf. If the size of
554 the buffer is not large enough to store all verifier messages, -1 is
555 returned and errno is set to ENOSPC.
556 * log_level verbosity level of the verifier. A value of zero means
558 that the verifier will not provide a log; in this case, log_buf must
559 be a NULL pointer, and log_size must be zero.
560 Applying close(2) to the file descriptor returned by BPF_PROG_LOAD will
562 unload the eBPF program (but see NOTES).
563 Maps are accessible from eBPF programs and are used to exchange data
565 between eBPF programs and between eBPF programs and user-space pro‐
566 grams. For example, eBPF programs can process various events (like
567 kprobe, packets) and store their data into a map, and user-space pro‐
568 grams can then fetch data from the map. Conversely, user-space pro‐
569 grams can use a map as a configuration mechanism, populating the map
570 with values checked by the eBPF program, which then modifies its behav‐
571 ior on the fly according to those values.
572 eBPF program types
574 The eBPF program type (prog_type) determines the subset of kernel
575 helper functions that the program may call. The program type also de‐
576 termines the program input (context)—the format of struct bpf_context
577 (which is the data blob passed into the eBPF program as the first argu‐
578 ment).
579 For example, a tracing program does not have the exact same subset of
581 helper functions as a socket filter program (though they may have some
582 helpers in common). Similarly, the input (context) for a tracing pro‐
583 gram is a set of register values, while for a socket filter it is a
584 network packet.
585 The set of functions available to eBPF programs of a given type may in‐
587 crease in the future.
588 The following program types are supported:
590 BPF_PROG_TYPE_SOCKET_FILTER (since Linux 3.19)
592 Currently, the set of functions for BPF_PROG_TYPE_SOCKET_FILTER
593 is:
594 bpf_map_lookup_elem(map_fd, void *key)
596 /* look up key in a map_fd */
597 bpf_map_update_elem(map_fd, void *key, void *value)
598 /* update key/value */
599 bpf_map_delete_elem(map_fd, void *key)
600 /* delete key in a map_fd */
601 The bpf_context argument is a pointer to a struct __sk_buff.
603 BPF_PROG_TYPE_KPROBE (since Linux 4.1)
605 [To be documented]
606 BPF_PROG_TYPE_SCHED_CLS (since Linux 4.1)
608 [To be documented]
609 BPF_PROG_TYPE_SCHED_ACT (since Linux 4.1)
611 [To be documented]
612 Events
614 Once a program is loaded, it can be attached to an event. Various ker‐
615 nel subsystems have different ways to do so.
616 Since Linux 3.19, the following call will attach the program prog_fd to
618 the socket sockfd, which was created by an earlier call to socket(2):
619 setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF,
621 &prog_fd, sizeof(prog_fd));
622 Since Linux 4.1, the following call may be used to attach the eBPF pro‐
624 gram referred to by the file descriptor prog_fd to a perf event file
625 descriptor, event_fd, that was created by a previous call to
626 perf_event_open(2):
627 ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd);
629
631 For a successful call, the return value depends on the operation:
632 BPF_MAP_CREATE
634 The new file descriptor associated with the eBPF map.
635 BPF_PROG_LOAD
637 The new file descriptor associated with the eBPF program.
638 All other commands
640 Zero.
641 On error, -1 is returned, and errno is set to indicate the error.
643
645 E2BIG The eBPF program is too large or a map reached the max_entries
646 limit (maximum number of elements).
647 EACCES For BPF_PROG_LOAD, even though all program instructions are
649 valid, the program has been rejected because it was deemed un‐
650 safe. This may be because it may have accessed a disallowed
651 memory region or an uninitialized stack/register or because the
652 function constraints don't match the actual types or because
653 there was a misaligned memory access. In this case, it is rec‐
654 ommended to call bpf() again with log_level = 1 and examine
655 log_buf for the specific reason provided by the verifier.
656 EBADF fd is not an open file descriptor.
658 EFAULT One of the pointers (key or value or log_buf or insns) is out‐
660 side the accessible address space.
661 EINVAL The value specified in cmd is not recognized by this kernel.
663 EINVAL For BPF_MAP_CREATE, either map_type or attributes are invalid.
665 EINVAL For BPF_MAP_*_ELEM commands, some of the fields of union
667 bpf_attr that are not used by this command are not set to zero.
668 EINVAL For BPF_PROG_LOAD, indicates an attempt to load an invalid pro‐
670 gram. eBPF programs can be deemed invalid due to unrecognized
671 instructions, the use of reserved fields, jumps out of range,
672 infinite loops or calls of unknown functions.
673 ENOENT For BPF_MAP_LOOKUP_ELEM or BPF_MAP_DELETE_ELEM, indicates that
675 the element with the given key was not found.
676 ENOMEM Cannot allocate sufficient memory.
678 EPERM The call was made without sufficient privilege (without the
680 CAP_SYS_ADMIN capability).
681
683 The bpf() system call first appeared in Linux 3.18.
684
686 The bpf() system call is Linux-specific.
687
689 Prior to Linux 4.4, all bpf() commands require the caller to have the
690 CAP_SYS_ADMIN capability. From Linux 4.4 onwards, an unprivileged user
691 may create limited programs of type BPF_PROG_TYPE_SOCKET_FILTER and as‐
692 sociated maps. However they may not store kernel pointers within the
693 maps and are presently limited to the following helper functions:
694 * get_random
696 * get_smp_processor_id
697 * tail_call
698 * ktime_get_ns
699 Unprivileged access may be blocked by writing the value 1 to the file
701 /proc/sys/kernel/unprivileged_bpf_disabled.
702 eBPF objects (maps and programs) can be shared between processes. For
704 example, after fork(2), the child inherits file descriptors referring
705 to the same eBPF objects. In addition, file descriptors referring to
706 eBPF objects can be transferred over UNIX domain sockets. File de‐
707 scriptors referring to eBPF objects can be duplicated in the usual way,
708 using dup(2) and similar calls. An eBPF object is deallocated only af‐
709 ter all file descriptors referring to the object have been closed.
710 eBPF programs can be written in a restricted C that is compiled (using
712 the clang compiler) into eBPF bytecode. Various features are omitted
713 from this restricted C, such as loops, global variables, variadic func‐
714 tions, floating-point numbers, and passing structures as function argu‐
715 ments. Some examples can be found in the samples/bpf/*_kern.c files in
716 the kernel source tree.
717 The kernel contains a just-in-time (JIT) compiler that translates eBPF
719 bytecode into native machine code for better performance. In kernels
720 before Linux 4.15, the JIT compiler is disabled by default, but its op‐
721 eration can be controlled by writing one of the following integer
722 strings to the file /proc/sys/net/core/bpf_jit_enable:
723 0 Disable JIT compilation (default).
725 1 Normal compilation.
727 2 Debugging mode. The generated opcodes are dumped in hexadecimal
729 into the kernel log. These opcodes can then be disassembled using
730 the program tools/net/bpf_jit_disasm.c provided in the kernel source
731 tree.
732 Since Linux 4.15, the kernel may configured with the CONFIG_BPF_JIT_AL‐
734 WAYS_ON option. In this case, the JIT compiler is always enabled, and
735 the bpf_jit_enable is initialized to 1 and is immutable. (This kernel
736 configuration option was provided as a mitigation for one of the Spec‐
737 tre attacks against the BPF interpreter.)
738 The JIT compiler for eBPF is currently available for the following ar‐
740 chitectures:
741 * x86-64 (since Linux 3.18; cBPF since Linux 3.0);
743 * ARM32 (since Linux 3.18; cBPF since Linux 3.4);
744 * SPARC 32 (since Linux 3.18; cBPF since Linux 3.5);
745 * ARM-64 (since Linux 3.18);
746 * s390 (since Linux 4.1; cBPF since Linux 3.7);
747 * PowerPC 64 (since Linux 4.8; cBPF since Linux 3.1);
748 * SPARC 64 (since Linux 4.12);
749 * x86-32 (since Linux 4.18);
750 * MIPS 64 (since Linux 4.18; cBPF since Linux 3.16);
751 * riscv (since Linux 5.1).
752
754 /* bpf+sockets example:
755 * 1. create array map of 256 elements
756 * 2. load program that counts number of packets received
757 * r0 = skb->data[ETH_HLEN + offsetof(struct iphdr, protocol)]
758 * map[r0]++
759 * 3. attach prog_fd to raw socket via setsockopt()
760 * 4. print number of received TCP/UDP packets every second
761 */
762 int
763 main(int argc, char *argv[])
764 {
765 int sock, map_fd, prog_fd, key;
766 long long value = 0, tcp_cnt, udp_cnt;
767 map_fd = bpf_create_map(BPF_MAP_TYPE_ARRAY, sizeof(key),
769 sizeof(value), 256);
770 if (map_fd < 0) {
771 printf("failed to create map '%s'\n", strerror(errno));
772 /* likely not run as root */
773 return 1;
774 }
775 struct bpf_insn prog[] = {
777 BPF_MOV64_REG(BPF_REG_6, BPF_REG_1), /* r6 = r1 */
778 BPF_LD_ABS(BPF_B, ETH_HLEN + offsetof(struct iphdr, protocol)),
779 /* r0 = ip->proto */
780 BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_0, -4),
781 /* *(u32 *)(fp - 4) = r0 */
782 BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), /* r2 = fp */
783 BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -4), /* r2 = r2 - 4 */
784 BPF_LD_MAP_FD(BPF_REG_1, map_fd), /* r1 = map_fd */
785 BPF_CALL_FUNC(BPF_FUNC_map_lookup_elem),
786 /* r0 = map_lookup(r1, r2) */
787 BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2),
788 /* if (r0 == 0) goto pc+2 */
789 BPF_MOV64_IMM(BPF_REG_1, 1), /* r1 = 1 */
790 BPF_XADD(BPF_DW, BPF_REG_0, BPF_REG_1, 0, 0),
791 /* lock *(u64 *) r0 += r1 */
792 BPF_MOV64_IMM(BPF_REG_0, 0), /* r0 = 0 */
793 BPF_EXIT_INSN(), /* return r0 */
794 };
795 prog_fd = bpf_prog_load(BPF_PROG_TYPE_SOCKET_FILTER, prog,
797 sizeof(prog) / sizeof(prog[0]), "GPL");
798 sock = open_raw_sock("lo");
800 assert(setsockopt(sock, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd,
802 sizeof(prog_fd)) == 0);
803 for (;;) {
805 key = IPPROTO_TCP;
806 assert(bpf_lookup_elem(map_fd, &key, &tcp_cnt) == 0);
807 key = IPPROTO_UDP;
808 assert(bpf_lookup_elem(map_fd, &key, &udp_cnt) == 0);
809 printf("TCP %lld UDP %lld packets\n", tcp_cnt, udp_cnt);
810 sleep(1);
811 }
812 return 0;
814 }
815 Some complete working code can be found in the samples/bpf directory in
817 the kernel source tree.
818
820 seccomp(2), bpf-helpers(7), socket(7), tc(8), tc-bpf(8)
821 Both classic and extended BPF are explained in the kernel source file
823 Documentation/networking/filter.txt.
824
826 This page is part of release 5.13 of the Linux man-pages project. A
827 description of the project, information about reporting bugs, and the
828 latest version of this page, can be found at
829 https://www.kernel.org/doc/man-pages/.
830Linux 2021-08-27 BPF(2)