[thirdparty/kernel/stable.git] / tools / bpf / bpftool / Documentation / bpftool-prog.rst

================
bpftool-prog
================
-------------------------------------------------------------------------------
tool for inspection and simple manipulation of eBPF progs
-------------------------------------------------------------------------------

:Manual section: 8

SYNOPSIS
========

	**bpftool** [*OPTIONS*] **prog** *COMMAND*

	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }

	*COMMANDS* :=
	{ **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load**
	| **loadall** | **help** }

PROG COMMANDS
=============

|	**bpftool** **prog { show | list }** [*PROG*]
|	**bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}]
|	**bpftool** **prog dump jited**  *PROG* [{**file** *FILE* | **opcodes** | **linum**}]
|	**bpftool** **prog pin** *PROG* *FILE*
|	**bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
|	**bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
|	**bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
|	**bpftool** **prog tracelog**
|	**bpftool** **prog help**
|
|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
|	*TYPE* := {
|		**socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
|		**tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
|		**cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
|		**lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
|		**cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
|		**cgroup/connect4** | **cgroup/connect6** | **cgroup/sendmsg4** | **cgroup/sendmsg6** |
|		**cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/sysctl**
|	}
|       *ATTACH_TYPE* := {
|		**msg_verdict** | **stream_verdict** | **stream_parser** | **flow_dissector**
|	}


