diff --git a/.gitignore b/.gitignore index a759b11f1..ce33d3459 100644 --- a/.gitignore +++ b/.gitignore @@ -130,6 +130,7 @@ config/sysconfig/lxc doc/*.1 doc/*.5 doc/*.7 +doc/*.8 doc/ja/*.1 doc/ja/*.5 doc/ja/*.7 diff --git a/configure.ac b/configure.ac index 6db186957..e546443ad 100644 --- a/configure.ac +++ b/configure.ac @@ -864,6 +864,8 @@ AC_CONFIG_FILES([ doc/lxc-usernsexec.sgml doc/lxc-wait.sgml + doc/pam_cgfs.sgml + doc/lxc.conf.sgml doc/lxc.container.conf.sgml doc/lxc.system.conf.sgml diff --git a/doc/Makefile.am b/doc/Makefile.am index 2bf92a0a8..29abd0154 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -46,6 +46,10 @@ man_MANS += lxc-attach.1 \ lxc-wait.1 endif +if ENABLE_PAM +man_MANS += pam_cgfs.8 +endif + if ENABLE_COMMANDS man_MANS += lxc-update-config.1 \ lxc-user-nic.1 \ @@ -64,8 +68,12 @@ endif $(db2xman) $< test "$(shell basename $@)" != "$@" && mv $(shell basename $@) $@ || true +%.8 : %.sgml + $(db2xman) $< + test "$(shell basename $@)" != "$@" && mv $(shell basename $@) $@ || true + lxc-%.sgml : common_options.sgml see_also.sgml clean-local: - $(RM) manpage.* *.7 *.5 *.1 $(man_MANS) + $(RM) manpage.* *.7 *.5 *.1 *.8 $(man_MANS) endif diff --git a/doc/pam_cgfs.sgml.in b/doc/pam_cgfs.sgml.in new file mode 100644 index 000000000..1952afcb2 --- /dev/null +++ b/doc/pam_cgfs.sgml.in @@ -0,0 +1,268 @@ + + + +]> + + + + @LXC_GENERATE_DATE@ + + + pam_cgfs + 8 + + + + pam_cgfs + + + cgroup management for unprivileged LXC containers. + + + + + + pam_cgfs.so + -c kernel_controller,name=named_controller + + + + + Description + + + 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 pam_cgfs.so came into existence. + + + + The pam_cgfs.so module can handle both pure cgroupfs v1 + (/sys/fs/cgroup/$controller) and pure cgroupfs + v2 (/sys/fs/cgroup), as well as 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. + + + + The cgroup created user/$user/n will be for the nth + session under cgroup kernel controller hierarchy. + + + + 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 pam_cgfs.so module is + smart enough to detect it and re-use the cgroup. + + + + In essence, the pam_cgfs.so 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 + them. + + + + + + + Options + + + + + + + + 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. + + + + + + + + + + Module types provided + + Only module type is provided (and needed). + + + + + + Return Values + + + + + PAM_SUCCESS + + + Writeable cgroups have been created for the user. + + + + + + PAM_SESSION_ERR + + + Failed to create writable cgroups for the user. + + + + + + + + + + + Files + + + + + /etc/pam.d/common-session{,-noninteractive} + + + Default configuration is added at the end of these files. + + + + + + + + + + EXAMPLE + +session optional pam_cgfs.so -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 pam_cgfs.so -c all +# user writable cgroups are created under all cgroup controllers. + +session optional pam_cgfs.so -c all,memory,freezer +# invalid argument and returns PAM_SESSION_ERR + + + + + See Also + + + + lxc-cgroup + 1 + , + + + cgroups + 7 + , + + + user_namespaces + 7 + , + + + namespaces + 7 + , + + + pam + 8 + + + + + + + + + Author + Venkata Harshavardhan Reddy Allu venkataharshavardhan_ven@srmuniv.edu.in + + + + +