CGCONFIG.CONF(5)

📦

version 3.2.0 · 5 versions

3.2.0 · ubuntu stonking (latest)
3.2.0 · alpine 3.24, nixos 26.05, nixpkgs unstable
3.0 · epel 10, fedora 43, fedora 44
2.0.2 · debian bookworm, ubuntu jammy, ubuntu noble
3.1.0 · debian trixie, ubuntu questing, ubuntu resolute

💅 CGCONFIG.CONF(5) 💅

File Formats Manual · the libcgroup era 💖

okay so bestie, buckle UP — this is the manual page for cgconfig.conf, and it is genuinely the main character of libcgroup configuration. no cap. let's get into it ✨

🎀 NAME 🎀

cgconfig.conf — the libcgroup configuration file. periodt. 💖

🌸 DESCRIPTION 🌸

cgconfig.conf is a configuration file used by libcgroup to define control groups, their parameters and their mount points. The file consists of mount, group and default sections. These sections can be in arbitrary order and all of them are optional — yes, every single one, fr fr. Any line starting with # is considered a comment line and is ignored (so annotate away, it's giving self-care 💅).

🗂️ the `mount` section 🗂️

mount section has this form:

mount {
       <controller> = <path>;
       ...
}

<controller> — Name of the kernel subsystem. The list of subsystems supported by the kernel can be found in the /proc/cgroups file. A named hierarchy can be specified as controller "name=<somename>". Do not forget to use double quotes around this controller name (see examples below 👀). Apart from named hierarchy, additional mount options may be specified by putting the controller and the options in quotes. Options supported are nosuid, noexec and nodev.

Libcgroup merges all subsystems mounted to the same directory (see Example 1) and the directory is mounted only once. queen of not doing things twice 💅.

<path> — The directory path where the group hierarchy associated to a given controller shall be mounted. The directory is created automatically on cgconfig service startup if it does not exist, and is deleted on service shutdown. bye bestie 🦋

If no mount section is specified, no controllers are mounted. (empty config energy, respectfully 🙈)

👑 the `group` section 👑

group section has this form:

group <name> {
       [permissions]
       <controller> {
              <param name> = <param value>;
              ...
       }
       ...
}

<name> — Name of the control group. It can contain only characters which are allowed for directory names. The groups form a tree, i.e. a control group can contain zero or more subgroups. Subgroups can be specified using the / delimiter.

The root control group is always created automatically in all hierarchies, and it is the base of the group hierarchy. It can be explicitly specified in cgconfig.conf by using . as the group name. This can be used e.g. to set its permissions, as shown in Example 6.

When the parent control group of a subgroup is not specified, it is created automatically.

permissions — Permissions of the given control group on mounted filesystem. root has always permission to do anything with the control group. Permissions have the following syntax:

perm {
       task {
              uid = <task user>;
              gid = <task group>;
              fperm = <file permissions>
       }
       admin {
              uid = <admin name>;
              gid = <admin group>;
              dperm = <directory permissions>
              fperm = <file permissions>
       }
}

task user/group — Name of the user and the group which own the tasks file of the control group. The given fperm then specifies the file permissions. Please note that the given value is not used as it was specified. Instead, the current file owner permissions are used as a "umask" for group and others permissions. For example, if fperm = 777, then both group and others will get the same permissions as the file owner. it's giving "we're all equal here" 😭
admin user/group — Name of the user and the group which own the rest of the control group's files. The given fperm and dperm control file and directory permissions. Again, the given value is masked by the file/directory owner permissions.

Permissions only apply to the enclosing control group and are not inherited by subgroups. If there is no perm section in the control group definition, root:root is the owner of all files, and default file permissions are preserved if fperm resp. dperm are not specified.

<controller> — Name of the kernel subsystem. The section can be empty, in which case default kernel parameters will be used. By specifying a controller, the control group and all its parents are controlled by that specific subsystem. One control group can be controlled by multiple subsystems, even if the subsystems are mounted on different directories. Each control group must be controlled by at least one subsystem, so that libcgroup knows in which hierarchies the control group should be created.

The parameters of the given controller can be modified in the following section enclosed in brackets.

<param name> — Name of the file to set. Each controller can have zero or more parameters.
<param value> — Value which should be written to the file when the control group is created. If it is enclosed in double quotes ", it can contain spaces and other special characters. party 🎉

If no group section is specified, no groups are created.

🌈 the `default` section 🌈

default section has this form:

default {
       perm {
              task {
                     uid = <task user>;
                     gid = <task group>;
                     fperm = <file permissions>
              }
              admin {
                     uid = <admin name>;
                     gid = <admin group>;
                     dperm = <directory permissions>
                     fperm = <file permissions>
              }
       }
}

