summaryrefslogtreecommitdiff
path: root/tools/bpf/bpftool/Documentation
AgeCommit message (Collapse)AuthorFilesLines
2018-07-12tools: bpf: build and install man page for eBPF helpers from bpftool/Quentin Monnet1-5/+8
Provide a new Makefile.helpers in tools/bpf, in order to build and install the man page for eBPF helpers. This Makefile is also included in the one used to build bpftool documentation, so that it can be called either on its own (cd tools/bpf && make -f Makefile.helpers) or from bpftool directory (cd tools/bpf/bpftool && make doc, or cd tools/bpf/bpftool/Documentation && make helpers). Makefile.helpers is not added directly to bpftool to avoid changing its Makefile too much (helpers are not 100% directly related with bpftool). But the possibility to build the page from bpftool directory makes us able to package the helpers man page with bpftool, and to install it along with bpftool documentation, so that the doc for helpers becomes easily available to developers through the "man" program. Cc: linux-man@vger.kernel.org Suggested-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-07-11tools: bpftool: allow reuse of maps with bpftool prog loadJakub Kicinski1-2/+18
Add map parameter to prog load which will allow reuse of existing maps instead of creating new ones. We need feature detection and compat code for reallocarray, since it's not available in many libc versions. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Alexei Starovoitov <ast@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-07-11tools: bpftool: allow users to specify program type for prog loadJakub Kicinski1-2/+13
Sometimes program section names don't match with libbpf's expectation. In particular XDP's default section names differ between libbpf and iproute2. Allow users to pass program type on command line. Name the types like the libbpf expected section names. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-07-11tools: bpftool: add support for loading programs for offloadJakub Kicinski1-2/+4
Extend the bpftool prog load command to also accept "dev" parameter, which will allow us to load programs onto devices. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-07-07bpftool: document cgroup tree commandRoman Gushchin1-1/+11
Describe cgroup tree command in the corresponding bpftool man page. Signed-off-by: Roman Gushchin <guro@fb.com> Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com> Cc: Quentin Monnet <quentin.monnet@netronome.com> Cc: Daniel Borkmann <daniel@iogearbox.net> Cc: Alexei Starovoitov <ast@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-05-30bpftool: Support sendmsg{4,6} attach typesAndrey Ignatov1-2/+7
Add support for recently added BPF_CGROUP_UDP4_SENDMSG and BPF_CGROUP_UDP6_SENDMSG attach types to bpftool, update documentation and bash completion. Signed-off-by: Andrey Ignatov <rdna@fb.com> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Acked-by: Song Liu <songliubraving@fb.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-05-25tools/bpftool: add perf subcommandYonghong Song2-1/+85
The new command "bpftool perf [show | list]" will traverse all processes under /proc, and if any fd is associated with a perf event, it will print out related perf event information. Documentation is also added. Below is an example to show the results using bcc commands. Running the following 4 bcc commands: kprobe: trace.py '__x64_sys_nanosleep' kretprobe: trace.py 'r::__x64_sys_nanosleep' tracepoint: trace.py 't:syscalls:sys_enter_nanosleep' uprobe: trace.py 'p:/home/yhs/a.out:main' The bpftool command line and result: $ bpftool perf pid 21711 fd 5: prog_id 5 kprobe func __x64_sys_write offset 0 pid 21765 fd 5: prog_id 7 kretprobe func __x64_sys_nanosleep offset 0 pid 21767 fd 5: prog_id 8 tracepoint sys_enter_nanosleep pid 21800 fd 5: prog_id 9 uprobe filename /home/yhs/a.out offset 1159 $ bpftool -j perf [{"pid":21711,"fd":5,"prog_id":5,"fd_type":"kprobe","func":"__x64_sys_write","offset":0}, \ {"pid":21765,"fd":5,"prog_id":7,"fd_type":"kretprobe","func":"__x64_sys_nanosleep","offset":0}, \ {"pid":21767,"fd":5,"prog_id":8,"fd_type":"tracepoint","tracepoint":"sys_enter_nanosleep"}, \ {"pid":21800,"fd":5,"prog_id":9,"fd_type":"uprobe","filename":"/home/yhs/a.out","offset":1159}] $ bpftool prog 5: kprobe name probe___x64_sys tag e495a0c82f2c7a8d gpl loaded_at 2018-05-15T04:46:37-0700 uid 0 xlated 200B not jited memlock 4096B map_ids 4 7: kprobe name probe___x64_sys tag f2fdee479a503abf gpl loaded_at 2018-05-15T04:48:32-0700 uid 0 xlated 200B not jited memlock 4096B map_ids 7 8: tracepoint name tracepoint__sys tag 5390badef2395fcf gpl loaded_at 2018-05-15T04:48:48-0700 uid 0 xlated 200B not jited memlock 4096B map_ids 8 9: kprobe name probe_main_1 tag 0a87bdc2e2953b6d gpl loaded_at 2018-05-15T04:49:52-0700 uid 0 xlated 200B not jited memlock 4096B map_ids 9 $ ps ax | grep "python ./trace.py" 21711 pts/0 T 0:03 python ./trace.py __x64_sys_write 21765 pts/0 S+ 0:00 python ./trace.py r::__x64_sys_nanosleep 21767 pts/2 S+ 0:00 python ./trace.py t:syscalls:sys_enter_nanosleep 21800 pts/3 S+ 0:00 python ./trace.py p:/home/yhs/a.out:main 22374 pts/1 S+ 0:00 grep --color=auto python ./trace.py Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Yonghong Song <yhs@fb.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2018-05-05tools: bpftool: add simple perf event output readerJakub Kicinski2-7/+24
Users of BPF sooner or later discover perf_event_output() helpers and BPF_MAP_TYPE_PERF_EVENT_ARRAY. Dumping this array type is not possible, however, we can add simple reading of perf events. Create a new event_pipe subcommand for maps, this sub command will only work with BPF_MAP_TYPE_PERF_EVENT_ARRAY maps. Parts of the code from samples/bpf/trace_output_user.c. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Alexei Starovoitov <ast@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-05-05tools: bpftool: fold hex keyword in command helpJakub Kicinski1-9/+10
Instead of spelling [hex] BYTES everywhere use DATA as keyword for generalized value. This will help us keep the messages concise when longer command are added in the future. It will also be useful once BTF support comes. We will only have to change the definition of DATA. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-04-26tools, bpftool: Display license GPL compatible in prog show/listJiri Olsa1-1/+2
Display the license "gpl" string in bpftool prog command, like: # bpftool prog list 5: tracepoint name func tag 57cd311f2e27366b gpl loaded_at Apr 26/09:37 uid 0 xlated 16B not jited memlock 4096B # bpftool --json --pretty prog show [{ "id": 5, "type": "tracepoint", "name": "func", "tag": "57cd311f2e27366b", "gpl_compatible": true, "loaded_at": "Apr 26/09:37", "uid": 0, "bytes_xlated": 16, "jited": false, "bytes_memlock": 4096 } ] Signed-off-by: Jiri Olsa <jolsa@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-04-18tools: bpftool: make it easier to feed hex bytes to bpftoolQuentin Monnet1-9/+20
bpftool uses hexadecimal values when it dumps map contents: # bpftool map dump id 1337 key: ff 13 37 ff value: a1 b2 c3 d4 ff ff ff ff Found 1 element In order to lookup or update values with bpftool, the natural reflex is then to copy and paste the values to the command line, and to try to run something like: # bpftool map update id 1337 key ff 13 37 ff \ value 00 00 00 00 00 00 1a 2b Error: error parsing byte: ff bpftool complains, because it uses strtoul() with a 0 base to parse the bytes, and that without a "0x" prefix, the bytes are considered as decimal values (or even octal if they start with "0"). To feed hexadecimal values instead, one needs to add "0x" prefixes everywhere necessary: # bpftool map update id 1337 key 0xff 0x13 0x37 0xff \ value 0 0 0 0 0 0 0x1a 0x2b To make it easier to use hexadecimal values, add an optional "hex" keyword to put after "key" or "value" to tell bpftool to consider the digits as hexadecimal. We can now do: # bpftool map update id 1337 key hex ff 13 37 ff \ value hex 0 0 0 0 0 0 1a 2b Without the "hex" keyword, the bytes are still parsed according to normal integer notation (decimal if no prefix, or hexadecimal or octal if "0x" or "0" prefix is used, respectively). The patch also add related documentation and bash completion for the "hex" keyword. Suggested-by: Daniel Borkmann <daniel@iogearbox.net> Suggested-by: David Beckett <david.beckett@netronome.com> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-04-18bpftool: Support new prog types and attach typesAndrey Ignatov1-2/+9
Add recently added prog types to `bpftool prog` and attach types to `bpftool cgroup`. Update bpftool documentation and bash completion appropriately. Signed-off-by: Andrey Ignatov <rdna@fb.com> Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-03-02tools: bpftool: new command-line option and documentation for 'visual'Jiong Wang1-6/+12
This patch adds new command-line option for visualizing the xlated eBPF sequence. Documentations are updated accordingly. Usage: bpftool prog dump xlated id 2 visual Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Jiong Wang <jiong.wang@netronome.com> Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2018-02-08tools: bpftool: add bash completion for cgroup commandsQuentin Monnet1-2/+2
Add bash completion for "bpftool cgroup" command family. While at it, also fix the formatting of some keywords in the man page for cgroups. Fixes: 5ccda64d38cc ("bpftool: implement cgroup bpf operations") Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-02-08tools: bpftool: make syntax for program map update explicit in man pageQuentin Monnet1-1/+2
Specify in the documentation that when using bpftool to update a map of type BPF_MAP_TYPE_PROG_ARRAY, the syntax for the program used as a value should use the "id|tag|pinned" keywords convention, as used with "bpftool prog" commands. Fixes: ff69c21a85a4 ("tools: bpftool: add documentation") Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-02-08tools: bpftool: exit doc Makefile early if rst2man is not availableQuentin Monnet1-0/+5
If rst2man is not available on the system, running `make doc` from the bpftool directory fails with an error message. However, it creates empty manual pages (.8 files in this case). A subsequent call to `make doc-install` would then succeed and install those empty man pages on the system. To prevent this, raise a Makefile error and exit immediately if rst2man is not available before generating the pages from the rst documentation. Fixes: ff69c21a85a4 ("tools: bpftool: add documentation") Reported-by: Jason van Aaardt <jason.vanaardt@netronome.com> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2018-01-04tools: bpftool: alias show and list commandsJakub Kicinski4-12/+12
iproute2 seems to accept show and list as aliases. Let's do the same thing, and by allowing both bring cgroup syntax back in line with maps and progs. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2017-12-14bpftool: implement cgroup bpf operationsRoman Gushchin4-4/+124
This patch adds basic cgroup bpf operations to bpftool: cgroup list, attach and detach commands. Usage is described in the corresponding man pages, and examples are provided. Syntax: $ bpftool cgroup list CGROUP $ bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS] $ bpftool cgroup detach CGROUP ATTACH_TYPE PROG Signed-off-by: Roman Gushchin <guro@fb.com> Cc: Alexei Starovoitov <ast@kernel.org> Cc: Daniel Borkmann <daniel@iogearbox.net> Cc: Jakub Kicinski <jakub.kicinski@netronome.com> Cc: Martin KaFai Lau <kafai@fb.com> Cc: Quentin Monnet <quentin.monnet@netronome.com> Reviewed-by: David Ahern <dsahern@gmail.com> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2017-12-14bpftool: implement prog load commandRoman Gushchin2-2/+10
Add the prog load command to load a bpf program from a specified binary file and pin it to bpffs. Usage description and examples are given in the corresponding man page. Syntax: $ bpftool prog load OBJ FILE FILE is a non-existing file on bpffs. Signed-off-by: Roman Gushchin <guro@fb.com> Cc: Alexei Starovoitov <ast@kernel.org> Cc: Daniel Borkmann <daniel@iogearbox.net> Reviewed-by: Jakub Kicinski <jakub.kicinski@netronome.com> Cc: Martin KaFai Lau <kafai@fb.com> Cc: Quentin Monnet <quentin.monnet@netronome.com> Cc: David Ahern <dsahern@gmail.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2017-12-08tools: bpftool: create "uninstall", "doc-uninstall" make targetsQuentin Monnet1-1/+7
Create two targets to remove executable and documentation that would have been previously installed with `make install` and `make doc-install`. Also create a "QUIET_UNINST" helper in tools/scripts/Makefile.include. Do not attempt to remove directories /usr/local/sbin and /usr/share/bash-completions/completions, even if they are empty, as those specific directories probably already existed on the system before we installed the program, and we do not wish to break other makefiles that might assume their existence. Do remvoe /usr/local/share/man/man8 if empty however, as this directory does not seem to exist by default. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2017-12-08tools: bpftool: harmonise Makefile and Documentation/MakefileQuentin Monnet1-9/+13
Several minor fixes and harmonisation items for Makefiles: * Use the same mechanism for verbose/non-verbose output in two files ("$(Q)"), for all commands. * Use calls to "QUIET_INSTALL" and equivalent in Makefile. In particular, use "call(descend, ...)" instead of "make -C" to run documentation targets. * Add a "doc-clean" target, aligned on "doc" and "doc-install". * Make "install" target in Makefile depend on "bpftool". * Remove condition on DESTDIR to initialise prefix in doc Makefile. * Remove modification of VPATH based on OUTPUT, it is unused. * Formatting: harmonise spaces around equal signs. * Make install path for man pages /usr/local/man instead of /usr/local/share/man (respects the Makefile conventions, and the latter is usually a symbolic link to the former anyway). * Do not erase prefix if set by user in bpftool Makefile. * Fix install target for bpftool: append DESTDIR to install path. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2017-11-30tools: bpftool: unify installation directoriesQuentin Monnet1-1/+1
Programs and documentation not managed by package manager are generally installed under /usr/local/, instead of the user's home directory. In particular, `man` is generally able to find manual pages under `/usr/local/share/man`. bpftool generally follows perf's example, and perf installs to home directory. However bpftool requires root credentials, so it seems sensible to follow the more common convention of installing files under /usr/local instead. So, make /usr/local the default prefix for installing the binary with `make install`, and the documentation with `make doc-install`. Also, create /usr/local/sbin if it does not exist. Note that the bash-completion file, however, is still installed under /usr/share/bash-completion/completions, as the default setup for bash does not attempt to load completion files under /usr/local/. Reported-by: David Beckett <david.beckett@netronome.com> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2017-11-11tools: bpftool: optionally show filenames of pinned objectsPrashant Bhole2-2/+8
Making it optional to show file names of pinned objects because it scans complete bpf-fs filesystem which is costly. Added option -f|--bpffs. Documentation updated. Signed-off-by: Prashant Bhole <bhole_prashant_q7@lab.ntt.co.jp> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-24tools: bpftool: update documentation for --json and --pretty usageQuentin Monnet3-4/+80
Update the documentation to provide help about JSON output generation, and add an example in bpftool-prog manual page. Also reintroduce an example that was left aside when the tool was moved from GitHub to the kernel sources, in order to show how to mount the bpffs file system (to pin programs) inside the bpftool-prog manual page. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-24tools: bpftool: add cosmetic changes for the manual pagesQuentin Monnet3-23/+26
Make the look-and-feel of the manual pages somewhat closer to other manual pages, such as the ones from the utilities from iproute2, by highlighting more keywords. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-24tools: bpftool: add option parsing to bpftool, --help and --versionQuentin Monnet3-0/+24
Add an option parsing facility to bpftool, in prevision of future options for demanding JSON output. Currently, two options are added: --help and --version, that act the same as the respective commands `help` and `version`. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-22tools: bpftool: add a command to display bpftool versionQuentin Monnet1-0/+2
This command can be used to print the version of the tool, which is in fact the version from Linux taken from usr/include/linux/version.h. Example usage: $ bpftool version bpftool v4.14.0 Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-22tools: bpftool: show that `opcodes` or `file FILE` should be exclusiveQuentin Monnet1-4/+4
For the `bpftool prog dump { jited | xlated } ...` command, adding `opcodes` keyword (to request opcodes to be printed) will have no effect if `file FILE` (to write binary output to FILE) is provided. The manual page and the help message to be displayed in the terminal should reflect that, and indicate that these options should be mutually exclusive. Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com> Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-18tools: bpftool: use more common tag formatJakub Kicinski1-1/+1
Program tag is usually displayed as string of bytes without any separators (e.g. as "aa5520b1090cfeb6" vs MAC addr-like format bpftool uses currently: "aa:55:20:b1:09:0c:fe:b6"). Make bptfool use the more common format both for displaying the tag and selecting the program by tag. This was pointed out in review but I misunderstood the comment. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Simon Horman <simon.horman@netronome.com> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Alexei Starovoitov <ast@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-10tools: bpftool: use the kernel's instruction printerJakub Kicinski1-4/+7
Compile the instruction printer from kernel/bpf and use it for disassembling "translated" eBPF code. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Reviewed-by: Simon Horman <simon.horman@netronome.com> Acked-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
2017-10-05tools: bpftool: add documentationJakub Kicinski4-0/+257
Add documentation for bpftool. Separate files for each subcommand. Use rst format. Documentation is compiled into man pages using rst2man. Signed-off-by: David Beckett <david.beckett@netronome.com> Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Acked-by: Alexei Starovoitov <ast@kernel.org> Acked-by: Daniel Borkmann <daniel@iogearbox.net> Signed-off-by: David S. Miller <davem@davemloft.net>
generated by cgit v1.2.3 (git 2.39.0) at 2024-11-28 19:44:25 +0300