[linux-2.6-block.git] / Documentation / cgroup-v1 / devices.txt

Device Whitelist Controller

1. Description:

Implement a cgroup to track and enforce open and mknod restrictions
on device files.  A device cgroup associates a device access
whitelist with each cgroup.  A whitelist entry has 4 fields.
'type' is a (all), c (char), or b (block).  'all' means it applies
to all types and all major and minor numbers.  Major and minor are
either an integer or * for all.  Access is a composition of r
(read), w (write), and m (mknod).

The root device cgroup starts with rwm to 'all'.  A child device
cgroup gets a copy of the parent.  Administrators can then remove
devices from the whitelist or add new entries.  A child cgroup can
never receive a device access which is denied by its parent.

2. User Interface

An entry is added using devices.allow, and removed using
devices.deny.  For instance

	echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow

allows cgroup 1 to read and mknod the device usually known as
/dev/null.  Doing

	echo a > /sys/fs/cgroup/1/devices.deny

will remove the default 'a *:* rwm' entry. Doing

	echo a > /sys/fs/cgroup/1/devices.allow

will add the 'a *:* rwm' entry to the whitelist.

3. Security

Any task can move itself between cgroups.  This clearly won't
suffice, but we can decide the best way to adequately restrict
movement as people get some experience with this.  We may just want
to require CAP_SYS_ADMIN, which at least is a separate bit from
CAP_MKNOD.  We may want to just refuse moving to a cgroup which
isn't a descendant of the current one.  Or we may want to use
CAP_MAC_ADMIN, since we really are trying to lock down root.

