file-hierarchy: Document /sys/fs/cgroup

joshtriplett · keszybz · commit c8aeb9d672fa · 2022-03-01T08:34:08.000+01:00
file-hierarchy does not mention anything about the expected mountpoint
for cgroups. This may lead some software to believe it will need to
search for it (e.g. by scanning mountinfo) rather than just looking in
the canonical location.

Document the canonical mountpoint as /sys/fs/cgroup. Also provide
information on the non-default configurations, but
make it clear that in such configurations if cgroup2 is mounted (hybrid
mode) it won't have resource controllers attached. This will help
software know if it should fall back to /sys/fs/cgroup/unified or just
ignore that case.
diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml
@@ -420,6 +420,25 @@
         this directory.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><filename>/sys/fs/cgroup/</filename></term>
+        <listitem><para>A virtual kernel file system exposing process
+        control groups (cgroups). This file system is an API to interface
+        with the kernel and not a place where normal files may be stored. On
+        current systems running in the default "unified" mode,
+        this directory serves as the mount point for the
+        <literal>cgroup2</literal> filesystem, which provides a unified
+        cgroup hierarchy for all resource controllers. On systems with
+        non-default configurations, this directory may instead be a tmpfs
+        filesystem containing mount points for various
+        <literal>cgroup</literal> (v1) resource controllers; in such
+        configurations, if <literal>cgroup2</literal> is mounted it will be
+        mounted on <filename>/sys/fs/cgroup/unified/</filename>, but
+        cgroup2 will not have resource controllers attached. In
+        sandboxed/containerized setups, this directory may either not exist or
+        may include a subset of functionality.
+        </para></listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 
