Skip to content

BPF Syscall BPF_LINK_CREATE command

v5.7

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

v5.7

This field specifies the file descriptor for the BPF program to be linked.

target_fd

v5.9

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

v5.9

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

v5.7

Attach type specifies the attach type. For more information about possible values and their meaning checkout the Attach types section.

flags

v5.7

target_btf_id

v5.10

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

v5.10

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

v5.10

This field specifies the length of the given iter_info structure, for the purposes of compatibility in case new kernels add additional fields.

v5.15

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

v5.18

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

v5.18

cnt

v5.18

This field is the number of syms, addrs and cookies to follow

syms

v5.18

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

v5.18

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

v5.18

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

v5.19

target_btf_id

v5.19

v5.19

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.

BPF_CGROUP_INET_INGRESS

v4.10

BPF_CGROUP_INET_EGRESS

v4.10

BPF_CGROUP_INET_SOCK_CREATE

v4.10

BPF_CGROUP_SOCK_OPS

v4.13

BPF_SK_SKB_STREAM_PARSER

v4.14

BPF_SK_SKB_STREAM_VERDICT

v4.14

BPF_CGROUP_DEVICE

v4.15

BPF_SK_MSG_VERDICT

v4.17

BPF_CGROUP_INET4_BIND

v4.17

BPF_CGROUP_INET6_BIND

v4.17

BPF_CGROUP_INET4_CONNECT

v4.17

BPF_CGROUP_INET6_CONNECT

v4.17

BPF_CGROUP_INET4_POST_BIND

v4.17

BPF_CGROUP_INET6_POST_BIND

v4.17

BPF_CGROUP_UDP4_SENDMSG

v4.18

BPF_CGROUP_UDP6_SENDMSG

v4.18

BPF_LIRC_MODE2

v4.18

BPF_FLOW_DISSECTOR

v4.20

BPF_CGROUP_SYSCTL

v5.2

BPF_CGROUP_UDP4_RECVMSG

v5.2

BPF_CGROUP_UDP6_RECVMSG

v5.2

BPF_CGROUP_GETSOCKOPT

v5.3

BPF_CGROUP_SETSOCKOPT

v5.3

BPF_TRACE_RAW_TP

v5.5

BPF_TRACE_FENTRY

v5.5

BPF_TRACE_FEXIT

v5.5

BPF_MODIFY_RETURN

v5.7

BPF_LSM_MAC

v5.7

BPF_TRACE_ITER

v5.8

BPF_CGROUP_INET4_GETPEERNAME

v5.8

BPF_CGROUP_INET6_GETPEERNAME

v5.8

BPF_CGROUP_INET4_GETSOCKNAME

v5.8

BPF_CGROUP_INET6_GETSOCKNAME

v5.8

BPF_XDP_DEVMAP

v5.8

BPF_CGROUP_INET_SOCK_RELEASE

v5.9

BPF_XDP_CPUMAP

v5.9

BPF_SK_LOOKUP

v5.9

BPF_XDP

v5.9

BPF_SK_SKB_VERDICT

v5.13

BPF_SK_REUSEPORT_SELECT

v5.14

BPF_SK_REUSEPORT_SELECT_OR_MIGRATE

v5.14

BPF_PERF_EVENT

v5.15

BPF_TRACE_KPROBE_MULTI

v5.18

BPF_LSM_CGROUP

v6.0

Flags