[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** }

MAP 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*]
|	**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**
|	}
|       *ATTACH_TYPE* := {
|		**msg_verdict** | **skb_verdict** | **skb_parse** | **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).

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

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

  10: xdp  name some_prog  tag 005a3d2123620c8b  gpl
	loaded_at Sep 29/20:11  uid 0
	xlated 528B  jited 370B  memlock 4096B  map_ids 10

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

::

    {
        "programs": [{
                "id": 10,
                "type": "xdp",
                "tag": "005a3d2123620c8b",
                "gpl_compatible": true,
                "loaded_at": "Sep 29/20:11",
                "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 dum jited tag 005a3d2123620c8b**

::

    push   %rbp
    mov    %rsp,%rbp
    sub    $0x228,%rsp
    sub    $0x28,%rbp
    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 dum jited pinned /sys/fs/bpf/prog opcodes**

::

    push   %rbp
    55
    mov    %rsp,%rbp
    48 89 e5
    sub    $0x228,%rsp
    48 81 ec 28 02 00 00
    sub    $0x28,%rbp
    48 83 ed 28
    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-net**\ (8),
	**bpftool-perf**\ (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 QM	20
	21	MAP COMMANDS
	22	=============
	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
77380998	28	\| bpftool prog { load \| loadall } OBJ PATH [type TYPE] [map {idx IDX \| name NAME} MAP] [dev NAME]
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 \|
	42	\| cgroup/connect4 \| cgroup/connect6 \| cgroup/sendmsg4 \| cgroup/sendmsg6
	43	\| }
092f0892 SF	44	\| ATTACH_TYPE := {
	45	\| msg_verdict \| skb_verdict \| skb_parse \| flow_dissector
	46	\| }
49f2cba3	47
ff69c21a JK	48
	49	DESCRIPTION
	50	===========
6ebe6dbd	51	bpftool prog { show \| list } [PROG]
ff69c21a JK	52	Show information about loaded programs. If PROG is
	53	specified show information only about given program, otherwise
	54	list all programs currently loaded on the system.
	55
	56	Output will start with program ID followed by program type and
	57	zero or more named attributes (depending on kernel version).
	58
b053b439	59	bpftool prog dump xlated PROG [{ file FILE \| opcodes \| visual \| linum }]
b6c1cedb JW	60	Dump eBPF instructions of the program from the kernel. By
	61	default, eBPF will be disassembled and printed to standard
	62	output in human-readable format. In this case, opcodes
	63	controls if raw opcodes should be printed as well.
c9c35995	64
b6c1cedb JW	65	If file is specified, the binary image will instead be
	66	written to FILE.
	67
	68	If visual is specified, control flow graph (CFG) will be
	69	built instead, and eBPF instructions will be presented with
	70	CFG in DOT format, on standard output.
ff69c21a	71
b053b439 MKL	72	If the prog has line_info available, the source line will
	73	be displayed by default. If linum is specified,
	74	the filename, line number and line column will also be
	75	displayed on top of the source line.
10a5ce98	76
b053b439	77	bpftool prog dump jited PROG [{ file FILE \| opcodes \| linum }]
ff69c21a JK	78	Dump jited image (host machine code) of the program.
	79	If FILE is specified image will be written to a file,
	80	otherwise it will be disassembled and printed to stdout.
	81
	82	opcodes controls if raw opcodes will be printed.
	83
b053b439 MKL	84	If the prog has line_info available, the source line will
	85	be displayed by default. If linum is specified,
	86	the filename, line number and line column will also be
	87	displayed on top of the source line.
10a5ce98	88
ff69c21a JK	89	bpftool prog pin PROG FILE
	90	Pin program PROG as FILE.
	91
882731e0 QM	92	Note: FILE must be located in bpffs mount. It must not
	93	contain a dot character ('.'), which is reserved for future
	94	extensions of bpffs.
ff69c21a	95
3767a94b	96	bpftool prog { load \| loadall } OBJ PATH [type TYPE] [map {idx IDX \| name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
77380998 SF	97	Load bpf program(s) from binary OBJ and pin as PATH.
	98	bpftool prog load pins only the first program from the
	99	OBJ as PATH. bpftool prog loadall pins all programs
	100	from the OBJ under PATH directory.
49f2cba3 JK	101	type is optional, if not specified program type will be
49f2cba3 JK	102	inferred from section names.
3ff5a4dc JK	103	By default bpftool will create new maps as declared in the ELF
	104	object being loaded. map parameter allows for the reuse
	105	of existing maps. It can be specified multiple times, each
	106	time for a different map. IDX refers to index of the map
	107	to be replaced in the ELF file counting from 0, while NAME
	108	allows to replace a map by name. MAP specifies the map to
	109	use, referring to it by id or through a pinned file.
ba6dd679 JK	110	If dev NAME is specified program will be loaded onto
ba6dd679 JK	111	given networking device (offload).
3767a94b SF	112	Optional pinmaps argument can be provided to pin all
3767a94b SF	113	maps under MAP_DIR directory.
49a086c2	114
77380998	115	Note: PATH must be located in bpffs mount. It must not
882731e0 QM	116	contain a dot character ('.'), which is reserved for future
882731e0 QM	117	extensions of bpffs.
49a086c2	118
092f0892 SF	119	bpftool prog attach PROG ATTACH_TYPE [MAP]
	120	Attach bpf program PROG (with type specified by
	121	ATTACH_TYPE). Most ATTACH_TYPEs require a MAP
	122	parameter, with the exception of flow_dissector which is
	123	attached to current networking name space.
	124
	125	bpftool prog detach PROG ATTACH_TYPE [MAP]
	126	Detach bpf program PROG (with type specified by
	127	ATTACH_TYPE). Most ATTACH_TYPEs require a MAP
	128	parameter, with the exception of flow_dissector which is
	129	detached from the current networking name space.
b7d3826c	130
30da46b5 QM	131	bpftool prog tracelog
	132	Dump the trace pipe of the system to the console (stdout).
	133	Hit <Ctrl+C> to stop printing. BPF programs can write to this
	134	trace pipe at runtime with the bpf_trace_printk() helper.
	135	This should be used only for debugging purposes. For
	136	streaming data from BPF programs to user space, one can use
	137	perf events (see also bpftool-map\ (8)).
	138
ff69c21a JK	139	bpftool prog help
	140	Print short help message.
	141
a2bc2e5c QM	142	OPTIONS
	143	=======
	144	-h, --help
	145	Print short generic help message (similar to bpftool help).
	146
	147	-v, --version
	148	Print version number (similar to bpftool version).
	149
0641c3c8 QM	150	-j, --json
	151	Generate JSON output. For commands that cannot produce JSON, this
	152	option has no effect.
	153
	154	-p, --pretty
	155	Generate human-readable JSON output. Implies -j.
	156
c541b734	157	-f, --bpffs
a8bfd2bc QM	158	When showing BPF programs, show file names of pinned
a8bfd2bc QM	159	programs.
c541b734	160
ff69c21a JK	161	EXAMPLES
	162	========
	163	# bpftool prog show
	164	::
	165
9b984a20	166	10: xdp name some_prog tag 005a3d2123620c8b gpl
ff69c21a JK	167	loaded_at Sep 29/20:11 uid 0
	168	xlated 528B jited 370B memlock 4096B map_ids 10
	169
0641c3c8 QM	170	# bpftool --json --pretty prog show
	171
	172	::
	173
	174	{
	175	"programs": [{
	176	"id": 10,
	177	"type": "xdp",
	178	"tag": "005a3d2123620c8b",
9b984a20	179	"gpl_compatible": true,
0641c3c8 QM	180	"loaded_at": "Sep 29/20:11",
	181	"uid": 0,
	182	"bytes_xlated": 528,
	183	"jited": true,
	184	"bytes_jited": 370,
	185	"bytes_memlock": 4096,
	186	"map_ids": [10
	187	]
	188	}
	189	]
	190	}
	191
ff69c21a JK	192	\|
	193	\| # bpftool prog dump xlated id 10 file /tmp/t
	194	\| # ls -l /tmp/t
	195	\| -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
	196
0641c3c8	197	# bpftool prog dum jited tag 005a3d2123620c8b
ff69c21a JK	198
	199	::
	200
	201	push %rbp
	202	mov %rsp,%rbp
	203	sub $0x228,%rsp
	204	sub $0x28,%rbp
	205	mov %rbx,0x0(%rbp)
	206
0641c3c8 QM	207	\|
	208	\| # mount -t bpf none /sys/fs/bpf/
	209	\| # bpftool prog pin id 10 /sys/fs/bpf/prog
49a086c2	210	\| # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
0641c3c8 QM	211	\| # ls -l /sys/fs/bpf/
0641c3c8 QM	212	\| -rw------- 1 root root 0 Jul 22 01:43 prog
49a086c2	213	\| -rw------- 1 root root 0 Jul 22 01:44 prog2
0641c3c8 QM	214
	215	# bpftool prog dum jited pinned /sys/fs/bpf/prog opcodes
	216
	217	::
	218
	219	push %rbp
	220	55
	221	mov %rsp,%rbp
	222	48 89 e5
	223	sub $0x228,%rsp
	224	48 81 ec 28 02 00 00
	225	sub $0x28,%rbp
	226	48 83 ed 28
	227	mov %rbx,0x0(%rbp)
	228	48 89 5d 00
ff69c21a	229
3ff5a4dc JK	230	\|
	231	\| # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
	232	\| # bpftool prog show pinned /sys/fs/bpf/xdp1
	233	\| 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
	234	\| loaded_at 2018-06-25T16:17:31-0700 uid 0
	235	\| xlated 488B jited 336B memlock 4096B map_ids 7
	236	\| # rm /sys/fs/bpf/xdp1
	237	\|
ff69c21a JK	238
	239	SEE ALSO
	240	========
f98e46a2 QM	241	bpf\ (2),
	242	bpf-helpers\ (7),
	243	bpftool\ (8),
	244	bpftool-map\ (8),
	245	bpftool-cgroup\ (8),
	246	bpftool-net\ (8),
	247	bpftool-perf\ (8)