You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/linux/concepts/dynptrs.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,6 +33,8 @@ The following functions create or manipulate dynptrs:
33
33
*[`bpf_copy_from_user_str_dynptr`](../kfuncs/bpf_copy_from_user_str_dynptr.md) - Sleepable, copies user-space string into a dynptr for the current task
34
34
*[`bpf_copy_from_user_task_dynptr`](../kfuncs/bpf_copy_from_user_task_dynptr.md) - Sleepable, copies user-space data of the task into a dynptr
35
35
*[`bpf_copy_from_user_task_str_dynptr`](../kfuncs/bpf_copy_from_user_task_str_dynptr.md) - Sleepable, copies user-space string of the task into a dynptr
36
+
*[`bpf_dynptr_from_file`](../kfuncs/bpf_dynptr_from_file.md) - Creates a dynptr for a file.
37
+
*[`bpf_dynptr_file_discard`](../kfuncs/bpf_dynptr_file_discard.md) - Releases a file dynptr.
36
38
37
39
The following functions are not dynptr centric, but do require dynptrs in their arguments:
This syscall command "freezes" a map, making its contents read-only from then on. This operation cannot be undone.
12
+
13
+
## Return value
14
+
15
+
This command will return a zero on success or an error number (negative integer) if something went wrong.
16
+
17
+
## Attributes
18
+
19
+
### `map_fd`
20
+
21
+
File descriptor of the map to freeze.
22
+
23
+
## Usage
24
+
25
+
The primary purpose of freezing a map is to allow a loader to provide map contents to the program (and verifier), and to give the guarantee that the contents of that map will not change for the duration of the lifetime of the program.
26
+
27
+
A specific example of where this is useful is for global constants. When a global constant is define, the compiler puts it in the `.rodata` ELF section, this section is turned into an array map, which gets frozen before loading. The verifier will see that this map is frozen, and that the values within are thus truly constant and will treat the map contents as scalar values. This is significant because it allows the compiler to do [dead code elimination](../concepts/verifier.md#dead-code-elimination) at load time based on the contents of the map.
This syscall command is an outdated method of attaching select program types. Where possible, [BPF links](BPF_LINK_CREATE.md) should be used instead.
12
+
13
+
## Return value
14
+
15
+
This command will return a zero on success or an error number (negative integer) if something went wrong.
16
+
17
+
## Attributes
18
+
19
+
### `target_fd`
20
+
21
+
The file descriptor to attach the program to. The type of file descriptor changes per program type.
22
+
23
+
### `target_ifindex`
24
+
25
+
The network interface index of the network device to attach the program to.
26
+
27
+
### `attach_bpf_fd`
28
+
29
+
The file descriptor of the BPF program to attach to the `target_fd`/`target_ifindex`.
30
+
31
+
### `attach_type`
32
+
33
+
The attach type of the program attachment. Used to for example specify if a program should be installed on a networks ingress or egress path.
34
+
35
+
### `attach_flags`
36
+
37
+
Any flags relevant to attaching.
38
+
39
+
### `replace_bpf_fd`
40
+
41
+
The file descriptor of the BPF program to replace with the program specified at `attach_bpf_fd`. Can for some program types be used to replace an explicitly specified program to avoid accidents where the wrong program may be replaced.
42
+
43
+
### `relative_fd`
44
+
45
+
The file descriptor of another program to attach relative to, in the case of attach points that support multiple programs being attached at the same time.
46
+
47
+
### `relative_id`
48
+
49
+
The BPF ID of another program to attach relative to, in the case of attach points that support multiple programs being attached at the same time.
50
+
51
+
### `expected_revision`
52
+
53
+
The expected revision of the collection of programs, in the case of attach points that support multiple programs being attached at the same time.
54
+
55
+
## Usage
56
+
57
+
This syscall command was an early attempt at allowing programs to be attached via a BPF syscall, instead of needing to use external systems such as [`ioctl`](https://man7.org/linux/man-pages/man2/ioctl.2.html) and [netlink](https://man7.org/linux/man-pages/man7/netlink.7.html) to attach BPF programs.
58
+
59
+
For the most part it has been succeeded by [BPF links](BPF_LINK_CREATE.md) are the current state of the art when it comes to attaching programs. But there are still some program types that have not received link support yet.
60
+
61
+
Below are section for each program type that can still be attached with this syscall.
62
+
63
+
### `BPF_PROG_TYPE_SK_SKB` and `BPF_PROG_TYPE_SK_MSG`
64
+
65
+
[`BPF_PROG_TYPE_SK_SKB`](../program-type/BPF_PROG_TYPE_SK_SKB.md) and [`BPF_PROG_TYPE_SK_MSG`](../program-type/BPF_PROG_TYPE_SK_MSG.md) programs are attached to a BPF socket map (map of type `BPF_MAP_TYPE_SOCKMAP` or `BPF_MAP_TYPE_SOCKHASH`). As of v6.19 there exists no link support for these program types.
66
+
67
+
`attach_bpf_fd` should be the file descriptor of a BPF socket map.
68
+
69
+
No `attach_flags` exist for these programs.
70
+
71
+
### `BPF_PROG_TYPE_LIRC_MODE2`
72
+
73
+
[`BPF_PROG_TYPE_LIRC_MODE2`](../program-type/BPF_PROG_TYPE_LIRC_MODE2.md) programs are attached to LIRC devices. As of v6.19 there exists no link support for this program types.
74
+
75
+
`attach_bpf_fd` should be the file descriptor of a LIRC device (obtained by opening a device in the `/dev` pseudo file system).
76
+
77
+
No `attach_flags` exist for this program type.
78
+
79
+
### `BPF_PROG_TYPE_FLOW_DISSECTOR`
80
+
81
+
[`BPF_PROG_TYPE_FLOW_DISSECTOR`](../program-type/BPF_PROG_TYPE_FLOW_DISSECTOR.md) programs attach to a network namespace. Flow dissectors can be attached via [BPF links](BPF_LINK_CREATE.md) which is the preferred method. But doing it via `BPF_PROG_ATTACH` is still possible for compatibility reasons.
82
+
83
+
When called, the program is attached to the network namespace of the calling process / thread.
84
+
85
+
`attach_bpf_fd` should be zero.
86
+
87
+
No `attach_flags` exist for this program type.
88
+
89
+
90
+
### `BPF_PROG_TYPE_SCHED_CLS`
91
+
92
+
[`BPF_PROG_TYPE_SCHED_CLS`](../program-type/BPF_PROG_TYPE_SCHED_CLS.md) (Traffic Control) programs attach to network interfaces. Traffic control programs can be attached via [BPF links](BPF_LINK_CREATE.md) which is the preferred method. But doing it via `BPF_PROG_ATTACH` is still possible for compatibility reasons.
93
+
94
+
`attach_ifindex` should contain the index of the network interface the program should be attached to.
95
+
96
+
If `attach_flags` contains `BPF_F_REPLACE`, then the new program will replace the program specified with `replace_bpf_fd`.
97
+
98
+
If `attach_flags` contains `BPF_F_BEFORE`, then the new program will be inserted before `relative_fd` / `relative_id`.
99
+
100
+
If `attach_flags` contains `BPF_F_AFTER`, then the new program will be inserted after `relative_fd` / `relative_id`.
101
+
102
+
`expected_revision` must be equal to the current revision which can be obtained via the [`BPF_PROG_QUERY`](BPF_PROG_QUERY.md) syscall.
The file descriptor for the program to bind the map to.
20
+
21
+
### `map_fd`
22
+
23
+
The file descriptor of the map to be bound.
24
+
25
+
### `flags`
26
+
27
+
Flags, currently not use, so always zero.
28
+
29
+
## Usage
30
+
31
+
Normally a map is bound to a program when a program uses a map directly. What this syscall allows us to do is to associate (bind) the map to an already loaded program in the same way. So the program will increment the reference count on the map so it will stay loaded as long as the program is loaded.
32
+
33
+
The intended use case is to bind array maps containing metadata to programs. These would not be referenced by the program itself, hence the need for the binding. Userspace can use these maps to store information such as commit hashes and other auxiliary information there.
This syscall command creates a [token](../concepts/token.md) from a BPF file system with delegated privileges.
12
+
13
+
## Return value
14
+
15
+
This command will return the file descriptor of the token (positive integer) or an error number (negative integer) if something went wrong.
16
+
17
+
## Attributes
18
+
19
+
### `flags`
20
+
21
+
A field for flags, currently unused.
22
+
23
+
### `bpffs_fd`
24
+
25
+
The file descriptor to the root of a BPF file system.
26
+
27
+
## Usage
28
+
29
+
Tokens allow a privileged process (with `CAP_SYS_ADMIN` running in the init user namespace) to delegate permission to do certain BPF related operations to a non-privileged process. Normally unprivileged processes have little capabilities, the can load a few program types and maps, unless the `unprivileged_bpf_disabled` syscall is set. But with tokens, unprivileged processes gain near root level capabilities. A token can only be obtained if the process has `CAP_BPF`, which is the only capability the process needs to be able to use BPF with tokens.
30
+
31
+
A token has its own "policy" for which actions can or cannot be executed, set by the delegating process. A token can allow or disallow access to individual syscall commands, program types, map types, and attach types. So for example, a process can be given permission to load [`BPF_PROG_TYPE_XDP`](../program-type/BPF_PROG_TYPE_XDP.md) programs, but not any other program types.
32
+
33
+
Normally, using certain BPF features requires `CAP_NET_ADMIN` or `CAP_PERFMON`, having a token allows you to use these features (if the token permits) without having the capabilities.
34
+
35
+
So the use case is isolation. Before tokens, the loader processes needed to have capabilities to do certain actions. However, these capabilities are to broad. Giving a process `CAP_NET_ADMIN` for example also allows it to do a great deal of modifying and configuration of network interfaces, something we may not want. So a token allows us to setup an environment where a process can still perform BPF operations, but without the overly broad capabilities. In addition, the token allows for scoping down what can or can not be done, allowing us to permit only exactly what a process requires, and nothing more, to minimize what attackers could leverage if a process were to get compromised.
0 commit comments