Explicit documentation of maps scope

[Silvanoc]

I do not find documentation about the scope of maps. Would it make sense to add it?

Some sections, like Maps in the Introduction, give some information about it:

Maps like all other BPF objects are shared over the whole host, and multiple programs can access the same maps at the same time.

But:

1. It does not use some in programming usual wording like "global".
2. For my taste, it is not explicit/clear enough.
3. It does not put it in contrast with other information storing and sharing elements, like variables, parameters and return values.

This information is very relevant with respect to security, confidentiality, privacy,...

[dylandreimerink]

I am all for making the Docs clearer. Lets figure out what the best way is to present this info.

Lets start by clarifying the "scope" maps as I understand it:

• A map is a eBPF refcounted resource, once created it exists until no more references to it exists (from userspace, other maps, eBPF programs, or pins)
• Maps can be pinned to a BPFFS, everyone with access to it can use the open syscall to get a reference (file descriptor) to the map
• Maps have a unique ID, users with the CAP_SYS_ADMIN privilige can iterate over these IDs and get a reference (file descriptor) to the map
• Processes with a file descriptor can read and write to the maps (unless they have been created with access restrictions or have been frozen)
• Multiple eBPF programs and multiple userspace programs can access a map at the same time (the memory of the map is shared), though maps such as RING_BUFFER are single-consumer queues, so while allowed, in practice its not feasible.
• Most maps allow for symmetric access, so userspace and eBPF can see the same contents. However, especially special purpose maps tend to have exceptions:
  • Streaming maps are one way
  • *_STORAGE maps can't be used by userspace
  • BPF_MAP_TYPE_STACK_TRACE doesn't store anything, just allows eBPF to read a stack trace
  • Packet redirection maps often have asymmetric accesses both in terms of allowed actions and data types

So it is very situational who can access what. But in general, everything with root access can access all maps. Users/processes without root can only access what is given to them.

It does not use some in programming usual wording like "global".

I avoid using that term when I can help it to avoid confusion with "global data" or "global variables". In eBPF this typically refers to the usage of a C global variable. These get turned into accesses into an BPF_MAP_TYPE_ARRAY_MAP. This is typically done to implicitly share a variable across CPUs within the same program, across programs defined in the same file, or between a program and the userspace application that loaded it. Since that data is stored in a map, it follows the same rules as laid out above.

It does not put it in contrast with other information storing and sharing elements, like variables, parameters and return values.

Different variables have different lifetimes. A context such as a __sk_buff can live across multiple programs and hooks. Arguments between BPF functions and local variables typically live on the stack and do no live past the end of a program/function. However, stack memory can point to things like map values (including global variables), kernel data, context fields which may outlive the program.

I hope that helps to clarify things in general.

So, now the question, which bits of info do we put on which pages.