netdev - Re: [PATCH bpf-next 09/10] bpftool: add bpftool-link manpage

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:   Fri, 24 Apr 2020 09:32:39 -0700
From:   Andrii Nakryiko <andrii.nakryiko@...il.com>
To:     Quentin Monnet <quentin@...valent.com>
Cc:     Andrii Nakryiko <andriin@...com>, bpf <bpf@...r.kernel.org>,
        Networking <netdev@...r.kernel.org>,
        Alexei Starovoitov <ast@...com>,
        Daniel Borkmann <daniel@...earbox.net>,
        Kernel Team <kernel-team@...com>
Subject: Re: [PATCH bpf-next 09/10] bpftool: add bpftool-link manpage

On Fri, Apr 24, 2020 at 3:33 AM Quentin Monnet <quentin@...valent.com> wrote:
>
> 2020-04-23 22:35 UTC-0700 ~ Andrii Nakryiko <andriin@...com>
> > Add bpftool-link manpage with information and examples of link-related
> > commands.
> >
> > Signed-off-by: Andrii Nakryiko <andriin@...com>
> > ---
> >  .../bpftool/Documentation/bpftool-link.rst    | 119 ++++++++++++++++++
> >  1 file changed, 119 insertions(+)
> >  create mode 100644 tools/bpf/bpftool/Documentation/bpftool-link.rst
> >
> > diff --git a/tools/bpf/bpftool/Documentation/bpftool-link.rst b/tools/bpf/bpftool/Documentation/bpftool-link.rst
> > new file mode 100644
> > index 000000000000..2866128cd6b2
> > --- /dev/null
> > +++ b/tools/bpf/bpftool/Documentation/bpftool-link.rst
> > @@ -0,0 +1,119 @@
> > +================
> > +bpftool-link
> > +================
> > +-------------------------------------------------------------------------------
> > +tool for inspection and simple manipulation of eBPF links
> > +-------------------------------------------------------------------------------
> > +
> > +:Manual section: 8
> > +
> > +SYNOPSIS
> > +========
> > +
> > +     **bpftool** [*OPTIONS*] **link *COMMAND*
>
> Missing the ending "**" after "**link", please fix.

will do

>
> > +
> > +     *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
> > +
> > +     *COMMANDS* := { **show** | **list** | **pin** | **help** }
> > +
> > +LINK COMMANDS
> > +=============
> > +
> > +|    **bpftool** **link { show | list }** [*LINK*]
> > +|    **bpftool** **link pin** *LINK* *FILE*
> > +|    **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.
>
> Nit: indent issue on the line above.

fixing

>
> > +
> > +     **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 help**
> > +               Print short help message.
> > +
> > +OPTIONS
> > +=======
> > +     -h, --help
> > +               Print short generic help message (similar to **bpftool help**).
> > +
> > +     -V, --version
> > +               Print version number (similar to **bpftool version**).
> > +
> > +     -j, --json
> > +               Generate JSON output. For commands that cannot produce JSON, this
> > +               option has no effect.
> > +
> > +     -p, --pretty
> > +               Generate human-readable JSON output. Implies **-j**.
> > +
> > +     -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.
> > +
> > +     -d, --debug
> > +               Print all logs available, even debug-level information. This
> > +               includes logs from libbpf.
> > +
> > +EXAMPLES
> > +========
> > +**# bpftool link show**
> > +
> > +::
> > +
> > +    10: cgroup  prog 25
> > +            cgroup_id 614  attach_type egress
> > +
> > +**# bpftool --json --pretty link show**
> > +
> > +::
> > +
> > +    [{
> > +            "type": "cgroup",
> > +            "prog_id": 25,
> > +            "cgroup_id": 614,
> > +            "attach_type": "egress"
> > +        }
> > +    ]
> > +
> > +|
> > +| **# mount -t bpf none /sys/fs/bpf/**
>
> [ Mounting should not be required, as you call
> do_pin_any()->do_pin_fd()->mount_bpffs_for_pin().
>
> Although on second thought I'm fine with keeping it, just in case users
> call bpftool --nomount. ]

It was a copy/paste from bpftool-prog.rst, but I think I'll drop it
for this one (and keep it in bpftool-prog.rst).

>
> > +| **# bpftool link pin id 10 /sys/fs/bpf/link**
> > +| **# ls -l /sys/fs/bpf/**
> > +
> > +::
> > +
> > +    -rw------- 1 root root 0 Apr 23 21:39 link
> > +
> > +
> > +SEE ALSO
> > +========
> > +     **bpf**\ (2),
> > +     **bpf-helpers**\ (7),
> > +     **bpftool**\ (8),
> > +     **bpftool-prog\ (8),
> > +     **bpftool-map**\ (8),
> > +     **bpftool-cgroup**\ (8),
> > +     **bpftool-feature**\ (8),
> > +     **bpftool-net**\ (8),
> > +     **bpftool-perf**\ (8),
> > +     **bpftool-btf**\ (8)
> >
>