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]

Message-ID: <43a50d28-4d23-fa23-6929-4f8a082de2a9@isovalent.com>
Date:   Fri, 24 Apr 2020 11:33:11 +0100
From:   Quentin Monnet <quentin@...valent.com>
To:     Andrii Nakryiko <andriin@...com>, bpf@...r.kernel.org,
        netdev@...r.kernel.org, ast@...com, daniel@...earbox.net
Cc:     andrii.nakryiko@...il.com, kernel-team@...com
Subject: Re: [PATCH bpf-next 09/10] bpftool: add bpftool-link manpage

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.

> +
> +	*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.

> +
> +	**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. ]

> +| **# 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)
>