Provided by: libpam-cgfs_5.0.0~git2209-g5a7b9ce67-0ubuntu3_amd64 bug


       pam_cgfs - cgroup management for unprivileged LXC containers.

SYNOPSIS {-c kernel_controller,name=named_controller}


       LXC  has  supported  fully  unprivileged  containers  since  LXC  1.0.  Fully unprivileged
       containers are the safest containers and are run  by  normal  (non-root)  users.  This  is
       achieved  by using user namespaces by mapping between a range of UIDs and GIDs on the host
       to a different (unprivileged) range of UIDs and GIDs in the container. That means the  uid
       0  (root)  in  the container is mapped to an unprivileged user id (something like 1000000)
       outside of the container and only has rights on resources that it owns itself.

       Cgroup management of fully unprivileged containers means restricting the resources used by
       these containers like limiting the CPU usage of a container, or the number of processes it
       is allowed to spawn, or the memory it is allowed to consume. It is clear  that  the  fully
       unprivileged  containers  are  run by normal users and there is a need to limit and manage
       resource consumption among the containers.  But unprivileged cgroup management is not easy
       with most init systems.  So, the came into existence.

       The module can handle pure cgroupfs v1 (/sys/fs/cgroup/$controller) and mixed
       mounts,  where  some  controllers  are  mounted  in  a  standard  cgroupfs  v1   hierarchy
       (/sys/fs/cgroup/$controller) and others in cgroupfs v2 hierarchy (/sys/fs/cgroup/unified).
       Writeable cgroups are either created for  all  controllers  or,  if  specified,  for  only
       controllers  listed as arguments on the command line.  Pure cgroup v2 mount is not covered
       by the module.

       The cgroup created user/$user/n will be for the nth session under cgroup kernel controller

       Systems with a systemd init system are treated specifically, both with respect to cgroupfs
       v1 and cgroupfs v2. For both, cgroupfs v1 and  cgroupfs  v2,  the  module  checks  whether
       systemd     already     placed     the     user     in     a     cgroup     it     created
       user.slice/user-$uid/session-n.scope by checking whether $uid == login  uid.  If  so,  the
       login  user  chown  the  session-n.scope,  else  a  cgroup  is  created  as outlined above
       (user/$user/n) and chown it to login uid. If the init system has already placed the  login
       user  inside a session specific group, the module is smart enough to detect it
       and re-use the cgroup.

       In essence, the module takes care of  placing  unprivileged  (non-root)  users
       into writable cgroups at login and also cleaning up these cgroup hierarchies on logout, so
       they are free to delegate resources to containers as needed that  have  been  provided  to


       -c controller-list
              Takes  a  string  argument  which  sets  the  list  of kernel controllers and named
              controllers delimited by commas  in-between  “,”.  Named  controllers  need  to  be
              specified  in  the  form  “name=$namedcontroller”.  Can use “all” enable all cgroup
              resource controller hierarchies. Specifying “all” and other controllers  explicitly
              returns PAM_SESSION_ERR.


       Only session module type is provided (and needed).


              Writeable cgroups have been created for the user.

              Failed to create writable cgroups for the user.


              Default configuration is added at the end of these files.


       session optional -c freezer,memory,named=systemd
       # default configuration
       # user writable cgroups are created under freezer, memory and named cgroup systemd hierarchies.
       # /sys/fs/cgroup/$controller/user/$user/n for freezer,memory.
       # /sys/fs/cgroup/systemd/user.slice/user-$uid/session-n.scope for systemd.

       session optional -c all
       # user writable cgroups are created under all cgroup controllers.

       session optional -c all,memory,freezer
       # invalid argument and returns PAM_SESSION_ERR


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


       Venkata Harshavardhan Reddy Allu <>

                                            2022-09-07                                pam_cgfs(8)