CAP_SYS_ADMIN is needed to modify the whitelist or move another
task to a new cgroup.  (Again we'll probably want to change that).

A cgroup may not be granted more permissions than the cgroup's
parent has.

4. Hierarchy

device cgroups maintain hierarchy by making sure a cgroup never has more
access permissions than its parent.  Every time an entry is written to
a cgroup's devices.deny file, all its children will have that entry removed
from their whitelist and all the locally set whitelist entries will be
re-evaluated.  In case one of the locally set whitelist entries would provide
more access than the cgroup's parent, it'll be removed from the whitelist.

Example:
      A
     / \
        B

    group        behavior	exceptions
    A            allow		"b 8:* rwm", "c 116:1 rw"
    B            deny		"c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"

If a device is denied in group A:
	# echo "c 116:* r" > A/devices.deny
it'll propagate down and after revalidating B's entries, the whitelist entry
"c 116:2 rwm" will be removed:

    group        whitelist entries                        denied devices
    A            all                                      "b 8:* rwm", "c 116:* rw"
    B            "c 1:3 rwm", "b 3:* rwm"                 all the rest

In case parent's exceptions change and local exceptions are not allowed
anymore, they'll be deleted.

Notice that new whitelist entries will not be propagated:
      A
     / \
        B

    group        whitelist entries                        denied devices
    A            "c 1:3 rwm", "c 1:5 r"                   all the rest
    B            "c 1:3 rwm", "c 1:5 r"                   all the rest

when adding "c *:3 rwm":
	# echo "c *:3 rwm" >A/devices.allow

the result:
    group        whitelist entries                        denied devices
    A            "c *:3 rwm", "c 1:5 r"                   all the rest
    B            "c 1:3 rwm", "c 1:5 r"                   all the rest

but now it'll be possible to add new entries to B:
	# echo "c 2:3 rwm" >B/devices.allow
	# echo "c 50:3 r" >B/devices.allow
or even
	# echo "c *:3 rwm" >B/devices.allow

Allowing or denying all by writing 'a' to devices.allow or devices.deny will
not be possible once the device cgroups has children.

4.1 Hierarchy (internal implementation)

device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
list of exceptions.  The internal state is controlled using the same user
interface to preserve compatibility with the previous whitelist-only
implementation.  Removal or addition of exceptions that will reduce the access
to devices will be propagated down the hierarchy.
For every propagated exception, the effective rules will be re-evaluated based
on current parent's access rules.
Commit	Line	Data
08ce5f16 SH	1	Device Whitelist Controller
	2
	3	1. Description:
	4
	5	Implement a cgroup to track and enforce open and mknod restrictions
	6	on device files. A device cgroup associates a device access
	7	whitelist with each cgroup. A whitelist entry has 4 fields.
	8	'type' is a (all), c (char), or b (block). 'all' means it applies
	9	to all types and all major and minor numbers. Major and minor are
	10	either an integer or * for all. Access is a composition of r
	11	(read), w (write), and m (mknod).
	12
	13	The root device cgroup starts with rwm to 'all'. A child device
	14	cgroup gets a copy of the parent. Administrators can then remove
	15	devices from the whitelist or add new entries. A child cgroup can
bd2953eb	16	never receive a device access which is denied by its parent.
08ce5f16 SH	17
	18	2. User Interface
	19
	20	An entry is added using devices.allow, and removed using
	21	devices.deny. For instance
	22
f6e07d38	23	echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
08ce5f16 SH	24
	25	allows cgroup 1 to read and mknod the device usually known as
	26	/dev/null. Doing
	27
f6e07d38	28	echo a > /sys/fs/cgroup/1/devices.deny
08ce5f16	29
d823f6bf LZ	30	will remove the default 'a : rwm' entry. Doing
d823f6bf LZ	31
f6e07d38	32	echo a > /sys/fs/cgroup/1/devices.allow
d823f6bf LZ	33
d823f6bf LZ	34	will add the 'a : rwm' entry to the whitelist.
08ce5f16 SH	35
	36	3. Security
	37
	38	Any task can move itself between cgroups. This clearly won't
	39	suffice, but we can decide the best way to adequately restrict
	40	movement as people get some experience with this. We may just want
	41	to require CAP_SYS_ADMIN, which at least is a separate bit from
	42	CAP_MKNOD. We may want to just refuse moving to a cgroup which
caa790ba	43	isn't a descendant of the current one. Or we may want to use
08ce5f16 SH	44	CAP_MAC_ADMIN, since we really are trying to lock down root.
	45
	46	CAP_SYS_ADMIN is needed to modify the whitelist or move another
	47	task to a new cgroup. (Again we'll probably want to change that).
	48
	49	A cgroup may not be granted more permissions than the cgroup's
	50	parent has.
bd2953eb AR	51
	52	4. Hierarchy
	53
	54	device cgroups maintain hierarchy by making sure a cgroup never has more
	55	access permissions than its parent. Every time an entry is written to
	56	a cgroup's devices.deny file, all its children will have that entry removed
	57	from their whitelist and all the locally set whitelist entries will be
	58	re-evaluated. In case one of the locally set whitelist entries would provide
	59	more access than the cgroup's parent, it'll be removed from the whitelist.
	60
	61	Example:
	62	A
	63	/ \
	64	B
	65
	66	group behavior exceptions
	67	A allow "b 8:* rwm", "c 116:1 rw"
	68	B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
	69
	70	If a device is denied in group A:
	71	# echo "c 116:* r" > A/devices.deny
	72	it'll propagate down and after revalidating B's entries, the whitelist entry
	73	"c 116:2 rwm" will be removed:
	74
	75	group whitelist entries denied devices
	76	A all "b 8:* rwm", "c 116:* rw"
	77	B "c 1:3 rwm", "b 3:* rwm" all the rest
	78
	79	In case parent's exceptions change and local exceptions are not allowed
	80	anymore, they'll be deleted.
	81
	82	Notice that new whitelist entries will not be propagated:
	83	A
	84	/ \
	85	B
	86
	87	group whitelist entries denied devices
	88	A "c 1:3 rwm", "c 1:5 r" all the rest
	89	B "c 1:3 rwm", "c 1:5 r" all the rest
	90
	91	when adding "c *:3 rwm":
	92	# echo "c *:3 rwm" >A/devices.allow
	93
	94	the result:
	95	group whitelist entries denied devices
	96	A "c *:3 rwm", "c 1:5 r" all the rest
	97	B "c 1:3 rwm", "c 1:5 r" all the rest
	98
	99	but now it'll be possible to add new entries to B:
	100	# echo "c 2:3 rwm" >B/devices.allow
	101	# echo "c 50:3 r" >B/devices.allow
	102	or even
	103	# echo "c *:3 rwm" >B/devices.allow
	104
	105	Allowing or denying all by writing 'a' to devices.allow or devices.deny will
	106	not be possible once the device cgroups has children.
	107
	108	4.1 Hierarchy (internal implementation)
	109
	110	device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
	111	list of exceptions. The internal state is controlled using the same user
	112	interface to preserve compatibility with the previous whitelist-only
	113	implementation. Removal or addition of exceptions that will reduce the access
	114	to devices will be propagated down the hierarchy.
115	For every propagated exception, the effective rules will be re-evaluated based
116	on current parent's access rules.