Content of the perm section has the same form as in group section. The permissions defined here specify the owner and permissions of groups and files of all groups which do not have explicitly specified their permissions in their group section. it's the fallback bestie, the safety net 🫶

💀 the `template` section 💀

template section has the same structure as group section. Template name uses the same templates string as cgrules.conf destination tag (see cgrules.conf (5)). A template definition is used as a control group definition for rules in cgrules.conf (5) with the same destination name. Templates do not use default section settings. (they said "no thank you" to the defaults 💅)

🖥️ the `systemd` section 🖥️

systemd section has this form (supported on cgroup v2):

systemd {
       slice = <slice-name.slice>;
       scope = <scope-name.scope>;
       setdefault = <yes>;
       pid = <pid>;
}

slice — The name of the systemd slice unit. It should end with .slice and obey the rules set forth by systemd slice unit. The slice unit is created if it doesn't exist. This configuration requires 'scope=<scope-name.scope>'. The term 'unit' and 'cgroup' is used interchangeably.
scope — The name of the systemd scope unit. It should end with .scope and obey the rules set forth by systemd transient scope unit. This configuration requires 'slice=<slice-name.scope>'.
setdefault — Set the scope as the default libcgroup scope. This default scope is used by libcgroup tools to build up the cgroup path.
pid — Moves the provided pid into the <slice-name.slice>/<scope-name.scope>. Without this configuration, libcgroup will create and attach a default idle program libcgroup_systemd_idle_thread required by a systemd transient scope unit. The scope-name.scope is automatically removed by systemd when the last task in the cgroup exits, but the slice-name.slice will exist until manually removed. 👋

The /etc/cgconfig.d/ directory can be used for additional configuration files. cgrulesengd searches this directory for additional templates. 🧚

🎀 EXAMPLES 🎀

✨ Example 1 ✨

The configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       cpuacct = /sys/fs/cgroup/cpu;
}

creates the hierarchy controlled by two subsystems with no groups inside. It corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

✨ Example 2 ✨

The configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       "name=scheduler" = /sys/fs/cgroup/cpu;
       "name=noctrl" = /sys/fs/cgroup/noctrl;
}

group daemons {
       cpu {
              cpu.shares = "1000";
       }
}
group test {
       "name=noctrl" {
       }
}

creates two hierarchies. One hierarchy named scheduler controlled by the cpu subsystem, with group daemons inside. The second hierarchy is named noctrl, without any controller, with group test. It corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,name=scheduler cpu /sys/fs/cgroup/cpu
mount -t cgroup -o none,name=noctrl none /sys/fs/cgroup/noctrl

mkdir /sys/fs/cgroup/cpu/daemons
echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares

mkdir /sys/fs/cgroup/noctrl/tests

The daemons group is created automatically when its first subgroup is created. All its parameters have the default value and only root can access the group's files.

Since both cpuacct and cpu subsystems are mounted to the same directory, all groups are implicitly controlled also by the cpuacct subsystem, even if there is no cpuacct section in any of the groups. sneaky but valid 🔥

✨ Example 3 ✨

The configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       cpuacct = /sys/fs/cgroup/cpu;
}

group daemons/www {
       perm {
              task {
                     uid = root;
                     gid = webmaster;
                     fperm = 770;
              }
              admin {
                     uid = root;
                     gid = root;
                     dperm = 775;
                     fperm = 744;
              }
       }
       cpu {
              cpu.shares = "1000";
       }
}

group daemons/ftp {
       perm {
              task {
                     uid = root;
                     gid = ftpmaster;
                     fperm = 774;
              }
              admin {
                     uid = root;
                     gid = root;
                     dperm = 755;
                     fperm = 700;
              }
       }
       cpu {
              cpu.shares = "500";
       }
}

okay so that whole thing up there 👆 creates a hierarchy controlled by two subsystems, with one group and two subgroups chilling inside it, and it sets one parameter. bestie it corresponds to these operations (except for file permissions, which are a* little bit trickier to fake with chmod — that part is giving "we tried our best"):

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

mkdir /sys/fs/cgroup/cpu/daemons

