Home WebsiteCloudLinux CageFS: How It Works and Fixes for Common Problems

CloudLinux CageFS: How It Works and Fixes for Common Problems

by Knowledge Base Linux
CloudLinux CageFS isolates every hosting account in a virtualized file system

On a plain shared server, every customer can peek at the system’s full file tree — and, with one misconfigured permission, at each other’s websites. CloudLinux CageFS removes that risk by giving every account its own virtualized view of the file system: users see their own files and a safe set of system files, and nothing else. This guide explains how CageFS works under the hood, the cagefsctl commands you will actually use, and the fixes for the problems admins hit most often. CageFS ships with CloudLinux itself, so if your server is not converted yet, follow our guide to install CloudLinux first.

How CloudLinux CageFS Works

CageFS is a virtualized, per-user file system built on Linux mount namespaces. When a user logs in via SSH, runs a cron job, or a web request executes PHP as that user, the process is placed inside the user’s “cage”. Inside the cage:

  • The user sees their own home directory and files, exactly as expected.
  • System directories such as /usr and /bin are populated only with binaries and libraries CloudLinux deems safe for shared hosting.
  • /etc/passwd inside the cage is a filtered copy — the user cannot enumerate the other accounts on the server.
  • Other users’ home directories simply do not exist from the caged user’s point of view, and other users’ processes are hidden as well.

The cage is assembled from a shared skeleton (/usr/share/cagefs-skeleton) plus per-user files stored under /var/cagefs/. Most system files are hardlinked rather than copied, so enabling CageFS for hundreds of accounts costs far less disk space than you might expect. A component called ProxyExec makes setuid binaries (such as su and mail tools) work safely inside the cage.

CageFS works together with the LVE: the cage controls what a user can see, while LVE limits control how much CPU, memory and I/O the user can use.

Inside a CloudLinux CageFS virtual file system with user files and safe system binaries

Enabling CageFS and the cagefsctl Commands You Need – CloudLinux CageFS

On a freshly converted CloudLinux server, initialize CageFS once and enable it for all existing users:

cagefsctl --init
cagefsctl --enable-all

You can also manage it per user, and check who is enabled:

cagefsctl --enable <username>
cagefsctl --disable <username>
cagefsctl --list-enabled
cagefsctl --list-disabled

In WHM or DirectAdmin, the same controls live in CloudLinux Manager → CageFS, where you can also choose whether newly created accounts are caged automatically — leave that on, so no account is ever created uncaged by accident.

To look at the server exactly as a customer sees it — the single most useful troubleshooting trick — enter the user’s cage yourself:

cagefsctl --enter <username>

Inside, run ls /home, which php or cat /etc/passwd and you will see precisely what the user sees. Exit with exit when done.

Keeping Cages Updated: –update, –remount and –force-update – CloudLinux CageFS

A cage is a snapshot of the safe system files. When the underlying system changes, the cages must be refreshed, and CageFS gives you three levels of refresh:

  • cagefsctl --update — updates cage contents after changes such as installing new software that users should be able to run. Run it after adding binaries or libraries meant for customers.
  • cagefsctl --remount-all — remounts all user cages. Needed when account-level data changes, most famously after users are added, removed or renamed and the filtered /etc/passwd inside existing cages becomes stale.
  • cagefsctl --force-update — the heavy option: rebuilds the cages completely. Use it when an ordinary update does not fix a broken cage — for example after a major alt-php or system package update leaves PHP misbehaving inside cages.

To make a custom file or binary available inside all cages, add its path to the mount configuration in /etc/cagefs/cagefs.mp (or a file in /etc/cagefs/conf.d/), then run cagefsctl --update. Never edit files inside /var/cagefs/ directly — your changes will be overwritten on the next update.

Common CageFS Problems and Their Fixes

“Command not found” for software you just installed

You installed a tool on the server, but inside the cage it does not exist. The binary is not in the skeleton yet. Add its path (and any helper files it needs) to /etc/cagefs/cagefs.mp, run cagefsctl --update, and verify from inside the user’s cage with cagefsctl --enter.

Stale or wrong /etc/passwd inside the cage

Symptoms include users seeing accounts that no longer exist, missing newly created users, or odd ownership names on files. The filtered /etc/passwd in the cage is a copy, and copies go stale. Fix it with cagefsctl --remount-all; if a single account is affected, cagefsctl --remount <username> is enough.

PHP breaks after a PHP or system update

After updating alt-php packages or system libraries, sites may throw errors inside cages while PHP works fine for root. The cages are still serving the old file set. Run cagefsctl --force-update and test again — this resolves the large majority of “it worked before the update” CageFS tickets.

A user is not caged at all

Accounts restored from backups or created while CageFS was in a selective mode may never have been enabled. Check with cagefsctl --list-disabled and enable the account with cagefsctl --enable <username>. Then confirm the default for new accounts is set to enabled in CloudLinux Manager so the gap does not reappear.

A legitimate application cannot see a file it needs

Some applications expect device files, sockets or unusual paths that the default skeleton does not include. Check the cage view with --enter, add the required paths to cagefs.mp or a conf.d file, and run cagefsctl --update. Avoid the temptation to disable CageFS for that user permanently — you would remove their isolation to fix a one-line configuration gap.

Is CageFS Enough on Its Own?

CageFS is a visibility and isolation layer, not a complete security program. It pairs with LVE limits for resource fairness, and you should still keep the OS and panels patched, use strong passwords and SSH keys, and run a malware scanner. What CageFS does uniquely well is shrink the blast radius: a compromised account cannot browse the server, read other customers’ configuration files (with their database passwords), or use local files as stepping stones.

Conclusion

CloudLinux CageFS gives every shared-hosting account a private, filtered view of the file system, and it costs you almost nothing once enabled. Remember the core workflow — --init and --enable-all to switch it on, --enter to see what users see, --update after system changes, --remount-all for stale account data, and --force-update when a cage is genuinely broken — and nearly every CageFS ticket becomes a two-minute fix.

You may also like

KbLinux

Typically replies within a day

Hello, Welcome to the site. Please click below button for chatting me through Telegram.