CloudLinux OS enhances server stability, density, and security by isolating each tenant in their own Lightweight Virtualized Environment (LVE). A core component of this isolation is CageFS, a virtualized file system that encapsulates each user, preventing them from seeing other users’ data or sensitive server information. This article guides you through understanding and managing CageFS on your CloudLinux cPanel server using the cagefsctl command.

What is CageFS?

CageFS is a per-user file system virtualization technology provided by CloudLinux. When a user is in CageFS, they are presented with a “caged” environment that contains only the necessary files and binaries for their account to function. This has several key benefits:

Security: Users cannot access other users’ files or sensitive system files, significantly reducing the risk of information disclosure and privilege escalation if one account is compromised.
Stability: Prevents users from impacting the stability of other accounts or the server by restricting access to critical system configurations.
Isolation: Each user has their own private set of configuration files, ensuring that customizations by one user do not affect others.
Content Segregation: Ensures users can only see their own processes and files.

Essentially, each user operates within their own “cage,” unaware of other users on the server, enhancing overall server security and reliability.

Prerequisites

Before you begin, ensure you have the following:

A CloudLinux OS activated on your server.
cPanel & WHM installed.
Root access to the server via SSH (commands in this article assume you are operating as the root user).

CageFS is typically installed and enabled by default when you install CloudLinux. If it’s not, you can install it using dnf. First, install the package:

dnf install cagefs -y

Then, initialize CageFS:

cagefsctl --init

The --init command sets up the CageFS skeleton directory (/usr/share/cagefs-skeleton) and initial configuration.

Checking CageFS status

You can check the status of user enrollment in CageFS using the cagefsctl command-line tool.

To see a summary of users currently in CageFS:

cagefsctl --list-enabled

To see a summary of users currently not in CageFS:

cagefsctl --list-disabled

While cagefsctl itself doesn’t have a single command for the overall daemon status, its successful operation on user management (enabling/disabling) and updates confirms its active state. If your system uses systemd, you can also check the service status:

systemctl status cagefs

However, for most administrative tasks related to CageFS, commands like --list-enabled and --list-disabled will provide the necessary status information regarding user encapsulation.

Managing CageFS with cagefsctl

The cagefsctl utility is your primary tool for managing CageFS from the command line.

Initializing CageFS

If CageFS was not initialized during CloudLinux setup or if you need to re-initialize it (use with caution as this rebuilds the skeleton), run the following command:

cagefsctl --init

This command might take some time as it creates the base file system structure used by all caged users.

Enabling and disabling CageFS for users in WHM

You can manage CageFS on a per-user basis or for all users.

Enabling or disabling per-user can be easily achieved via the CloudLinux Manager feature in WHM.

Log into WHM
Search for “CloudLinux Manager” in the search bar.
Go to the Users tab
Toggle the CageFS on or off for each user as desired.

Bulk enabling and disabling CageFS for users via command line

Bulk enabling or disabling of CageFS is generally easiest via command line.

To enable CageFS for all users, run the following command:

cagefsctl --enable-all

To disable CageFS for all users, run the following command:

cagefsctl --disable-all

When a new account is created in cPanel, CageFS is usually enabled for it automatically if the “Enable CageFS for new users” option is active in WHM’s CloudLinux Manager.

Updating CageFS skeleton and mounts

When you make changes to CageFS configuration files (like adding new mount points or modifying templates), or when system packages that CageFS relies on are updated, you need to update CageFS.

cagefsctl --update

This command remounts users’ CageFS instances and applies changes. If you encounter issues or want to ensure a full rebuild of the metadata, you can use:

cagefsctl --force-update

This command performs a more thorough update and ensures all changes are propagated.

Entering a user’s CageFS environment

As the root user, you might need to enter a user’s CageFS environment to troubleshoot or verify settings. When you su to a user who is enabled in CageFS, you are automatically placed within their caged environment.

su - username

Once you are in the user’s shell, you will only see the files and directories available within their CageFS.

Working with files and directories within CageFS

For the end-user, working within CageFS is largely transparent. They can access their home directory (/home/username), temporary files (/tmp, which is virtualized per user), and common system utilities. They won’t be able to navigate to other users’ home directories or system-critical locations like /etc (except for a few safe, virtualized files).

Key points for users:

Their website files are typically in /home/username/public_html.
They have access to essential binaries (e.g., ls, cat, php, perl) located in standard paths like /bin, /usr/bin, etc., but these are actually links or copies from the CageFS skeleton.
PHP versions and extensions selected via cPanel’s “Select PHP Version” (CloudLinux PHP Selector) are respected and isolated within their CageFS.

Adding custom files or directories via configuration files

For more complex configurations or to keep customizations organized, you can add .cfg files to the /etc/cagefs/conf.d/ directory. For instance, to make a custom application available:

Create a file named /etc/cagefs/conf.d/customapp.cfg with content like:

[customapp]
comment=Allow access to custom application
paths=/opt/custom_app, /usr/local/custom_lib
mount_by_default=1

Then, update CageFS:

cagefsctl --force-update

Integrating with Cloudlinux PHP selector

CageFS works seamlessly with CloudLinux’s PHP Selector. When a user chooses a specific PHP version and extensions in cPanel, CageFS ensures that their environment uses only those selected components. The necessary PHP binaries, modules, and php.ini files are correctly mapped into the user’s cage.

Troubleshooting common issues

Command not found
If a user reports “command not found” for a utility they expect to use, the command might not be part of the default CageFS skeleton or mounts. You may need to add its path to /etc/cagefs/cagefs.mp or a custom .cfg file. Always verify the safety of adding new commands. After making changes, run cagefsctl --force-update.

Permission errors
These are often legitimate protections by CageFS. If a script tries to access a file outside its cage, it will be denied. Ensure all necessary files for a user’s applications are within their home directory or paths explicitly mounted in CageFS.

Software needing global access
Some software might expect access to system-wide resources not available in CageFS. In such rare cases, you might consider if the software is suitable for a shared hosting environment or if specific paths can be safely exposed. Disabling CageFS for a user should be a last resort and only if the security implications are understood.

Conclusion

CageFS is a powerful tool for enhancing security and stability on your CloudLinux cPanel server. By understanding how it works and how to manage it with cagefsctl, you can ensure a secure and isolated environment for each user. Regular updates to CageFS and its skeleton are crucial for maintaining a robust and secure hosting platform.

Was this article helpful?

Thank you for your input.

Thank you for your feedback.