linux/tools/bpf/bpftool/Documentation/bpftool-link.rst

108 lines
2.8 KiB
ReStructuredText
Raw Permalink Normal View History

.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
================
bpftool-link
================
-------------------------------------------------------------------------------
tool for inspection and simple manipulation of eBPF links
-------------------------------------------------------------------------------
:Manual section: 8
bpftool: Update doc (use susbtitutions) and test_bpftool_synctypes.py test_bpftool_synctypes.py helps detecting inconsistencies in bpftool between the different list of types and options scattered in the sources, the documentation, and the bash completion. For options that apply to all bpftool commands, the script had a hardcoded list of values, and would use them to check whether the man pages are up-to-date. When writing the script, it felt acceptable to have this list in order to avoid to open and parse bpftool's main.h every time, and because the list of global options in bpftool doesn't change so often. However, this is prone to omissions, and we recently added a new -l|--legacy option which was described in common_options.rst, but not listed in the options summary of each manual page. The script did not complain, because it keeps comparing the hardcoded list to the (now) outdated list in the header file. To address the issue, this commit brings the following changes: - Options that are common to all bpftool commands (--json, --pretty, and --debug) are moved to a dedicated file, and used in the definition of a RST substitution. This substitution is used in the sources of all the man pages. - This list of common options is updated, with the addition of the new -l|--legacy option. - The script test_bpftool_synctypes.py is updated to compare: - Options specific to a command, found in C files, for the interactive help messages, with the same specific options from the relevant man page for that command. - Common options, checked just once: the list in main.h is compared with the new list in substitutions.rst. Signed-off-by: Quentin Monnet <quentin@isovalent.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20211115225844.33943-3-quentin@isovalent.com
2021-11-15 22:58:43 +00:00
.. include:: substitutions.rst
SYNOPSIS
========
**bpftool** [*OPTIONS*] **link** *COMMAND*
*OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } }
*COMMANDS* := { **show** | **list** | **pin** | **help** }
LINK COMMANDS
=============
| **bpftool** **link { show | list }** [*LINK*]
| **bpftool** **link pin** *LINK* *FILE*
| **bpftool** **link detach** *LINK*
| **bpftool** **link help**
|
| *LINK* := { **id** *LINK_ID* | **pinned** *FILE* }
DESCRIPTION
===========
bpftool link { show | list } [*LINK*]
Show information about active links. If *LINK* is specified show
information only about given link, otherwise list all links currently
active on the system.
Output will start with link ID followed by link type and zero or more named
attributes, some of which depend on type of link.
Since Linux 5.8 bpftool is able to discover information about processes
that hold open file descriptors (FDs) against BPF links. On such kernels
bpftool will automatically emit this information as well.
bpftool link pin *LINK* *FILE*
Pin link *LINK* as *FILE*.
Note: *FILE* must be located in *bpffs* mount. It must not contain a dot
character ('.'), which is reserved for future extensions of *bpffs*.
bpftool link detach *LINK*
Force-detach link *LINK*. BPF link and its underlying BPF program will stay
valid, but they will be detached from the respective BPF hook and BPF link
will transition into a defunct state until last open file descriptor for
that link is closed.
bpftool link help
Print short help message.
OPTIONS
=======
.. include:: common_options.rst
-f, --bpffs
When showing BPF links, show file names of pinned links.
-n, --nomount
Do not automatically attempt to mount any virtual file system (such as
tracefs or BPF virtual file system) when necessary.
EXAMPLES
========
**# bpftool link show**
::
10: cgroup prog 25
cgroup_id 614 attach_type egress
pids test_progs(223)
**# bpftool --json --pretty link show**
::
[{
"type": "cgroup",
"prog_id": 25,
"cgroup_id": 614,
"attach_type": "egress",
"pids": [{
"pid": 223,
"comm": "test_progs"
}
]
}
]
|
| **# bpftool link pin id 10 /sys/fs/bpf/link**
| **# ls -l /sys/fs/bpf/**
::
-rw------- 1 root root 0 Apr 23 21:39 link