`cgrp`

Linux cgroup and namespace control - create and destroy cgroups, set CPU shares and quotas, memory limits, block I/O weight, network class IDs, freeze/thaw process groups, list member PIDs, and enter or create new namespaces.

Load with: use cgrp

What this module does

cgrp provides direct control over Linux cgroups v1 and Linux namespaces. Cgroups let you constrain and account for the CPU, memory, I/O, and network resources used by a group of processes - the foundation of container isolation. Namespace functions let you create (unshare) or enter (setns) isolated views of the process, network, mount, and IPC namespaces.

Functions are available both as bare names (cgmk, cgset, etc.) and via the cgrp namespace object (cgrp.mk, cgrp.set, etc.).

Quick example

use cgrp

# Create a CPU and memory cgroup for a sandbox
cg = cgmk("sandbox1", "memory")

# Limit to 256 MB RAM
cgmem(cg, 268435456)

# Limit CPU to 50% of one core (50000us quota / 100000us period)
cgcpx(cg, 50000, 100000)

# Move a process into the cgroup
cgadd(cg, my_pid)

# Freeze all processes in the group
cgfrz(cg)

# Check stats
prn(cgst(cg))  # {procs, mem, cpu}

# Thaw and clean up
cgthw(cg)
cgrm(cg)

Functions

Cgroup lifecycle

cgmk(name, controller)

Creates a cgroup at /sys/fs/cgroup/{controller}/{name} via __sys_mkdir. Returns a cgroup object {name, ctrl, path}.

cgrm(cg)

Removes a cgroup directory via __sys_rmdir.

Raw file access

cgset(cg, key, val)

Writes val to the file {cg.path}/{key}. Returns the cgroup object. This is the general-purpose setter - all resource limit functions use it internally.

cgget(cg, key)

Reads and trims the content of {cg.path}/{key}.

Process membership

cgadd(cg, pid)

Adds a process to the cgroup by writing its PID to cgroup.procs.

cgprc(cg)

Returns a list of integer PIDs currently in the cgroup by reading cgroup.procs.

Resource limits

cgcpu(cg, shares)

Sets CPU shares (relative weight). Higher values get proportionally more CPU time. Writes to cpu.shares.

cgcpx(cg, quota, period)

Sets a hard CPU time quota: processes in this cgroup may use at most quota microseconds per period microseconds. Writes to cpu.cfs_quota_us and cpu.cfs_period_us.

cgmem(cg, bytes)

Sets the memory limit in bytes. Writes to memory.limit_in_bytes.

cgmsw(cg, bytes)

Sets the combined memory + swap limit in bytes. Writes to memory.memsw.limit_in_bytes.

cgpio(cg, weight)

Sets block I/O weight (100–1000). Higher values get more disk bandwidth. Writes to blkio.weight.

cgnet(cg, classid)

Sets the network class ID for traffic shaping. Writes to net_cls.classid.

Freeze / thaw

cgfrz(cg)

Freezes all processes in the cgroup by writing "FROZEN" to freezer.state. Processes are paused but remain in memory.

cgthw(cg)

Thaws the cgroup by writing "THAWED" to freezer.state.

Stats

cgst(cg)

Returns a stats snapshot: {procs: count, mem: usage_bytes_string, cpu: usage_ns_string} from cgroup.procs, memory.usage_in_bytes, and cpuacct.usage.

Namespaces

nsmk(flags)

Creates new namespaces for the calling process via __sys_unshare(flags). flags is a bitmask of CLONE_* constants (e.g. CLONE_NEWNS, CLONE_NEWNET, CLONE_NEWPID).

nsent(pid, flags)

Enters the namespaces of another process via __sys_setns(pid, flags).

Notes

Requires Linux and root (or appropriate capabilities) to write cgroup files.
Uses cgroups v1 paths - for cgroups v2 (/sys/fs/cgroup/unified/), file names differ.
Requires txt and trl.