[linux.git] / tools / bpf / bpftool / Documentation / bpftool-cgroup.rst

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

:Manual section: 8

SYNOPSIS
========

	**bpftool** [*OPTIONS*] **cgroup** *COMMAND*

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

	*COMMANDS* :=
	{ **show** | **list** | **tree** | **attach** | **detach** | **help** }

MAP COMMANDS
=============

|	**bpftool** **cgroup { show | list }** *CGROUP*
|	**bpftool** **cgroup tree** [*CGROUP_ROOT*]
|	**bpftool** **cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
|	**bpftool** **cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
|	**bpftool** **cgroup help**
|
|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
|	*ATTACH_TYPE* := { **ingress** | **egress** | **sock_create** | **sock_ops** | **device** |
|		**bind4** | **bind6** | **post_bind4** | **post_bind6** | **connect4** | **connect6** |
|               **sendmsg4** | **sendmsg6** }
|	*ATTACH_FLAGS* := { **multi** | **override** }

DESCRIPTION
===========
	**bpftool cgroup { show | list }** *CGROUP*
		  List all programs attached to the cgroup *CGROUP*.

		  Output will start with program ID followed by attach type,
		  attach flags and program name.

	**bpftool cgroup tree** [*CGROUP_ROOT*]
		  Iterate over all cgroups in *CGROUP_ROOT* and list all
		  attached programs. If *CGROUP_ROOT* is not specified,
		  bpftool uses cgroup v2 mountpoint.

		  The output is similar to the output of cgroup show/list
		  commands: it starts with absolute cgroup path, followed by
		  program ID, attach type, attach flags and program name.

	**bpftool cgroup attach** *CGROUP* *ATTACH_TYPE* *PROG* [*ATTACH_FLAGS*]
		  Attach program *PROG* to the cgroup *CGROUP* with attach type
		  *ATTACH_TYPE* and optional *ATTACH_FLAGS*.

		  *ATTACH_FLAGS* can be one of: **override** if a sub-cgroup installs
		  some bpf program, the program in this cgroup yields to sub-cgroup
		  program; **multi** if a sub-cgroup installs some bpf program,
		  that cgroup program gets run in addition to the program in this
		  cgroup.

		  Only one program is allowed to be attached to a cgroup with
		  no attach flags or the **override** flag. Attaching another
		  program will release old program and attach the new one.

		  Multiple programs are allowed to be attached to a cgroup with
		  **multi**. They are executed in FIFO order (those that were
		  attached first, run first).

		  Non-default *ATTACH_FLAGS* are supported by kernel version 4.14
		  and later.

		  *ATTACH_TYPE* can be on of:
		  **ingress** ingress path of the inet socket (since 4.10);
		  **egress** egress path of the inet socket (since 4.10);
		  **sock_create** opening of an inet socket (since 4.10);
		  **sock_ops** various socket operations (since 4.12);
		  **device** device access (since 4.15);
		  **bind4** call to bind(2) for an inet4 socket (since 4.17);
		  **bind6** call to bind(2) for an inet6 socket (since 4.17);
		  **post_bind4** return from bind(2) for an inet4 socket (since 4.17);
		  **post_bind6** return from bind(2) for an inet6 socket (since 4.17);
		  **connect4** call to connect(2) for an inet4 socket (since 4.17);
		  **connect6** call to connect(2) for an inet6 socket (since 4.17);
		  **sendmsg4** call to sendto(2), sendmsg(2), sendmmsg(2) for an
		  unconnected udp4 socket (since 4.18);
		  **sendmsg6** call to sendto(2), sendmsg(2), sendmmsg(2) for an
		  unconnected udp6 socket (since 4.18).

	**bpftool cgroup detach** *CGROUP* *ATTACH_TYPE* *PROG*
		  Detach *PROG* from the cgroup *CGROUP* and attach type
		  *ATTACH_TYPE*.

	**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
		  Show file names of pinned programs.

EXAMPLES
========
|
| **# mount -t bpf none /sys/fs/bpf/**
| **# mkdir /sys/fs/cgroup/test.slice**
| **# bpftool prog load ./device_cgroup.o /sys/fs/bpf/prog**
| **# bpftool cgroup attach /sys/fs/cgroup/test.slice/ device id 1 allow_multi**

**# bpftool cgroup list /sys/fs/cgroup/test.slice/**

::

    ID       AttachType      AttachFlags     Name
    1        device          allow_multi     bpf_prog1

|
| **# bpftool cgroup detach /sys/fs/cgroup/test.slice/ device id 1**
| **# bpftool cgroup list /sys/fs/cgroup/test.slice/**

::

    ID       AttachType      AttachFlags     Name

SEE ALSO
========
	**bpf**\ (2),
	**bpf-helpers**\ (7),
	**bpftool**\ (8),
	**bpftool-prog**\ (8),
	**bpftool-map**\ (8),
	**bpftool-net**\ (8),
	**bpftool-perf**\ (8)
Commit	Line	Data
5ccda64d RG	1	================
	2	bpftool-cgroup
	3	================
	4	-------------------------------------------------------------------------------
	5	tool for inspection and simple manipulation of eBPF progs
	6	-------------------------------------------------------------------------------
	7
	8	:Manual section: 8
	9
	10	SYNOPSIS
	11	========
	12
	13	bpftool [OPTIONS] cgroup COMMAND
	14
	15	OPTIONS := { { -j \| --json } [{ -p \| --pretty }] \| { -f \| --bpffs } }
	16
	17	COMMANDS :=
7d31a0a1	18	{ show \| list \| tree \| attach \| detach \| help }
5ccda64d RG	19
	20	MAP COMMANDS
	21	=============
	22