DESCRIPTION
===========
	**bpftool prog { show | list }** [*PROG*]
		  Show information about loaded programs.  If *PROG* is
		  specified show information only about given program, otherwise
		  list all programs currently loaded on the system.

		  Output will start with program ID followed by program type and
		  zero or more named attributes (depending on kernel version).

		  Since Linux 5.1 the kernel can collect statistics on BPF
		  programs (such as the total time spent running the program,
		  and the number of times it was run). If available, bpftool
		  shows such statistics. However, the kernel does not collect
		  them by defaults, as it slightly impacts performance on each
		  program run. Activation or deactivation of the feature is
		  performed via the **kernel.bpf_stats_enabled** sysctl knob.

	**bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** | **linum** }]
		  Dump eBPF instructions of the program from the kernel. By
		  default, eBPF will be disassembled and printed to standard
		  output in human-readable format. In this case, **opcodes**
		  controls if raw opcodes should be printed as well.

		  If **file** is specified, the binary image will instead be
		  written to *FILE*.

		  If **visual** is specified, control flow graph (CFG) will be
		  built instead, and eBPF instructions will be presented with
		  CFG in DOT format, on standard output.

		  If the prog has line_info available, the source line will
		  be displayed by default.  If **linum** is specified,
		  the filename, line number and line column will also be
		  displayed on top of the source line.

	**bpftool prog dump jited**  *PROG* [{ **file** *FILE* | **opcodes** | **linum** }]
		  Dump jited image (host machine code) of the program.
		  If *FILE* is specified image will be written to a file,
		  otherwise it will be disassembled and printed to stdout.

		  **opcodes** controls if raw opcodes will be printed.

		  If the prog has line_info available, the source line will
		  be displayed by default.  If **linum** is specified,
		  the filename, line number and line column will also be
		  displayed on top of the source line.

	**bpftool prog pin** *PROG* *FILE*
		  Pin program *PROG* 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 prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
		  Load bpf program(s) from binary *OBJ* and pin as *PATH*.
		  **bpftool prog load** pins only the first program from the
		  *OBJ* as *PATH*. **bpftool prog loadall** pins all programs
		  from the *OBJ* under *PATH* directory.
		  **type** is optional, if not specified program type will be
		  inferred from section names.
		  By default bpftool will create new maps as declared in the ELF
		  object being loaded.  **map** parameter allows for the reuse
		  of existing maps.  It can be specified multiple times, each
		  time for a different map.  *IDX* refers to index of the map
		  to be replaced in the ELF file counting from 0, while *NAME*
		  allows to replace a map by name.  *MAP* specifies the map to
		  use, referring to it by **id** or through a **pinned** file.
		  If **dev** *NAME* is specified program will be loaded onto
		  given networking device (offload).
		  Optional **pinmaps** argument can be provided to pin all
		  maps under *MAP_DIR* directory.

		  Note: *PATH* must be located in *bpffs* mount. It must not
		  contain a dot character ('.'), which is reserved for future
		  extensions of *bpffs*.

	**bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
		  Attach bpf program *PROG* (with type specified by
		  *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
		  parameter, with the exception of *flow_dissector* which is
		  attached to current networking name space.

	**bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
		  Detach bpf program *PROG* (with type specified by
		  *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
		  parameter, with the exception of *flow_dissector* which is
		  detached from the current networking name space.

	**bpftool prog tracelog**
		  Dump the trace pipe of the system to the console (stdout).
		  Hit <Ctrl+C> to stop printing. BPF programs can write to this
		  trace pipe at runtime with the **bpf_trace_printk()** helper.
		  This should be used only for debugging purposes. For
		  streaming data from BPF programs to user space, one can use
		  perf events (see also **bpftool-map**\ (8)).

	**bpftool prog 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 programs, show file names of pinned
		  programs.

	-m, --mapcompat
		  Allow loading maps with unknown map definitions.

	-n, --nomount
		  Do not automatically attempt to mount any virtual file system
		  (such as tracefs or BPF virtual file system) when necessary.

EXAMPLES
========
**# bpftool prog show**

::

    10: xdp  name some_prog  tag 005a3d2123620c8b  gpl run_time_ns 81632 run_cnt 10
            loaded_at 2017-09-29T20:11:00+0000  uid 0
            xlated 528B  jited 370B  memlock 4096B  map_ids 10

**# bpftool --json --pretty prog show**

::

    [{
            "id": 10,
            "type": "xdp",
            "tag": "005a3d2123620c8b",
            "gpl_compatible": true,
            "run_time_ns": 81632,
            "run_cnt": 10,
            "loaded_at": 1506715860,
            "uid": 0,
            "bytes_xlated": 528,
            "jited": true,
            "bytes_jited": 370,
            "bytes_memlock": 4096,
            "map_ids": [10
            ]
        }
    ]

|
| **# bpftool prog dump xlated id 10 file /tmp/t**
| **# ls -l /tmp/t**

::

    -rw------- 1 root root 560 Jul 22 01:42 /tmp/t

**# bpftool prog dump jited tag 005a3d2123620c8b**

::

    0:   push   %rbp
    1:   mov    %rsp,%rbp
    2:   sub    $0x228,%rsp
    3:   sub    $0x28,%rbp
    4:   mov    %rbx,0x0(%rbp)

|
| **# mount -t bpf none /sys/fs/bpf/**
| **# bpftool prog pin id 10 /sys/fs/bpf/prog**
| **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
| **# ls -l /sys/fs/bpf/**

::

    -rw------- 1 root root 0 Jul 22 01:43 prog
    -rw------- 1 root root 0 Jul 22 01:44 prog2

**# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes**

::

   0:   push   %rbp
        55
   1:   mov    %rsp,%rbp
        48 89 e5
   4:   sub    $0x228,%rsp
        48 81 ec 28 02 00 00
   b:   sub    $0x28,%rbp
        48 83 ed 28
   f:   mov    %rbx,0x0(%rbp)
        48 89 5d 00

|
| **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
| **# bpftool prog show pinned /sys/fs/bpf/xdp1**

::

    9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
            loaded_at 2018-06-25T16:17:31-0700  uid 0
            xlated 488B  jited 336B  memlock 4096B  map_ids 7

**# rm /sys/fs/bpf/xdp1**

SEE ALSO
========
	**bpf**\ (2),
	**bpf-helpers**\ (7),
	**bpftool**\ (8),
	**bpftool-map**\ (8),
	**bpftool-cgroup**\ (8),
	**bpftool-feature**\ (8),
	**bpftool-net**\ (8),
	**bpftool-perf**\ (8),
	**bpftool-btf**\ (8)
Commit	Line	Data
ff69c21a JK	1	================
	2	bpftool-prog
	3	================
	4	-------------------------------------------------------------------------------
	5	tool for inspection and simple manipulation of eBPF progs
	6	-------------------------------------------------------------------------------
	7
	8	:Manual section: 8
	9
	10	SYNOPSIS
	11	========
	12
0641c3c8 QM	13	bpftool [OPTIONS] prog COMMAND
0641c3c8 QM	14
c541b734	15	OPTIONS := { { -j \| --json } [{ -p \| --pretty }] \| { -f \| --bpffs } }
0641c3c8 QM	16
0641c3c8 QM	17	COMMANDS :=
77380998 SF	18	{ show \| list \| dump xlated \| dump jited \| pin \| load
77380998 SF	19	\| loadall \| help }
0641c3c8	20
a5f2d082	21	PROG COMMANDS
0641c3c8 QM	22	=============
0641c3c8 QM	23
6ebe6dbd	24	\| bpftool prog { show \| list } [PROG]
b053b439 MKL	25	\| bpftool prog dump xlated PROG [{file FILE \| opcodes \| visual \| linum}]
b053b439 MKL	26	\| bpftool prog dump jited PROG [{file FILE \| opcodes \| linum}]
47ff7ac6	27	\| bpftool prog pin PROG FILE
9a487883	28	\| bpftool prog { load \| loadall } OBJ PATH [type TYPE] [map {idx IDX \| name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
30da46b5 QM	29	\| bpftool prog attach PROG ATTACH_TYPE [MAP]
	30	\| bpftool prog detach PROG ATTACH_TYPE [MAP]
	31	\| bpftool prog tracelog
47ff7ac6	32	\| bpftool prog help
ff69c21a	33	\|
3ff5a4dc	34	\| MAP := { id MAP_ID \| pinned FILE }
47ff7ac6	35	\| PROG := { id PROG_ID \| pinned FILE \| tag PROG_TAG }
49f2cba3 JK	36	\| TYPE := {
	37	\| socket \| kprobe \| kretprobe \| classifier \| action \|
	38	\| tracepoint \| raw_tracepoint \| xdp \| perf_event \| cgroup/skb \|
	39	\| cgroup/sock \| cgroup/dev \| lwt_in \| lwt_out \| lwt_xmit \|
	40	\| lwt_seg6local \| sockops \| sk_skb \| sk_msg \| lirc_mode2 \|
	41	\| cgroup/bind4 \| cgroup/bind6 \| cgroup/post_bind4 \| cgroup/post_bind6 \|
f25377ee	42	\| cgroup/connect4 \| cgroup/connect6 \| cgroup/sendmsg4 \| cgroup/sendmsg6 \|
000aa125	43	\| cgroup/recvmsg4 \| cgroup/recvmsg6 \| cgroup/sysctl
49f2cba3	44	\| }
092f0892	45	\| ATTACH_TYPE := {
a5d9265e	46	\| msg_verdict \| stream_verdict \| stream_parser \| flow_dissector
092f0892	47	\| }
49f2cba3	48
ff69c21a JK	49
	50	DESCRIPTION
	51	===========
6ebe6dbd	52	bpftool prog { show \| list } [PROG]
ff69c21a JK	53	Show information about loaded programs. If PROG is
	54	specified show information only about given program, otherwise
	55	list all programs currently loaded on the system.
	56
	57	Output will start with program ID followed by program type and
	58	zero or more named attributes (depending on kernel version).
	59
25df480d QM	60	Since Linux 5.1 the kernel can collect statistics on BPF
	61	programs (such as the total time spent running the program,
	62	and the number of times it was run). If available, bpftool
	63	shows such statistics. However, the kernel does not collect
	64	them by defaults, as it slightly impacts performance on each
	65	program run. Activation or deactivation of the feature is
	66	performed via the kernel.bpf_stats_enabled sysctl knob.
	67
b053b439	68	bpftool prog dump xlated PROG [{ file FILE \| opcodes \| visual \| linum }]
b6c1cedb JW	69	Dump eBPF instructions of the program from the kernel. By
	70	default, eBPF will be disassembled and printed to standard
	71	output in human-readable format. In this case, opcodes
	72	controls if raw opcodes should be printed as well.
c9c35995	73
b6c1cedb JW	74	If file is specified, the binary image will instead be
	75	written to FILE.
	76
	77	If visual is specified, control flow graph (CFG) will be
	78	built instead, and eBPF instructions will be presented with
	79	CFG in DOT format, on standard output.
ff69c21a	80
b053b439 MKL	81	If the prog has line_info available, the source line will
	82	be displayed by default. If linum is specified,
	83	the filename, line number and line column will also be
	84	displayed on top of the source line.
10a5ce98	85
b053b439	86	bpftool prog dump jited PROG [{ file FILE \| opcodes \| linum }]
ff69c21a JK	87	Dump jited image (host machine code) of the program.
	88	If FILE is specified image will be written to a file,
	89	otherwise it will be disassembled and printed to stdout.
	90
	91	opcodes controls if raw opcodes will be printed.
	92
b053b439 MKL	93	If the prog has line_info available, the source line will
	94	be displayed by default. If linum is specified,
	95	the filename, line number and line column will also be
	96	displayed on top of the source line.
10a5ce98	97
ff69c21a JK	98	bpftool prog pin PROG FILE
	99	Pin program PROG as FILE.
	100
882731e0 QM	101	Note: FILE must be located in bpffs mount. It must not
	102	contain a dot character ('.'), which is reserved for future
	103	extensions of bpffs.
ff69c21a	104
3767a94b	105	bpftool prog { load \| loadall } OBJ PATH [type TYPE] [map {idx IDX \| name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
77380998 SF	106	Load bpf program(s) from binary OBJ and pin as PATH.
	107	bpftool prog load pins only the first program from the
	108	OBJ as PATH. bpftool prog loadall pins all programs
	109	from the OBJ under PATH directory.
49f2cba3 JK	110	type is optional, if not specified program type will be
49f2cba3 JK	111	inferred from section names.
3ff5a4dc JK	112	By default bpftool will create new maps as declared in the ELF
	113	object being loaded. map parameter allows for the reuse
	114	of existing maps. It can be specified multiple times, each
	115	time for a different map. IDX refers to index of the map
	116	to be replaced in the ELF file counting from 0, while NAME
	117	allows to replace a map by name. MAP specifies the map to
	118	use, referring to it by id or through a pinned file.
ba6dd679 JK	119	If dev NAME is specified program will be loaded onto
ba6dd679 JK	120	given networking device (offload).
3767a94b SF	121	Optional pinmaps argument can be provided to pin all
3767a94b SF	122	maps under MAP_DIR directory.
49a086c2	123
77380998	124	Note: PATH must be located in bpffs mount. It must not
882731e0 QM	125	contain a dot character ('.'), which is reserved for future
882731e0 QM	126	extensions of bpffs.
49a086c2	127
092f0892 SF	128	bpftool prog attach PROG ATTACH_TYPE [MAP]
	129	Attach bpf program PROG (with type specified by
	130	ATTACH_TYPE). Most ATTACH_TYPEs require a MAP
	131	parameter, with the exception of flow_dissector which is
	132	attached to current networking name space.
	133
	134	bpftool prog detach PROG ATTACH_TYPE [MAP]
	135	Detach bpf program PROG (with type specified by
	136	ATTACH_TYPE). Most ATTACH_TYPEs require a MAP
	137	parameter, with the exception of flow_dissector which is
	138	detached from the current networking name space.
b7d3826c	139
30da46b5 QM	140	bpftool prog tracelog
	141	Dump the trace pipe of the system to the console (stdout).
	142	Hit <Ctrl+C> to stop printing. BPF programs can write to this
	143	trace pipe at runtime with the bpf_trace_printk() helper.
	144	This should be used only for debugging purposes. For
	145	streaming data from BPF programs to user space, one can use
	146	perf events (see also bpftool-map\ (8)).
	147
ff69c21a JK	148	bpftool prog help
	149	Print short help message.
	150
a2bc2e5c QM	151	OPTIONS
	152	=======
	153	-h, --help
	154	Print short generic help message (similar to bpftool help).
	155
88b3eed8	156	-V, --version
a2bc2e5c QM	157	Print version number (similar to bpftool version).
a2bc2e5c QM	158
0641c3c8 QM	159	-j, --json
	160	Generate JSON output. For commands that cannot produce JSON, this
	161	option has no effect.
	162
	163	-p, --pretty
	164	Generate human-readable JSON output. Implies -j.
	165
c541b734	166	-f, --bpffs
a8bfd2bc QM	167	When showing BPF programs, show file names of pinned
a8bfd2bc QM	168	programs.
c541b734	169
bc6cd664 QM	170	-m, --mapcompat
	171	Allow loading maps with unknown map definitions.
	172
33221307 QM	173	-n, --nomount
	174	Do not automatically attempt to mount any virtual file system
	175	(such as tracefs or BPF virtual file system) when necessary.
	176
ff69c21a JK	177	EXAMPLES
	178	========
	179	# bpftool prog show
32870ba4	180
ff69c21a JK	181	::
ff69c21a JK	182
88ad472b	183	10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
32870ba4 QM	184	loaded_at 2017-09-29T20:11:00+0000 uid 0
32870ba4 QM	185	xlated 528B jited 370B memlock 4096B map_ids 10
ff69c21a	186
0641c3c8 QM	187	# bpftool --json --pretty prog show
	188
	189	::
	190
32870ba4 QM	191	[{
	192	"id": 10,
	193	"type": "xdp",
	194	"tag": "005a3d2123620c8b",
	195	"gpl_compatible": true,
88ad472b AS	196	"run_time_ns": 81632,
88ad472b AS	197	"run_cnt": 10,
32870ba4 QM	198	"loaded_at": 1506715860,
	199	"uid": 0,
	200	"bytes_xlated": 528,
	201	"jited": true,
	202	"bytes_jited": 370,
	203	"bytes_memlock": 4096,
	204	"map_ids": [10
	205	]
	206	}
	207	]
0641c3c8	208
ff69c21a JK	209	\|
	210	\| # bpftool prog dump xlated id 10 file /tmp/t
	211	\| # ls -l /tmp/t
ff69c21a	212
32870ba4 QM	213	::
	214
	215	-rw------- 1 root root 560 Jul 22 01:42 /tmp/t
	216
	217	# bpftool prog dump jited tag 005a3d2123620c8b
ff69c21a JK	218
	219	::
	220
32870ba4 QM	221	0: push %rbp
	222	1: mov %rsp,%rbp
	223	2: sub $0x228,%rsp
	224	3: sub $0x28,%rbp
	225	4: mov %rbx,0x0(%rbp)
ff69c21a	226
0641c3c8 QM	227	\|
	228	\| # mount -t bpf none /sys/fs/bpf/
	229	\| # bpftool prog pin id 10 /sys/fs/bpf/prog
49a086c2	230	\| # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
0641c3c8	231	\| # ls -l /sys/fs/bpf/
0641c3c8	232
32870ba4 QM	233	::
	234
	235	-rw------- 1 root root 0 Jul 22 01:43 prog
	236	-rw------- 1 root root 0 Jul 22 01:44 prog2
	237
	238	# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
0641c3c8 QM	239
	240	::
	241
32870ba4 QM	242	0: push %rbp
	243	55
	244	1: mov %rsp,%rbp
	245	48 89 e5
	246	4: sub $0x228,%rsp
	247	48 81 ec 28 02 00 00
	248	b: sub $0x28,%rbp
	249	48 83 ed 28
	250	f: mov %rbx,0x0(%rbp)
	251	48 89 5d 00
ff69c21a	252
3ff5a4dc JK	253	\|
	254	\| # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
	255	\| # bpftool prog show pinned /sys/fs/bpf/xdp1
32870ba4 QM	256
	257	::
	258
	259	9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
	260	loaded_at 2018-06-25T16:17:31-0700 uid 0
	261	xlated 488B jited 336B memlock 4096B map_ids 7
	262
	263	# rm /sys/fs/bpf/xdp1
ff69c21a JK	264
	265	SEE ALSO
	266	========
f98e46a2 QM	267	bpf\ (2),
	268	bpf-helpers\ (7),
	269	bpftool\ (8),
	270	bpftool-map\ (8),
	271	bpftool-cgroup\ (8),
49eb7ab3	272	bpftool-feature\ (8),
f98e46a2	273	bpftool-net\ (8),
ca253339 AN	274	bpftool-perf\ (8),
ca253339 AN	275	bpftool-btf\ (8)