BPF Syscall BPF_LINK_CREATE command
This syscall command create a new BPF link. BPF links are the newest and thus preferred way to attach BPF programs to their hook locations within the kernel. This syscall command is intended to replace both BPF_PROG_ATTACH and other legacy attachment methods such as netlink and perf events.
Return type
If successful, this syscall command will return a file descriptor to the newly created link. The link is a reference counted object just like other BPF objects. The link is destroyed once no more references to it exist, which might happen if the loader exists without pinning the link or if the pin gets deleted. A loader might also chose to forcefully cause the link to detach from the hook point with the BPF_LINK_DETACH command.
The returned file descriptor can be used with the BPF_LINK_UPDATE and BPF_LINK_DETACH commands.
Attributes
C structure
struct { /* struct used by BPF_LINK_CREATE command */
__u32 prog_fd; /* eBPF program to attach */
union {
__u32 target_fd; /* object to attach to */
__u32 target_ifindex; /* target ifindex */
};
__u32 attach_type; /* attach type */
__u32 flags; /* extra flags */
union {
__u32 target_btf_id; /* btf_id of target to attach to */
struct {
__aligned_u64 iter_info; /* extra bpf_iter_link_info */
__u32 iter_info_len; /* iter_info length */
};
struct {
/* black box user-provided value passed through
* to BPF program at the execution time and
* accessible through bpf_get_attach_cookie() BPF helper
*/
__u64 bpf_cookie;
} perf_event;
struct {
__u32 flags;
__u32 cnt;
__aligned_u64 syms;
__aligned_u64 addrs;
__aligned_u64 cookies;
} kprobe_multi;
struct {
/* this is overlaid with the target_btf_id above. */
__u32 target_btf_id;
/* black box user-provided value passed through
* to BPF program at the execution time and
* accessible through bpf_get_attach_cookie() BPF helper
*/
__u64 cookie;
} tracing;
};
}
prog_fd
This field specifies the file descriptor for the BPF program to be linked.
target_fd
This field specifies the file descriptor of the target you wish to attach the program to. The kind of file descriptor varies per program type.
For cGroup programs (BPF_PROG_TYPE_CGROUP_SKB, BPF_PROG_TYPE_CGROUP_SOCK,
BPF_PROG_TYPE_CGROUP_SOCK_ADDR,BPF_PROG_TYPE_SOCK_OPS,BPF_PROG_TYPE_CGROUP_DEVICE,BPF_PROG_TYPE_CGROUP_SYSCTL,BPF_PROG_TYPE_CGROUP_SOCKOPT) the file descriptor should be a cGroup directory in the cGroup FS, commonly mounted at /sys/fs/cgroup, for example /sys/fs/cgroup/test.slice/. Such a fd can be obtained by using the open syscall on the desired path.
For BPF_PROG_TYPE_EXT programs this should be a file descriptor to another BPF program.
For BPF_PROG_TYPE_TRACING programs with the attach type BPF_LSM_CGROUP it should also be a cGroup directory as described above.
For BPF_PROG_TYPE_TRACING programs with the attach type BPF_TRACE_FENTRY, BPF_TRACE_FEXIT or BPF_MODIFY_RETURN this should be a file descriptor to an existing BPF program.
For BPF_PROG_TYPE_LIRC2 programs this should be a file descriptor to a infrared device in /dev.
For BPF_PROG_TYPE_FLOW_DISSECTOR and BPF_PROG_TYPE_SK_LOOKUP programs this should be a file descriptor to a network namespace. Named network namespaces are represented as objects in /var/run/netns, a file descriptor to a namespace can be obtained open syscall on one of these objects (/var/run/netns/{name}).
target_ifindex
This field specifies the network interface index of the network device to attach the program to. This field is only used for BPF_PROG_TYPE_XDP programs.
attach_type
Attach type specifies the attach type. For more information about possible values and their meaning checkout the Attach types section.
flags
target_btf_id
This field specifies the BTF id of the target to attach to, used to specify the kernel function to hook to when attaching BPF_PROG_TYPE_LSM programs.
iter_info
This field specifies over what kind of information a iterator program should iterate. It is a pointer to an instance of union bpf_iter_link_info
union bpf_iter_link_info C structure
union bpf_iter_link_info {
struct {
__u32 map_fd;
} map;
struct {
enum bpf_cgroup_iter_order order;
/* At most one of cgroup_fd and cgroup_id can be non-zero. If
* both are zero, the walk starts from the default cgroup v2
* root. For walking v1 hierarchy, one should always explicitly
* specify cgroup_fd.
*/
__u32 cgroup_fd;
__u64 cgroup_id;
} cgroup;
/* Parameters of task iterators. */
struct {
__u32 tid;
__u32 pid;
__u32 pid_fd;
} task;
};
iter_info_len
This field specifies the length of the given iter_info structure, for the purposes of compatibility in case new kernels add additional fields.
bpf_cookie
This field is an optional opaque value which is reported back to tracing programs via the bpf_get_attach_cookie helper.
The idea behind this cookie is that if the same program gets attached to multiple locations in the kernel, this value can be used to distinguish for which attach point the program is called. This ID value can for example be used as the key for a map which contains additional data the program needs or as key when collecting statistics.
kprobe_multi
This sub-struct is a collection of fields which specify one or multiple kprobe attachment points to attach the same program to multiple locations with a single syscall.
flags
cnt
This field is the number of syms, addrs and cookies to follow
syms
This field specifies a list of kernel symbols to attach the kprobe to. The value should be a pointer to an array of null-terminated string pointers.
[cnt][]char
This field is mutually exclusive with addrs. Only one can be used at a time.
addrs
This field specifies a list of kernel addresses to attach the kprobe to. The value should be a pointer to an array of memory addresses.
This field is mutually exclusive with syms. Only one can be used at a time.
cookies
This field specifies a list of cookies(bpf_cookie) values for each attachment point. The value should be a pointer to an array of 64-bit cookie values or 0 if you do not want to specify cookies.
tracing
target_btf_id
cookie
Attach types
This section describes the possible values and meanings for the attach_type attribute. These values are the same as used in the BPF_PROG_ATTACH command and the expected_attach_type field of the BPF_PROG_LOAD command.
The attach type is often used to communicate a specialization for a program type, for example if the program should attach to the ingress or egress. Since the hook locations will differ, the capabilities of the program may as well. Please check the pages of the program types for details about these attach type dependant limitations.