6ebe6dbd	23	\| bpftool cgroup { show \| list } CGROUP
7d31a0a1	24	\| bpftool cgroup tree [CGROUP_ROOT]
5ccda64d RG	25	\| bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS]
	26	\| bpftool cgroup detach CGROUP ATTACH_TYPE PROG
	27	\| bpftool cgroup help
	28	\|
	29	\| PROG := { id PROG_ID \| pinned FILE \| tag PROG_TAG }
393de512	30	\| ATTACH_TYPE := { ingress \| egress \| sock_create \| sock_ops \| device \|
13a370b9 AI	31	\| bind4 \| bind6 \| post_bind4 \| post_bind6 \| connect4 \| connect6 \|
13a370b9 AI	32	\| sendmsg4 \| sendmsg6 }
a827a164	33	\| ATTACH_FLAGS := { multi \| override }
5ccda64d RG	34
	35	DESCRIPTION
	36	===========
6ebe6dbd	37	bpftool cgroup { show \| list } CGROUP
5ccda64d RG	38	List all programs attached to the cgroup CGROUP.
	39
	40	Output will start with program ID followed by attach type,
	41	attach flags and program name.
	42
7d31a0a1 RG	43	bpftool cgroup tree [CGROUP_ROOT]
	44	Iterate over all cgroups in CGROUP_ROOT and list all
	45	attached programs. If CGROUP_ROOT is not specified,
	46	bpftool uses cgroup v2 mountpoint.
	47
	48	The output is similar to the output of cgroup show/list
	49	commands: it starts with absolute cgroup path, followed by
	50	program ID, attach type, attach flags and program name.
	51
5ccda64d RG	52	bpftool cgroup attach CGROUP ATTACH_TYPE PROG [ATTACH_FLAGS]
	53	Attach program PROG to the cgroup CGROUP with attach type
	54	ATTACH_TYPE and optional ATTACH_FLAGS.
	55
	56	ATTACH_FLAGS can be one of: override if a sub-cgroup installs
	57	some bpf program, the program in this cgroup yields to sub-cgroup
	58	program; multi if a sub-cgroup installs some bpf program,
	59	that cgroup program gets run in addition to the program in this
	60	cgroup.
	61
	62	Only one program is allowed to be attached to a cgroup with
	63	no attach flags or the override flag. Attaching another
	64	program will release old program and attach the new one.
	65
	66	Multiple programs are allowed to be attached to a cgroup with
	67	multi. They are executed in FIFO order (those that were
	68	attached first, run first).
	69
	70	Non-default ATTACH_FLAGS are supported by kernel version 4.14
	71	and later.
	72
	73	ATTACH_TYPE can be on of:
	74	ingress ingress path of the inet socket (since 4.10);
	75	egress egress path of the inet socket (since 4.10);
	76	sock_create opening of an inet socket (since 4.10);
	77	sock_ops various socket operations (since 4.12);
393de512 AI	78	device device access (since 4.15);
	79	bind4 call to bind(2) for an inet4 socket (since 4.17);
	80	bind6 call to bind(2) for an inet6 socket (since 4.17);
	81	post_bind4 return from bind(2) for an inet4 socket (since 4.17);
	82	post_bind6 return from bind(2) for an inet6 socket (since 4.17);
	83	connect4 call to connect(2) for an inet4 socket (since 4.17);
13a370b9 AI	84	connect6 call to connect(2) for an inet6 socket (since 4.17);
	85	sendmsg4 call to sendto(2), sendmsg(2), sendmmsg(2) for an
	86	unconnected udp4 socket (since 4.18);
	87	sendmsg6 call to sendto(2), sendmsg(2), sendmmsg(2) for an
	88	unconnected udp6 socket (since 4.18).
5ccda64d RG	89
	90	bpftool cgroup detach CGROUP ATTACH_TYPE PROG
	91	Detach PROG from the cgroup CGROUP and attach type
	92	ATTACH_TYPE.
	93
	94	bpftool prog help
	95	Print short help message.
	96
	97	OPTIONS
	98	=======
	99	-h, --help
	100	Print short generic help message (similar to bpftool help).
	101
	102	-v, --version
	103	Print version number (similar to bpftool version).
	104
	105	-j, --json
	106	Generate JSON output. For commands that cannot produce JSON, this
	107	option has no effect.
	108
	109	-p, --pretty
	110	Generate human-readable JSON output. Implies -j.
	111
	112	-f, --bpffs
	113	Show file names of pinned programs.
	114
	115	EXAMPLES
	116	========
	117	\|
	118	\| # mount -t bpf none /sys/fs/bpf/
	119	\| # mkdir /sys/fs/cgroup/test.slice
	120	\| # bpftool prog load ./device_cgroup.o /sys/fs/bpf/prog
	121	\| # bpftool cgroup attach /sys/fs/cgroup/test.slice/ device id 1 allow_multi
	122
	123	# bpftool cgroup list /sys/fs/cgroup/test.slice/
	124
	125	::
	126
	127	ID AttachType AttachFlags Name
	128	1 device allow_multi bpf_prog1
	129
	130	\|
	131	\| # bpftool cgroup detach /sys/fs/cgroup/test.slice/ device id 1
	132	\| # bpftool cgroup list /sys/fs/cgroup/test.slice/
	133
	134	::
	135
	136	ID AttachType AttachFlags Name
	137
	138	SEE ALSO
	139	========
f98e46a2 QM	140	bpf\ (2),
	141	bpf-helpers\ (7),
	142	bpftool\ (8),
	143	bpftool-prog\ (8),
	144	bpftool-map\ (8),
	145	bpftool-net\ (8),
	146	bpftool-perf\ (8)