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

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 ================
   4 bpftool-link
   5 ================
   6 -------------------------------------------------------------------------------
   7 tool for inspection and simple manipulation of eBPF links
   8 -------------------------------------------------------------------------------
   9
  10 :Manual section: 8
  11
  12 .. include:: substitutions.rst
  13
  14 SYNOPSIS
  15 ========
  16
  17         **bpftool** [*OPTIONS*] **link** *COMMAND*
  18
  19         *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } }
  20
  21         *COMMANDS* := { **show** | **list** | **pin** | **help** }
  22
  23 LINK COMMANDS
  24 =============
  25
  26 |       **bpftool** **link { show | list }** [*LINK*]
  27 |       **bpftool** **link pin** *LINK* *FILE*
  28 |       **bpftool** **link detach** *LINK*
  29 |       **bpftool** **link help**
  30 |
  31 |       *LINK* := { **id** *LINK_ID* | **pinned** *FILE* }
  32
  33
  34 DESCRIPTION
  35 ===========
  36         **bpftool link { show | list }** [*LINK*]
  37                   Show information about active links. If *LINK* is
  38                   specified show information only about given link,
  39                   otherwise list all links currently active on the system.
  40
  41                   Output will start with link ID followed by link type and
  42                   zero or more named attributes, some of which depend on type
  43                   of link.
  44
  45                   Since Linux 5.8 bpftool is able to discover information about
  46                   processes that hold open file descriptors (FDs) against BPF
  47                   links. On such kernels bpftool will automatically emit this
  48                   information as well.
  49
  50         **bpftool link pin** *LINK* *FILE*
  51                   Pin link *LINK* as *FILE*.
  52
  53                   Note: *FILE* must be located in *bpffs* mount. It must not
  54                   contain a dot character ('.'), which is reserved for future
  55                   extensions of *bpffs*.
  56
  57         **bpftool link detach** *LINK*
  58                   Force-detach link *LINK*. BPF link and its underlying BPF
  59                   program will stay valid, but they will be detached from the
  60                   respective BPF hook and BPF link will transition into
  61                   a defunct state until last open file descriptor for that
  62                   link is closed.
  63
  64         **bpftool link help**
  65                   Print short help message.
  66
  67 OPTIONS
  68 =======
  69         .. include:: common_options.rst
  70
  71         -f, --bpffs
  72                   When showing BPF links, show file names of pinned
  73                   links.
  74
  75         -n, --nomount
  76                   Do not automatically attempt to mount any virtual file system
  77                   (such as tracefs or BPF virtual file system) when necessary.
  78
  79 EXAMPLES
  80 ========
  81 **# bpftool link show**
  82
  83 ::
  84
  85     10: cgroup  prog 25
  86             cgroup_id 614  attach_type egress
  87             pids test_progs(223)
  88
  89 **# bpftool --json --pretty link show**
  90
  91 ::
  92
  93     [{
  94             "type": "cgroup",
  95             "prog_id": 25,
  96             "cgroup_id": 614,
  97             "attach_type": "egress",
  98             "pids": [{
  99                     "pid": 223,
 100                     "comm": "test_progs"
 101                 }
 102             ]
 103         }
 104     ]
 105
 106 |
 107 | **# bpftool link pin id 10 /sys/fs/bpf/link**
 108 | **# ls -l /sys/fs/bpf/**
 109
 110 ::
 111
 112     -rw------- 1 root root 0 Apr 23 21:39 link