.\" Copyright (C) 2015 Alexei Starovoitov .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .TH BPF 2 2015-03-10 "Linux" "Linux Programmer's Manual" .SH NAME bpf - perform a command on an extended BPF map or program .SH SYNOPSIS .nf .B #include .sp .BI "int bpf(int cmd, union bpf_attr *attr, unsigned int size); .SH DESCRIPTION .BR bpf() syscall is a multiplexor for a range of different operations on extended Berkeley Packet Filter which can be characterized as "universal in-kernel virtual machine". The extended BPF (or eBPF) is similar to the original BPF (or classic BPF) used to filter network packets. Both statically analyze the programs before loading them into the kernel to ensure that they cannot harm the running system. .P eBPF extends classic BPF in multiple ways including the ability to call in-kernel helper functions and access shared data structures like BPF maps. The programs can be written in a restricted C that is compiled into eBPF bytecode and executed on the in-kernel virtual machine or JITed into native code. .SS Extended BPF Design/Architecture .P BPF maps are a generic data structure for storage of different data types. A user process can create multiple maps (with key/value-pairs being opaque bytes of data) and access them via file descriptor. BPF programs can access maps from inside the kernel in parallel. It's up to the user process and BPF program to decide what they store inside maps. .P BPF programs are similar to kernel modules. They are loaded by the user process and automatically unloaded when the process exits. Each BPF program is a set of instructions that is safe to run until its completion. The BPF verifier statically determines that the program terminates and is safe to execute. During verification the program takes hold of maps that it intends to use, so selected maps cannot be removed until the program is unloaded. The program can be attached to different events. These events can be packets, tracing events and other types that may be added in the future. A new event triggers execution of the program which may store information about the event in the maps. Beyond storing data the programs may call into in-kernel helper functions. The same program can be attached to multiple events and different programs can access the same map: .in +4n .nf tracing tracing tracing packet packet event A event B event C on eth0 on eth1 | | | | | | | | | | --> tracing <-- tracing socket socket prog_1 prog_2 prog_3 prog_4 | | | | |--- -----| |-------| map_3 map_1 map_2 .fi .in .SS Syscall Arguments .BR bpf () syscall operation is determined by .IR cmd which can be one of the following: .TP .B BPF_MAP_CREATE Create a map with the given type and attributes and return map FD .TP .B BPF_MAP_LOOKUP_ELEM Lookup element by key in a given map and return its value .TP .B BPF_MAP_UPDATE_ELEM Create or update element (key/value pair) in a given map .TP .B BPF_MAP_DELETE_ELEM Lookup and delete element by key in a given map .TP .B BPF_MAP_GET_NEXT_KEY Lookup element by key in a given map and return key of next element .TP .B BPF_PROG_LOAD Verify and load BPF program .PP .I attr is a pointer to a union of type .I bpf_attr as defined below. .I size is the size of the union. .P .nf union bpf_attr { struct { /* anonymous struct used by BPF_MAP_CREATE command */ __u32 map_type; __u32 key_size; /* size of key in bytes */ __u32 value_size; /* size of value in bytes */ __u32 max_entries; /* maximum number of entries in a map */ }; struct { /* anonymous struct used by BPF_MAP_*_ELEM commands */ __u32 map_fd; __aligned_u64 key; union { __aligned_u64 value; __aligned_u64 next_key; }; __u64 flags; }; struct { /* anonymous struct used by BPF_PROG_LOAD command */ __u32 prog_type; __u32 insn_cnt; __aligned_u64 insns; /* 'const struct bpf_insn *' */ __aligned_u64 license; /* 'const char *' */ __u32 log_level; /* verbosity level of verifier */ __u32 log_size; /* size of user buffer */ __aligned_u64 log_buf; /* user supplied 'char *' buffer */ }; } __attribute__((aligned(8))); .fi .SS BPF maps maps are a generic data structure for storage of different types and sharing data between kernel and userspace. Any map type has the following attributes: . type . max number of elements . key size in bytes . value size in bytes The following wrapper functions demonstrate how this syscall can be used to access the maps. The functions use the .IR cmd argument to invoke different operations. .TP .B BPF_MAP_CREATE .nf int bpf_create_map(enum bpf_map_type map_type, int key_size, int value_size, int max_entries) { union bpf_attr attr = { .map_type = map_type, .key_size = key_size, .value_size = value_size, .max_entries = max_entries }; return bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); } .fi .BR bpf () syscall creates a map of .I map_type type and given attributes .IR key_size , .IR value_size , .IR max_entries . On success it returns a process-local file descriptor. On error, \-1 is returned and .I errno is set to .BR EINVAL , .BR EPERM , or .BR ENOMEM . The attributes .I key_size and .I value_size will be used by the verifier during program loading to check that the program is calling .BR bpf_map_*_elem () helper functions with a correctly initialized .I key and that the program doesn't access map element .I value beyond the specified .I value_size. For example, when a map is created with .IR "key_size = 8" and the program calls .in +4n .nf bpf_map_lookup_elem(map_fd, fp - 4) .fi .in the program will be rejected, since the in-kernel helper function bpf_map_lookup_elem(map_fd, void *key) expects to read 8 bytes from .I key pointer, but .IR "fp\ -\ 4" starting address will cause out-of-bounds stack access. Similarly, when a map is created with .I "value_size = 1" and the program calls .in +4n .nf value = bpf_map_lookup_elem(...); *(u32 *) value = 1; .fi .in the program will be rejected, since it accesses the .I value pointer beyond the specified 1 byte .I value_size limit. Currently two .I map_type are supported: .in +4n .nf enum bpf_map_type { BPF_MAP_TYPE_UNSPEC, BPF_MAP_TYPE_HASH, BPF_MAP_TYPE_ARRAY, }; .fi .in .I map_type selects one of the available map implementations in the kernel. For all map_types programs access maps with the same .BR bpf_map_lookup_elem ()/ .BR bpf_map_update_elem () helper functions. .TP .B BPF_MAP_LOOKUP_ELEM .nf int bpf_lookup_elem(int fd, void *key, void *value) { union bpf_attr attr = { .map_fd = fd, .key = ptr_to_u64(key), .value = ptr_to_u64(value), }; return bpf(BPF_MAP_LOOKUP_ELEM, &attr, sizeof(attr)); } .fi .BR bpf () syscall looks up an element with a given .I key in a map .IR fd . If an element is found it returns zero and stores element's value into .I value. If no element is found it returns \-1 and sets .I errno to .BR ENOENT . .TP .B BPF_MAP_UPDATE_ELEM .nf int bpf_update_elem(int fd, void *key, void *value, __u64 flags) { union bpf_attr attr = { .map_fd = fd, .key = ptr_to_u64(key), .value = ptr_to_u64(value), .flags = flags, }; return bpf(BPF_MAP_UPDATE_ELEM, &attr, sizeof(attr)); } .fi The call creates or updates an element with a given .I key/value in a map .I fd according to .I flags which can have one of 3 possible values: .nf #define BPF_ANY 0 /* create new element or update existing */ #define BPF_NOEXIST 1 /* create new element if it didn't exist */ #define BPF_EXIST 2 /* update existing element */ .fi On success it returns zero. On error, \-1 is returned and .I errno is set to .BR EINVAL , .BR EPERM , .BR ENOMEM , or .BR E2BIG . .B E2BIG indicates that the number of elements in the map reached .I max_entries limit specified at map creation time. .B EEXIST will be returned from a call to bpf_update_elem(fd, key, value, BPF_NOEXIST) if the element with .I key already exists in the map. .B ENOENT will be returned from a call to bpf_update_elem(fd, key, value, BPF_EXIST) if the element with .I key doesn't exist in the map. .TP .B BPF_MAP_DELETE_ELEM .nf int bpf_delete_elem(int fd, void *key) { union bpf_attr attr = { .map_fd = fd, .key = ptr_to_u64(key), }; return bpf(BPF_MAP_DELETE_ELEM, &attr, sizeof(attr)); } .fi The call deletes an element in a map .I fd with a given .IR key . Returns zero on success. If the element is not found it returns \-1 and sets .I errno to .BR ENOENT . .TP .B BPF_MAP_GET_NEXT_KEY .nf int bpf_get_next_key(int fd, void *key, void *next_key) { union bpf_attr attr = { .map_fd = fd, .key = ptr_to_u64(key), .next_key = ptr_to_u64(next_key), }; return bpf(BPF_MAP_GET_NEXT_KEY, &attr, sizeof(attr)); } .fi The call looks up an element by .I key in a given map .I fd and sets the .I next_key pointer to the key of the next element. If .I key is not found, it returns zero and sets the .I next_key pointer to the key of the first element. If .I key is the last element, it returns \-1 and sets .I errno to .BR ENOENT . Other possible .I errno values are .BR ENOMEM , .BR EFAULT , .BR EPERM , and .BR EINVAL . This method can be used to iterate over all elements in the map. .TP .B close(map_fd) will delete the map .IR map_fd . When the user space program that created maps exits all maps will be deleted automatically. .SS BPF programs .TP .B BPF_PROG_LOAD This .IR cmd is used to load extended BPF program into the kernel. .nf char bpf_log_buf[LOG_BUF_SIZE]; int bpf_prog_load(enum bpf_prog_type prog_type, const struct bpf_insn *insns, int insn_cnt, const char *license) { union bpf_attr attr = { .prog_type = prog_type, .insns = ptr_to_u64(insns), .insn_cnt = insn_cnt, .license = ptr_to_u64(license), .log_buf = ptr_to_u64(bpf_log_buf), .log_size = LOG_BUF_SIZE, .log_level = 1, }; return bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); } .fi .I prog_type is one of the available program types: .in +4n .nf enum bpf_prog_type { BPF_PROG_TYPE_UNSPEC, BPF_PROG_TYPE_SOCKET_FILTER, BPF_PROG_TYPE_SCHED_CLS, }; .fi .in By picking .I prog_type the program author selects a set of helper functions callable from the program and the corresponding format of .I struct bpf_context (which is the data blob passed into the program as the first argument). For example, the programs loaded with prog_type = BPF_PROG_TYPE_SOCKET_FILTER may call the .BR bpf_map_lookup_elem () helper, whereas some future types may not. The set of functions available to the programs under a given type may increase in the future. Currently the set of functions for .B BPF_PROG_TYPE_SOCKET_FILTER is: .in +4n .nf bpf_map_lookup_elem(map_fd, void *key) /* look up key in a map_fd */ bpf_map_update_elem(map_fd, void *key, void *value) /* update key/value */ bpf_map_delete_elem(map_fd, void *key) /* delete key in a map_fd */ .fi .in and .I bpf_context is a pointer to .IR "struct sk_buff" . Programs cannot access fields of .I sk_buff directly. More program types may be added in the future. Like .B BPF_PROG_TYPE_KPROBE and .I bpf_context for it may be defined as a pointer to a .IR "struct pt_regs" . .I insns array of .I "struct bpf_insn" instructions. .I insn_cnt number of instructions in the program. .I license license string, which must be GPL compatible to call helper functions marked .IR gpl_only . .I log_buf user supplied buffer that the in-kernel verifier is using to store the verification log. This log is a multi-line string that can be checked by the program author in order to understand how the verifier came to the conclusion that the BPF program is unsafe. The format of the output can change at any time as the verifier evolves. .I log_size size of user buffer. If the size of the buffer is not large enough to store all verifier messages, \-1 is returned and .I errno is set to .BR ENOSPC . .I log_level verbosity level of the verifier. A value of zero means that the verifier will not provide a log. .TP .B close(prog_fd) will unload the BPF program. .P The maps are accessible from programs and used to exchange data between programs and between them and user space. Programs process various events (like kprobe, packets) and store their data into maps. User space fetches data from the maps. Either the same or a different map may be used by user space as a configuration space to alter program behavior on the fly. .SS Events Once a program is loaded, it can be attached to an event. Various kernel subsystems have different ways to do so. For example: .in +4n .nf setsockopt(sock, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, sizeof(prog_fd)); .fi .in will attach the program .I prog_fd to socket .I sock which was received from a prior call to .BR socket (2). In the future .in +4n .nf ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd); .fi .in may attach the program .I prog_fd to perf event .I event_fd which was received by prior call to .BR perf_event_open (2). .SH EXAMPLES .nf /* bpf+sockets example: * 1. create array map of 256 elements * 2. load program that counts number of packets received * r0 = skb->data[ETH_HLEN + offsetof(struct iphdr, protocol)] * map[r0]++ * 3. attach prog_fd to raw socket via setsockopt() * 4. print number of received TCP/UDP packets every second */ int main(int ac, char **av) { int sock, map_fd, prog_fd, key; long long value = 0, tcp_cnt, udp_cnt; map_fd = bpf_create_map(BPF_MAP_TYPE_ARRAY, sizeof(key), sizeof(value), 256); if (map_fd < 0) { printf("failed to create map '%s'\\n", strerror(errno)); /* likely not run as root */ return 1; } struct bpf_insn prog[] = { BPF_MOV64_REG(BPF_REG_6, BPF_REG_1), /* r6 = r1 */ BPF_LD_ABS(BPF_B, ETH_HLEN + offsetof(struct iphdr, protocol)), /* r0 = ip->proto */ BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_0, -4), /* *(u32 *)(fp - 4) = r0 */ BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), /* r2 = fp */ BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, -4), /* r2 = r2 - 4 */ BPF_LD_MAP_FD(BPF_REG_1, map_fd), /* r1 = map_fd */ BPF_CALL_FUNC(BPF_FUNC_map_lookup_elem), /* r0 = map_lookup(r1, r2) */ BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), /* if (r0 == 0) goto pc+2 */ BPF_MOV64_IMM(BPF_REG_1, 1), /* r1 = 1 */ BPF_XADD(BPF_DW, BPF_REG_0, BPF_REG_1, 0, 0), /* lock *(u64 *) r0 += r1 */ BPF_MOV64_IMM(BPF_REG_0, 0), /* r0 = 0 */ BPF_EXIT_INSN(), /* return r0 */ }; prog_fd = bpf_prog_load(BPF_PROG_TYPE_SOCKET_FILTER, prog, sizeof(prog), "GPL"); sock = open_raw_sock("lo"); assert(setsockopt(sock, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, sizeof(prog_fd)) == 0); for (;;) { key = IPPROTO_TCP; assert(bpf_lookup_elem(map_fd, &key, &tcp_cnt) == 0); key = IPPROTO_UDP assert(bpf_lookup_elem(map_fd, &key, &udp_cnt) == 0); printf("TCP %lld UDP %lld packets\n", tcp_cnt, udp_cnt); sleep(1); } return 0; } .fi .SH RETURN VALUE For a successful call, the return value depends on the operation: .TP .B BPF_MAP_CREATE The new file descriptor associated with the BPF map. .TP .B BPF_PROG_LOAD The new file descriptor associated with the BPF program. .TP All other commands Zero. .PP On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP .B EPERM .BR bpf() syscall was made without sufficient privilege (without the .B CAP_SYS_ADMIN capability). .TP .B ENOMEM Cannot allocate sufficient memory. .TP .B EBADF .I fd is not an open file descriptor .TP .B EFAULT One of the pointers .RI ( key or .I value or .I log_buf or .IR insns ) is outside the accessible address space. .TP .B EINVAL The value specified in .I cmd is not recognized by this kernel. .TP .B EINVAL For .BR BPF_MAP_CREATE , either .I map_type or attributes are invalid. .TP .B EINVAL For .BR BPF_MAP_*_ELEM commands, some of the fields of .I "union bpf_attr" that are not used by this command are not set to zero. .TP .B EINVAL For .BR BPF_PROG_LOAD, indicates an attempt to load an invalid program. BPF programs can be deemed invalid due to unrecognized instructions, the use of reserved fields, jumps out of range, infinite loops or calls of unknown functions. .TP .BR EACCES For .BR BPF_PROG_LOAD, even though all program instructions are valid, the program has been rejected because it was deemed unsafe. This may be because it may have accessed a disallowed memory region or an uninitialized stack/register or because the function contraints don't match the actual types or because there was a misaligned memory access. In such case it is recommended to call .BR bpf () again with .I log_level = 1 and examine .I log_buf for the specific reason provided by the verifier. .TP .BR ENOENT For .B BPF_MAP_LOOKUP_ELEM or .B BPF_MAP_DELETE_ELEM, indicates that the element with the given .I key was not found. .TP .BR E2BIG program is too large or a map reached .I max_entries limit (max number of elements). .SH NOTES These commands may be used only by a privileged process (one having the .B CAP_SYS_ADMIN capability). .SH SEE ALSO Both classic and extended BPF are explained in .IR Documentation/networking/filter.txt .