1pam_cgfs(8)                                                        pam_cgfs(8)
2
3
4

NAME

6       pam_cgfs - cgroup management for unprivileged LXC containers.
7

SYNOPSIS

9       pam_cgfs.so {-c kernel_controller,name=named_controller}
10

DESCRIPTION

12       LXC  has  supported fully unprivileged containers since LXC 1.0.  Fully
13       unprivileged containers are the safest containers and are run by normal
14       (non-root)  users. This is achieved by using user namespaces by mapping
15       between a range of UIDs and GIDs on the host to a  different  (unprivi‐
16       leged)  range  of  UIDs and GIDs in the container. That means the uid 0
17       (root) in the container is mapped to an unprivileged user id (something
18       like 1000000) outside of the container and only has rights on resources
19       that it owns itself.
20
21       Cgroup management of fully unprivileged  containers  means  restricting
22       the resources used by these containers like limiting the CPU usage of a
23       container, or the number of processes it is allowed to  spawn,  or  the
24       memory  it  is  allowed to consume. It is clear that the fully unprivi‐
25       leged containers are run by normal users and there is a need  to  limit
26       and manage resource consumption among the containers.  But unprivileged
27       cgroup management  is  not  easy  with  most  init  systems.   So,  the
28       pam_cgfs.so came into existence.
29
30       The    pam_cgfs.so    module    can    handle    pure    cgroupfs    v1
31       (/sys/fs/cgroup/$controller) and mixed mounts, where  some  controllers
32       are  mounted  in a standard cgroupfs v1 hierarchy (/sys/fs/cgroup/$con‐
33       troller) and others in cgroupfs v2 hierarchy  (/sys/fs/cgroup/unified).
34       Writeable  cgroups are either created for all controllers or, if speci‐
35       fied, for only controllers listed as arguments  on  the  command  line.
36       Pure cgroup v2 mount is not covered by the pam_cgfs.so module.
37
38       The  cgroup  created  user/$user/n  will  be  for the nth session under
39       cgroup kernel controller hierarchy.
40
41       Systems with a systemd init system are treated specifically, both  with
42       respect  to  cgroupfs  v1  and  cgroupfs  v2. For both, cgroupfs v1 and
43       cgroupfs v2, the module checks whether systemd already placed the  user
44       in a cgroup it created user.slice/user-$uid/session-n.scope by checking
45       whether $uid == login uid.  If  so,  the  login  user  chown  the  ses‐
46       sion-n.scope, else a cgroup is created as outlined above (user/$user/n)
47       and chown it to login uid. If the init system has  already  placed  the
48       login  user  inside a session specific group, the pam_cgfs.so module is
49       smart enough to detect it and re-use the cgroup.
50
51       In essence, the pam_cgfs.so module takes care of  placing  unprivileged
52       (non-root)  users  into  writable cgroups at login and also cleaning up
53       these cgroup hierarchies on logout, so they are free  to  delegate  re‐
54       sources to containers as needed that have been provided to them.
55

OPTIONS

57       -c controller-list
58              Takes  a  string  argument  which  sets  the list of kernel con‐
59              trollers and named controllers delimited  by  commas  in-between
60              “,”.  Named  controllers  need  to  be  specified  in  the  form
61              “name=$namedcontroller”. Can use “all”  enable  all  cgroup  re‐
62              source  controller  hierarchies. Specifying “all” and other con‐
63              trollers explicitly returns PAM_SESSION_ERR.
64

MODULE TYPES PROVIDED

66       Only session module type is provided (and needed).
67

RETURN VALUES

69       PAM_SUCCESS
70              Writeable cgroups have been created for the user.
71
72       PAM_SESSION_ERR
73              Failed to create writable cgroups for the user.
74

FILES

76       /etc/pam.d/common-session{,-noninteractive}
77              Default configuration is added at the end of these files.
78

EXAMPLE

80       session optional    pam_cgfs.so -c freezer,memory,named=systemd
81       # default configuration
82       # user writable cgroups are created under freezer, memory and named cgroup systemd hierarchies.
83       # /sys/fs/cgroup/$controller/user/$user/n for freezer,memory.
84       # /sys/fs/cgroup/systemd/user.slice/user-$uid/session-n.scope for systemd.
85
86       session optional    pam_cgfs.so -c all
87       # user writable cgroups are created under all cgroup controllers.
88
89       session optional    pam_cgfs.so -c all,memory,freezer
90       # invalid argument and returns PAM_SESSION_ERR
91
92

SEE ALSO

94       lxc-cgroup(1), cgroups(7), user_namespaces(7), namespaces(7), pam(8)
95

AUTHOR

97       Venkata  Harshavardhan   Reddy   Allu   <venkataharshavardhan_ven@srmu‐
98       niv.edu.in>
99
100
101
102                                  2022-05-26                       pam_cgfs(8)
Impressum