mkdir /sys/fs/cgroup/cpu/daemons/www
chown root:root /sys/fs/cgroup/cpu/daemons/www/*
chown root:webmaster /sys/fs/cgroup/cpu/daemons/www/tasks
echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares

 # + chmod the files so the result looks like:
 # ls -la /sys/fs/cgroup/cpu/daemons/www/
 # admin.dperm = 755:
 # drwxr-xr-x. 2 root webmaster 0 Jun 16 11:51 .
 #
 # admin.fperm = 744:
 # --w-------. 1 root webmaster 0 Jun 16 11:51 cgroup.event_control
 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cgroup.procs
 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.stat
 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage
 # -r--r--r--. 1 root webmaster 0 Jun 16 11:51 cpuacct.usage_percpu
 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_period_us
 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.rt_runtime_us
 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 cpu.shares
 # -rw-r--r--. 1 root webmaster 0 Jun 16 11:51 notify_on_release
 #
 # tasks.fperm = 770
 # -rw-rw----. 1 root webmaster 0 Jun 16 11:51 tasks

mkdir /sys/fs/cgroup/cpu/daemons/ftp
chown root:root /sys/fs/cgroup/cpu/daemons/ftp/*
chown root:ftpmaster /sys/fs/cgroup/cpu/daemons/ftp/tasks
echo 500 > /sys/fs/cgroup/cpu/daemons/ftp/cpu.shares

 # + chmod the files so the result looks like:
 # ls -la /sys/fs/cgroup/cpu/daemons/ftp/
 # admin.dperm = 755:
 # drwxr-xr-x. 2 root ftpmaster 0 Jun 16 11:51 .
 #
 # admin.fperm = 700:
 # --w-------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.event_control
 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cgroup.procs
 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.stat
 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage
 # -r--------. 1 root ftpmaster 0 Jun 16 11:51 cpuacct.usage_percpu
 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_period_us
 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.rt_runtime_us
 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 cpu.shares
 # -rw-------. 1 root ftpmaster 0 Jun 16 11:51 notify_on_release
 #
 # tasks.fperm = 774:
 # -rw-rw-r--. 1 root ftpmaster 0 Jun 16 11:51 tasks

the daemons group gets created automatically the second its first subgroup shows up, no invitation needed 💅. every single one of its parameters is just sitting at the default value, and only root can touch that group's files. gatekeeping, honestly iconic.

and because cpuacct and cpu are both mounted to the same directory, every group is implicitly also controlled by the cpuacct subsystem — even if there's literally no cpuacct section anywhere in any of the groups. it's giving "you're on the list whether you applied or not" ✨.

Example 4 🦋

the configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       cpuacct = /sys/fs/cgroup/cpuacct;
}

group daemons {
       cpuacct{
       }
       cpu {
       }
}

creates two hierarchies and one common group in both of them 🫶. it corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mkdir /sys/fs/cgroup/cpuacct
mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu
mount -t cgroup -o cpuacct cpuacct /sys/fs/cgroup/cpuacct

mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpuacct/daemons

lowkey though? that's actually two groups created. one in the cpuacct hierarchy, the second in the cpu hierarchy 🌸. these two groups have nothing in common and can hold totally different subgroups and totally different tasks. strangers, not sisters, no cap.

Example 5 🎀

the configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       cpuacct = /sys/fs/cgroup/cpuacct;
}

group daemons {
       cpuacct{
       }
}

group daemons/www {
       cpu {
              cpu.shares = "1000";
       }
}

group daemons/ftp {
       cpu {
              cpu.shares = "500";
       }
}

creates two hierarchies with a few groups inside, and one of those groups is created in both hierarchies 👑.

it corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mkdir /sys/fs/cgroup/cpuacct
mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu
mount -t cgroup -o cpuacct cpuacct /sys/fs/cgroup/cpuacct

mkdir /sys/fs/cgroup/cpuacct/daemons
mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpu/daemons/www
echo 1000 > /sys/fs/cgroup/cpu/daemons/www/cpu.shares
mkdir /sys/fs/cgroup/cpu/daemons/ftp
echo 500 > /sys/fs/cgroup/cpu/daemons/ftp/cpu.shares

so group daemons gets created in both hierarchies. in the cpuacct hierarchy it's explicitly written out in the config file. in the cpu hierarchy it's created implicitly when www pops up in there 🙈. and again — these two groups share nothing. they don't share processes, they don't share subgroups, they're not friends 💀. groups www and ftp only exist in the cpu hierarchy and are absolutely not controlled by the cpuacct subsystem.

Example 6 🔥

the configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       cpuacct = /sys/fs/cgroup/cpu;
}

group . {
       perm {
              task {
                     uid = root;
                     gid = operator;
              }
              admin {
                     uid = root;
                     gid = operator;
              }
       }
       cpu {
       }
}

group daemons {
       perm {
              task {
                     uid = root;
                     gid = daemonmaster;
              }
              admin {
                     uid = root;
                     gid = operator;
              }
       }
       cpu {
       }
}

creates the hierarchy controlled by two subsystems, with one group that has some special permissions ✨. it corresponds to the following operations:

mkdir /sys/fs/cgroup/cpu
mount -t cgroup -o cpu,cpuacct cpu /sys/fs/cgroup/cpu

chown root:operator /sys/fs/cgroup/cpu/*
chown root:operator /sys/fs/cgroup/cpu/tasks

mkdir /sys/fs/cgroup/cpu/daemons
chown root:operator /sys/fs/cgroup/cpu/daemons/*
chown root:daemonmaster /sys/fs/cgroup/cpu/daemons/tasks

so the tea is ☕: users who are members of the operator group are allowed to administer the control groups — meaning create new control groups and move processes between them, without ever having root privileges. delegation, we love to see it 👑

meanwhile members of the daemonmaster group can move processes to the daemons control group, but they cannot move a process out of the group 😭. only operator or root can do that. it's a one-way door, bestie.

Example 7 🌈

the configuration file:

mount {
       cpu = /sys/fs/cgroup/cpu;
       cpuacct = /sys/fs/cgroup/cpuacct;
}

group students {
       cpuacct{
       }
       cpu {
       }
}

template students/%u {
       cpuacct{
       }
       cpu {
       }
}

mkdir /sys/fs/cgroup/cpu/daemons
mkdir /sys/fs/cgroup/cpuacct/daemons

the situation here is similar to Example 4 — same vibe, different font 🫶. the only difference is the template, which gets used if some rule uses "/students/%u" as a destination. that's it, that's the whole plot twist 💖.

Example 8 🌟

the configuration file:

mount {
       "cpu,nodev,nosuid,noexec" = /sys/fs/cgroup/cpu;
}

this is the same as mount -t cgroup cgroup -o nodev,nosuid,noexec,cpu /sys/fs/cgroup/cpu 🌸. it mounts the cpu controller with MS_NODEV, MS_NOSUID and MS_NOEXEC options passed. slay 💅.

Example 9 🧚

the configuration file:

systemd {
       slice = database.slice;
       scope = db.scope;
       setdefault = yes;
}

this creates a systemd transient scope unit db.scope under the systemd slice unit database.slice, and spawns a libcgroup_systemd_idle_thread in the scope cgroup unit 🎀. the 'setdefault' configuration appends database.slice/db.scope to the path constructed by libcgroup</> and its tools. it's giving "shortcut, but make it systemd" ✨.

🌈 RECOMMENDATIONS 🌈

Keep hierarchies separated

having multiple hierarchies is perfectly valid and can genuinely be useful in various scenarios 💖. but to keep things clean, do not create one group in multiple hierarchies. Examples 4 and 5 show exactly how unreadable and confusing that gets — especially when you're reading somebody else's configuration file at 2am 😭. future-you is a real person bestie, be kind to them.

Explicit is better than implicit

libcgroup can implicitly create groups that are needed just so your configured subgroups can exist. that's useful and it saves you some typing in simple scenarios, no cap 🫶. but once multiple hierarchies enter the chat, it's way better to explicitly specify all the groups and all the controllers related to them. spell it out 💅.

📁 FILES 📁

/etc/cgconfig.conf — default libcgroup configuration file 💖
/etc/cgconfig.d/ — default libcgroup configuration files directory 📂

👀 SEE ALSO 👀

cgconfigparser(8) — the actual tool that eats this file for breakfast 🔥

💀 BUGS 💀

parameter values must be single strings without spaces 😭. parsing of quoted strings is not implemented. so no, you cannot get cute with your quoting. keep it simple, keep it space-free, keep it moving 🫶.

and that's genuinely it — the whole CGCONFIG.CONF(5) page from libcgroup, wrapped up with a bow 🎀 go forth, configure your control groups, and remember: no group in two hierarchies 💜 see you in the next manpage bestie ✨💅👑

📦 where this page comes from

ubuntu stonking: cgroup-tools 3.2.0-1 · LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

CGCONFIG.CONF(5)

💅 CGCONFIG.CONF(5) 💅

🎀 NAME 🎀

🌸 DESCRIPTION 🌸

🗂️ the mount section 🗂️

👑 the group section 👑

🌈 the default section 🌈

💀 the template section 💀

🖥️ the systemd section 🖥️

🎀 EXAMPLES 🎀

✨ Example 1 ✨

✨ Example 2 ✨

✨ Example 3 ✨

Example 4 🦋

Example 5 🎀

Example 6 🔥

Example 7 🌈

Example 8 🌟

Example 9 🧚

🌈 RECOMMENDATIONS 🌈

Keep hierarchies separated

Explicit is better than implicit

📁 FILES 📁

👀 SEE ALSO 👀

💀 BUGS 💀

🗂️ the `mount` section 🗂️

👑 the `group` section 👑

🌈 the `default` section 🌈

💀 the `template` section 💀

🖥️ the `systemd` section 🖥️