FreeBSD RCTL: Resource Limits for Users, Jails, and Processes

Traditional login-class and process limits are useful, but they do not answer every operational question. FreeBSD’s Resource Containers framework can account for and control resources by process, user, login class, or jail. The rctl command manages that rule database while racct supplies the accounting behind it.

RCTL is not a scheduler and it is not a complete container boundary. It is a policy layer for named resource counters. A safe rule begins by identifying exactly what is counted, which subject owns the limit, and what action occurs when the threshold is reached.

Confirm that accounting is available

The kernel needs RACCT and RCTL support. On a system where they are available, inspect the live database before adding anything.

rctl
rctl -hu jail:web

The first command lists rules. The second shows resource usage for the jail named web in human-readable units. Usage and limits are different views: a subject can consume a resource without having an explicit RCTL rule, and several rules can apply to the same process through its user, login class, jail, and process identities.

Use rctl -l process:PID to see every rule that applies to one process. That is more informative than filtering the database for rules whose subject happens to equal the PID.

Read a rule from left to right

The rule syntax is:

subject:subject-id:resource:action=amount/per

For example, the following denies additional processes after a login class reaches 100 processes per user:

rctl -a 'loginclass:testing:maxproc:deny=100/user'

Subjects include process, user, loginclass, and jail. Resources include quantities such as virtual memory, physical memory, open files, processes, CPU time, wall-clock time, and I/O rates. Actions are resource-dependent. deny rejects an allocation when the kernel can refuse it, while other rules may log, notify through devd, signal a process, or throttle a rate.

The per field controls how usage is aggregated. A rule that says 100/user does not mean the same thing as one global pool shared by the entire login class. Always verify the expanded behavior with rctl -l against a real process before assuming the grouping matches the English sentence in a change request.

Choose a resource with enforceable semantics

Some counters are exact enough for hard policy; others are approximations. The manual notes that read and write operation or bandwidth counters are calculated in filesystem layers and may reflect cache activity rather than physical device operations. They are useful for controlling a workload’s behavior, but they are not a replacement for device-level telemetry.

Memory rules need similar care. A vmemoryuse limit concerns virtual address space, not resident RAM. A memoryuse rule can create severe reclaim pressure before an action restores stability. Test a realistic workload and observe swap, page faults, ARC behavior, and latency rather than treating one counter as the entire memory model.

Start with visibility or a generous threshold. A jail inventory is a practical baseline:

rctl -hu jail:web
rctl -l jail:web

Then add one rule at a time, exercise the workload, and confirm the resulting error or throttle from inside the jail as well as from the host.

Keep persistent policy in one place

Rules added with rctl -a modify the live database. Persistent defaults belong in /etc/rctl.conf, one rule per line, using the same syntax.

# Prevent one test jail from exhausting the host process table.
jail:web:maxproc:deny=512/jail

Apply and verify the rule during a maintenance window. Keep comments about the owner, expected peak, measurement date, and rollback condition. A bare threshold becomes dangerous when the workload grows and nobody remembers the original capacity assumption.

To remove a specific live rule, pass a matching filter to rctl -r. Broad filters can remove more than one rule, so list the matches first and capture the original configuration before changing them.

Treat denial as an application event

The host may successfully enforce a limit while the application fails badly. A process-count denial can block a worker fork, an open-file limit can break log rotation, and a memory allocation failure can trigger an unsafe retry loop. Monitor both the RCTL event and the service-level result.

For jails, pair RCTL with filesystem quotas, network policy, securelevel or MAC policy where appropriate, and service-specific limits. For ordinary users, login classes may still be the simpler control. Choose RCTL when its subject hierarchy and live accounting solve a concrete host-protection problem.

Separate notification from enforcement

RCTL actions are not interchangeable. deny applies only to resources whose allocation can be refused; it is not supported for CPU time, wall-clock time, or the I/O rate resources. throttle is limited to read and write bandwidth or operation rates. Signal actions can terminate or notify an offending process, while log writes a console warning and devctl emits an event that devd can route.

Use this to stage a limit without pretending that observation is enforcement. A devctl rule can feed a narrowly matched devd action that records the subject, resource, threshold, jail, and service state. Once the measured peak and failure behavior are understood, add a separate supported enforcement rule. Keep alert commands nonblocking and rate-limited; an event storm must not create a second resource exhaustion problem.

Several rules can apply through different subject identities. A process in jail web can simultaneously match process, user, login-class, and jail rules. List the effective set with rctl -l process:PID after every change and test the combined result. Do not assume a more specific rule overrides a broader one as though RCTL were a firewall ruleset.

Rollback should be just as precise. Before rctl -r, list the filter matches and save them. A short filter can remove several live rules, and the next boot may restore anything still present in /etc/rctl.conf. Update persistent configuration and live state as one reviewed change, then verify both after a reboot.

The correct success criterion is not merely that rctl lists the rule. It is that the intended subject reaches a tested boundary, unrelated workloads remain unaffected, the application fails predictably, and removal of the rule restores normal operation.

Related:

Sources: