Manage CageFS as Root (cagefsctl Commands)

CageFS gives every cPanel user a private, virtualised file system. As root you decide who is caged, which commands are available inside the cage and when the cage template (the skeleton) is rebuilt after software updates. Most work is done with the cagefsctl command.

On MdmHost hosting plans this is managed for you. This guide is for administrators of their own CloudLinux cPanel server with root SSH access.

Before you start

CloudLinux with CageFS installed and initialised (see installing CloudLinux).
Root SSH access.

Choose the mode

CageFS has two modes: enabled for all users (new users are caged automatically; recommended) or disabled for all, with only selected users caged. Set it in WHM → Plugins → CloudLinux Manager → CageFS or from SSH:

cagefsctl --enable-all

Enable or disable individual users

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

Disable a user only temporarily for troubleshooting; uncaged users can see more of the server.

Update the skeleton

The skeleton in /usr/share/cagefs-skeleton holds copies of system files available inside cages. After installing or updating software that users should see, update it:

cagefsctl --force-update

A daily cron job runs a normal update automatically; use --force-update right after changes.

Add a command to the cage

Create a config file in /etc/cagefs/conf.d/, for example mytool.cfg:
```
[mytool]
comment=My tool
paths=/usr/bin/mytool
```
Run cagefsctl --force-update.
Test as a user: su - username -s /bin/bash -c "which mytool".

Warning: Only add tools that are safe for untrusted users. Anything inside the cage can be run by every customer, including compromised accounts.

Mount points are listed in /etc/cagefs/cagefs.mp. Add a path to make a server directory visible inside cages, then run cagefsctl --remount-all.
Prefix a line with @ to give each user a private copy of a directory.

Common errors

A user's site broke after enabling CageFS

The site calls a binary not in the cage, such as an image tool. Add it as above, or switch the script to a PHP library.

"Error: user is not in cagefs" or stale files

Remount the user's cage:

cagefsctl --remount username

Skeleton update fails with low disk space

The skeleton needs several GB on the partition holding /usr/share. Free space or move the skeleton with CloudLinux's documented relocation steps.

What users experience inside the cage is described in CageFS explained, and PHP selector behaviour in PHP Selector admin settings.

Frequently asked questions

Does CageFS affect cron jobs?

Yes, user cron jobs run inside the cage, so the commands they use must be available there.

Is root ever caged?

No. Root and system users are never caged; CageFS applies to hosting users only.

How do I check a user's view?

Run cagefsctl --enter username (on recent versions) or use su to start a shell as the user and look around.

Do I need to update the skeleton after every dnf update?

The daily automatic update usually covers it. Run cagefsctl --force-update immediately after installing new tools or PHP versions users need straight away.

Was this guide helpful?

Still stuck?

Ask MdmHost AI for a quick answer, or open a ticket and our team will take a look. We are here 24/7.

Ask MdmHost AI Open a ticket