Skip to content

Docker audit fix · Runtime & Resources

How to Configure PID Limits for Docker Containers

Docker applies no default process cap, so a container without --pids-limit can fork until the host PID table is full and not even root can start a shell to stop it. Give each container a positive limit sized from its real thread count.

Hiren KalariyaHiren KalariyaLast reviewed pid-limits
CtrlOpsPID LimitsLOW

What did your audit say?

WARN · when the audit printed

Some do not

The named containers can fork without limit, so one runaway process inside them can exhaust the host process table.

Severity
Low
Needs root or sudo
Yes
Results it can return
WARN · SKIP · PASS
Check in this audit
5 of 6

Every threshold on this page is transcribed from the docker-security-runtime-resources audit script that CtrlOps runs, and a build check fails if the two ever disagree. See all 6 Runtime & Resources checks, or how the audit runs.

The check runs docker inspect across the running containers with the template {{if or (not .HostConfig.PidsLimit) (le .HostConfig.PidsLimit 0)}}{{.Name}} {{end}}, so it reads a single field: .HostConfig.PidsLimit, the per-container cap set by --pids-limit. A field that is missing, null or ≤ 0 counts as unlimited, -1 being Docker's explicit unlimited, and puts that container's name on the list; any positive value passes whatever its size. An empty list is the PASS, and otherwise the WARN reports how many of the running containers are uncapped and names up to five.

Needs a reachable daemon and at least one running container; otherwise SKIP. It tests .HostConfig.PidsLimit per running container and treats missing, null or a value ≤ 0 as unlimited (-1 is Docker's explicit "unlimited"). Any positive value passes, regardless of size - the check does not assess whether the cap is appropriate. Only the container's own setting counts: a systemd TasksMax on docker.service or an nproc ulimit caps something else and leaves the container reported as unlimited.

What each result means
ResultWhenWhat it means
SKIPNo running containersNothing was verified. No process cap was read anywhere, so the check did not confirm that a single container is protected.
PASSEvery container caps PIDsEvery running container has a positive --pids-limit, though the check never judges whether the number is high or low.
WARNSome do notThe named containers can fork without limit, so one runaway process inside them can exhaust the host process table.

A fork bomb inside a container exhausts the host PID table (default kernel.pid_max 32768 or 4194304) and prevents even root from spawning a shell to fix it. The pids cgroup controller caps it per container. CIS Docker 5.28 "Ensure that the PIDs cgroup limit is used"; OWASP Docker Cheat Sheet Rule #7.

  • Docker sets no PID limit unless you ask for one. Some distros' systemd TasksMax on docker.service limits the daemon's own total but not each container.
  • An nproc ulimit (--ulimit nproc=...) is a per-user limit, not a per-container one, and does not satisfy this check.
  • Value 0 in older API versions meant "unlimited"; -1 is the explicit unlimited today; both are treated as unlimited.
  • Java/Go apps with many threads need generous limits (threads count as PIDs): measure docker top or cat /sys/fs/cgroup/pids.current.
  1. Measure the real process count

    Threads count against the limit, so read the cgroup's own counter under normal load rather than counting processes:

    sh
    docker exec <name> cat /sys/fs/cgroup/pids.current

    A typical web server runs 10 to 30, a PHP-FPM pool 50 to 100, and JVM or Node services with large thread pools several hundred.

  2. Set a positive limit

    Two to three times the measured count leaves room for spikes while still stopping a fork loop.

    sh
    docker run --pids-limit 256 ...

    In Compose:

    yaml
    services:  app:    pids_limit: 256

  3. Apply it

    Recreate the container, or change a running one in place. Keep the Compose file in step, or the next recreate removes the cap.

    sh
    docker compose up -d --force-recreate# or, in place:docker update --pids-limit 256 <name>

  4. Confirm the cap

    sh
    docker exec <name> cat /sys/fs/cgroup/pids.max

    It should print your number, not max.

sh
docker inspect -f '{{.Name}} pids={{.HostConfig.PidsLimit}}' $(docker ps -q)# expected: a positive number for every container# The cgroup's view, and current usage:docker exec <name> sh -c 'cat /sys/fs/cgroup/pids.max; cat /sys/fs/cgroup/pids.current'# expected: a number rather than "max", with current well below it# Prove a cap holds, on a throwaway container rather than a production one:docker run --rm --pids-limit 20 alpine sh -c 'for i in $(seq 50); do sleep 5 & done; wait' 2>&1 | head -3# expected: "can't fork" errors once the 20th process is reached

Debugging

  • This one message covers two different cases: the audit could not reach the Docker daemon, or it reached it and nothing was running. Run docker ps as the audit user, then sudo docker ps. If both fail, the daemon is unreachable: check systemctl status docker, then run the audit as root or give the account sudo. If they work but list nothing, there is genuinely nothing to evaluate, and a stopped container is never checked. The Docker Inventory check reports the two cases separately, so its result tells you which one you hit.
  • Expected: the check reads only each container's own PidsLimit. TasksMax limits the Docker service as a whole, and nproc applies per user ID, so neither stops one container filling the process table for the others. Set --pids-limit (Compose pids_limit:) on each container.
  • Truncated with head -5; the count is complete. Full list: docker inspect -f '{{if or (not .HostConfig.PidsLimit) (le .HostConfig.PidsLimit 0)}}{{.Name}}{{end}}' $(docker ps -q).
  • The cap is too low for its thread count. Size it from pids.current under load; JVM and Node applications with large thread pools routinely need several hundred. 512 or 1024 is a common starting point.
  • The limit may be far larger than needed, or the culprit ran outside a container. Compare each container's pids.max against real usage, and check the host-wide ceiling with sysctl kernel.pid_max.

Sources

Next

Re-run the Runtime & Resources audit after applying the fix and confirm this check moves to PASS. CtrlOps runs all 6 checks over your existing SSH connection and scores the result, so the change is visible without reading another config file.

Download for MacDownload for WindowsAll 6 Runtime & Resources fixes

14-day free trial, no credit card required.

Explore article with AI tools

Written by

Hiren Kalariya

Co-Founder & CEO, TST Technology

Hiren Kalariya is the Co-Founder and CEO of TST Technology and the product lead behind CtrlOps, a local-first desktop app that makes Linux server management fast and easy for developers and DevOps teams. Over the past five years he has shipped 60+ production systems, and he still tests every tool he writes about on real servers.

Stop juggling tools. Start managing fleets.

PuTTY
Termius
MobaXterm
WinSCP
SecureCRT
Royal TS
Warp
CtrlOps14 tools left
Webmin
aaPanel
RunCloud
Dokploy
IP spreadsheet
bash (2)
sticky notes

One app. All your servers. No context switching. Free to start, free to leave.

Start instantly · No credit card · Cancel anytime

Your privacy preferences. We use product analytics to improve CtrlOps. Google Analytics cookies and live chat stay off until you allow them. Cookie policy