Inspect and Edit eBPF Maps with bpftool map

A BPF map is a table living inside the kernel, and bpftool map is how you read it, or change it, without writing a program. By the end you can identify a map, inspect its entries, address it by ID or pinned path, and make a controlled update. The examples use the bpftool-map(8) interface shipped by linux-tools-common 6.8.0-139.139 on this host.

Allow 15 to 30 minutes if the map already exists. You need a Linux host with a running BPF workload, the bpftool command, and permission to inspect or change the map. Inspecting ordinary system maps may need elevated privileges, and creating, pinning, updating or deleting maps commonly requires root or equivalent BPF capabilities.

1. Check the local command first

Check the command and its version before you touch a map. This catches a common trap: linux-tools-common can install a wrapper without installing the executable that matches the running kernel.

$ command -v bpftool
/usr/sbin/bpftool
$ bpftool version
WARNING: bpftool not found for kernel 6.8.0-139

On this host, the wrapper reports that linux-tools-6.8.0-139-generic may also be required. Install the matching kernel tools through your normal package-management process, then repeat bpftool version. Do not treat the warning as a successful version check, and do not guess at a binary from another kernel release.

The rest of this guide describes the map syntax documented by the installed manpage. If the command still only prints the warning, stop here: there is no useful map output to verify yet.

2. List maps and record their shape

List every loaded map, or ask for one by ID, name or pinned path. Begin with a read-only listing so you know the key and value sizes before you prepare any bytes.

# bpftool map show
10: hash  name some_map  flags 0x0
      key 4B  value 8B  max_entries 2048  memlock 167936B

The first number is the map ID. The listing also gives the map type, name, key size, value size and capacity. Those sizes are a hard boundary: a four-byte key is not interchangeable with an eight-byte key. Attributes vary with the kernel version, and a process holding a map file descriptor may be shown on kernels with the relevant support.

For scripts, ask for JSON and let a parser read it instead of scraping columns:

# bpftool -j map show

• Pretty JSON. --pretty implies JSON and is easier to read interactively.
• Pinned names. --bpffs adds pinned file names when available.
• No mounting. --nomount stops bpftool attempting automatic virtual-filesystem mounts, which matters when a diagnostic command must not change mount state.

3. Choose a stable map reference

An ID such as 10 can change after a map is destroyed and recreated. A pinned path is usually clearer for repeatable administration:

# bpftool map show id 10
# bpftool map show name some_map
# bpftool map show pinned /sys/fs/bpf/example_map

4. Read entries before changing them

Dump a map to see all entries, or look up one known key. The output is byte-oriented, so interpret it using the map's own key and value layout. Do not assume the bytes are text or host-order integers.

# bpftool map dump id 10
key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
Found 1 element
# bpftool map lookup id 10 key 0 1 2 3
key: 00 01 02 03 value: 00 01 02 03 04 05 06 07

To walk keys, omit the key to get the first one, then supply a returned key to get the next:

# bpftool map getnext id 10
# bpftool map getnext id 10 key 0 1 2 3

An empty dump is a valid result for an empty map. A failed lookup is different: check the key length, map reference and byte values before trying again.

5. Update one entry with explicit bytes

Take a fresh dump, confirm the target key and value sizes, then update one entry. The safest example uses hex, because it removes any doubt about whether a byte such as 0c is decimal or hexadecimal.

# bpftool map update id 10 \
    key hex 20 c4 b7 00 \
    value hex 0f ff ff ab 01 02 03 4c \
    exist

• exist refuses to create. Use noexist when creation is the only acceptable result, or any when either creation or replacement is fine.
• No flag means permissive. Without an update flag, the documented default is update-or-create.
• Byte prefixes matter. If you omit hex, bpftool reads unprefixed values as decimal; 0x selects hexadecimal and a leading 0 selects octal.

6. Pin a map for other commands

A pinned map keeps a filesystem reference after the creating process exits. The destination must be on a mounted BPF filesystem, and the path must not contain a dot.

# mount -t bpf none /sys/fs/bpf
# bpftool map pin id 10 /sys/fs/bpf/example_map
# bpftool map dump pinned /sys/fs/bpf/example_map

Mounting the BPF filesystem and pinning both change the host, so record the intended path first.

7. Treat special map operations as application actions

Queue and stack maps have dedicated operations: peek, push, pop, enqueue and dequeue. These consume or add entries, so they are not harmless inspection commands.

A perf-event array's event_pipe operation installs perf rings and silently replaces an existing ring at the selected location, so another consumer can stop receiving events. Use it only when you own that map's event pipeline.

Program-array maps can change tail-call targets with map update, but the map must be pinned or the update can disappear when bpftool exits. Verify the target program reference and rollback plan before changing live packet or tracing behaviour.

8. Freeze only when you mean it

freeze makes a map read-only to user space. Entries can no longer be updated or deleted through the BPF system call, and the operation is not reversible for that map. BPF programs keep their existing read and write permissions.

# bpftool map freeze pinned /sys/fs/bpf/example_map
# bpftool map lookup pinned /sys/fs/bpf/example_map key 0 1 2 3