# CloudLinux Isolates (BETA)

CloudLinux Isolates isolates the individual websites of a single hosting account from one another. It has two layers, which are described in turn below:

• CageFS per domain — filesystem isolation, so that a compromised website cannot reach another site's files.
• LVE per domain — resource isolation, so that one website's CPU, memory and I/O usage is limited and accounted for on its own.

# CageFS Per Domain

CloudLinux Isolates is a security feature that provides domain-level isolation within CageFS. It allows server administrators to isolate individual websites from each other, even when they belong to the same hosting account. This prevents cross-site attacks where a compromised website could access files or data from other websites on the same account.

# Overview

When CloudLinux Isolates is enabled for a domain:

• Each isolated website runs in its own isolated environment
• PHP processes for isolated websites cannot access files from other websites
• Crontab entries are automatically scoped to their respective document roots
• Existing PHP processes are gracefully terminated and restarted in the isolated environment
• Per-domain PHP Selector configuration is automatically set up (inheriting user-level settings)

# Prerequisites

# Minimum Package Versions

# Compatible Web Servers

# LiteSpeed requirements

CloudLinux Isolates is supported under standalone LiteSpeed Web Server, and for now on cPanel servers only.

In addition to the minimum package versions listed above, LiteSpeed servers require:

To check the installed versions:

rpm -q cagefs lve-wrappers lve ea-apache24-mod_hostinglimits

# Compatible PHP Handlers

The following table applies to Apache. For standalone LiteSpeed, see LiteSpeed requirements above.

# LSAPI per-user restriction

The mod_lsapi directive lsapi_per_user controls how lsphp backend processes are spawned:

• lsapi_per_user Off (default) — one lsphp master per virtual host. Each master receives the site's DOCUMENT_ROOT and enters the correct isolated environment. This is the only mode compatible with CloudLinux Isolates.
• lsapi_per_user On — a single lsphp master serves all virtual hosts for a user. In this mode, mod_lsapi does not pass DOCUMENT_ROOT to the backend, so isolation cannot determine which site a request belongs to. This mode is incompatible with CloudLinux Isolates.

To check your current setting, run:

grep -ri 'lsapi_per_user' /etc/apache2/conf.d/ /etc/httpd/conf.d/ 2>/dev/null

The directive is typically located in /etc/apache2/conf.d/lsapi.conf (cPanel) or /etc/httpd/conf.d/lsapi.conf. If the command returns no output, or all matches are commented out or show Off, your configuration is compatible (the default is Off). If any match shows lsapi_per_user On (uncommented), you must set it to Off before enabling CloudLinux Isolates.

# Compatible Control Panels

*Control Panel Integration

The table above applies to Apache. Under standalone LiteSpeed, only cPanel is supported so far.

# Compatible PHP Versions

CloudLinux Isolates provides partial FPM handler support for both ea-php (cPanel) and alt-php.

# ea-php (cPanel)

# alt-php

# Quick Start

Follow these steps to enable CloudLinux Isolates for a domain:

1. Allow the feature server-wide (administrator only, one-time setup):

cagefsctl --site-isolation-allow-all

2. Enable isolation for a specific domain:

cagefsctl --site-isolation-enable <example.com>

3. Verify isolation is active:

cagefsctl --site-isolation-list

To disable isolation for a domain:

cagefsctl --site-isolation-disable <example.com>

# Command Reference

# Server-Wide Management

# Allow CloudLinux Isolates for All Users

cagefsctl --site-isolation-allow-all

Enables the CloudLinux Isolates feature server-wide in "Allow All" mode. All users are allowed to use CloudLinux Isolates by default (individual users can be denied with --site-isolation-deny).

Example:

# cagefsctl --site-isolation-allow-all
CloudLinux Isolates was allowed for all users.

Notes:

• Creates the feature flag at /opt/cloudlinux/flags/enabled-flags.d/website-isolation.flag
• Sets up the per-user denied directory at /etc/cagefs/site-isolation.users.denied
• Triggers a CageFS remount to apply necessary mount configurations
• Registers the isolatectl proxyexec command for user-level management
• Must be run with root privileges

# Deny CloudLinux Isolates for All Users

cagefsctl --site-isolation-deny-all

Disables the CloudLinux Isolates feature server-wide and switches to "Deny All" mode. Removes all domain isolation configurations for all users.

Example:

# cagefsctl --site-isolation-deny-all
CloudLinux Isolates was denied for all users.

Warning: This command will:

• Disable isolation for all currently isolated domains
• Remove all per-user isolation configurations
• Terminate and restart affected PHP processes
• Clean up token directories and overlay storage
• Switch to "Deny All" mode

# Per-User Management

CloudLinux Isolates uses a two-mode user model to control which users can use the feature:

• Allow All mode (allow_all): All users are allowed by default. Individual users can be denied (added as exceptions).
• Deny All mode (deny_all): No users are allowed by default. Individual users can be allowed (added as exceptions).

# Allow CloudLinux Isolates for a Specific User

cagefsctl --site-isolation-allow <username> [<username2> ...]

Allows CloudLinux Isolates for one or more specific users.

Parameters:

Behavior depends on current mode:

• Allow All mode: Removes the user from the denied list (undoes a previous --site-isolation-deny)
• Deny All mode: Adds the user to the allowed list
• Not initialized: Sets up infrastructure in Deny All mode with the user as the first allowed user

Example:

# cagefsctl --site-isolation-allow john
CloudLinux Isolates was allowed for user(s): john

# cagefsctl --site-isolation-allow john jane
CloudLinux Isolates was allowed for user(s): john, jane

# Deny CloudLinux Isolates for a Specific User

cagefsctl --site-isolation-deny <username> [<username2> ...]

Denies CloudLinux Isolates for one or more specific users and disables all their domain isolation.

Parameters:

Behavior depends on current mode:

• Allow All mode: Adds the user to the denied list
• Deny All mode: Removes the user from the allowed list (undoes a previous --site-isolation-allow)

Example:

# cagefsctl --site-isolation-deny john
CloudLinux Isolates was denied for user(s): john

Notes:

• Also cleans up all existing domain isolation for the denied user(s)
• CloudLinux Isolates must be enabled server-wide first

# Toggle User Mode

cagefsctl --site-isolation-toggle-mode

Toggles the isolation user mode between "Allow All" and "Deny All" without modifying any per-user exception lists.

Mode transitions:

• allow_all → deny_all
• deny_all → allow_all
• Not initialized → allow_all

Example:

# cagefsctl --site-isolation-toggle-mode
CloudLinux Isolates user mode toggled to 'deny_all'.

Notes:

• Only flips the mode indicator directories
• Does not clean up existing user isolation
• Does not alter the per-user exception lists
• Useful for quickly switching the default behavior without losing per-user configuration

# Domain-Level Management

# Enable Isolation for a Domain

cagefsctl --site-isolation-enable <domain> [<domain2> ...]

Enables CloudLinux Isolates for one or more specified domains.

Parameters:

Example:

# cagefsctl --site-isolation-enable example.com
CloudLinux Isolates was enabled for domain(s),
example.com

# cagefsctl --site-isolation-enable site1.com site2.com
CloudLinux Isolates was enabled for domain(s),
site1.com,site2.com

Requirements:

• CloudLinux Isolates must be allowed server-wide first
• CloudLinux Isolates must be allowed for the domain's user
• The domain must exist and be associated with a valid user account
• Must be run with root privileges

What happens when isolation is enabled:

1. A unique website token directory is created
2. Overlay storage directory is configured for the website
3. User configuration is updated with the isolated domain
4. Per-domain PHP Selector configuration is set up (inheriting from user's PHP settings)
5. If this is the first isolated website for the user, CageFS is remounted
6. Existing PHP processes for the domain are terminated and restarted in isolation
7. Document root monitoring service is started

# Disable Isolation for a Domain

cagefsctl --site-isolation-disable <domain> [<domain2> ...]

Disables CloudLinux Isolates for one or more specified domains.

Parameters:

Example:

# cagefsctl --site-isolation-disable example.com
CloudLinux Isolates was disabled for domain(s),
example.com

Requirements:

• Must be run with root privileges

What happens when isolation is disabled:

1. Domain is removed from the user's isolation configuration
2. Mount configuration is regenerated
3. PHP processes for the domain are restarted outside of isolation
4. Token directories are cleaned up
5. If no users have any isolated domains left, the monitoring service is stopped

# Monitoring and Management

# List Isolated Domains

cagefsctl --site-isolation-list [<username> ...]

Lists all users and domains that have CloudLinux Isolates enabled.

Parameters:

Example - List all isolated domains:

# cagefsctl --site-isolation-list

Domains with enabled CloudLinux Isolates for user john:
example.com
mysite.org

Domains with enabled CloudLinux Isolates for user jane:
shop.example.com

Example - List isolated domains for specific user:

# cagefsctl --site-isolation-list john

Domains with enabled CloudLinux Isolates for user john:
example.com
mysite.org

Output when no domains are isolated:

# cagefsctl --site-isolation-list
No users with enabled CloudLinux Isolates

# Regenerate Isolation Configuration

cagefsctl --site-isolation-regenerate <username> [<username2> ...]

Regenerates the CloudLinux Isolates configuration for specified users. Use this command after manual configuration changes or when troubleshooting isolation issues.

Parameters:

Example:

# cagefsctl --site-isolation-regenerate john jane
Regenerated configuration CloudLinux Isolates for users:
john
jane

When to use:

• After domain document root changes
• After domain renames or migrations
• When isolation configuration appears out of sync
• As part of troubleshooting steps recommended by support

# User-Level Management (isolatectl)

End users can manage CloudLinux Isolates and per-domain resource limits for their own domains using the isolatectl utility. All output is JSON.

isolatectl must be run as a regular (non-root) user. It automatically identifies the calling user — no --username or --lve-id flags are needed.

# Site Isolation

# Enable Isolation for a Domain (User-Level)

isolatectl site-isolation enable --domain <domain>[,<domain2>,...]

Enables CloudLinux Isolates for one or more domains owned by the calling user.

Parameters:

Example:

$ isolatectl site-isolation enable --domain example.com
{"result": "success", "enabled_sites": ["example.com"]}

$ isolatectl site-isolation enable --domain site1.com,site2.com
{"result": "success", "enabled_sites": ["site1.com", "site2.com"]}

Notes:

• The user can only manage domains they own
• CloudLinux Isolates must be allowed for the user by the server administrator

# Disable Isolation for a Domain (User-Level)

isolatectl site-isolation disable --domain <domain>[,<domain2>,...]

Disables CloudLinux Isolates for one or more domains owned by the calling user.

Parameters:

Example:

$ isolatectl site-isolation disable --domain example.com
{"result": "success", "enabled_sites": []}

# List Isolated Domains (User-Level)

isolatectl site-isolation list

Lists all domains with CloudLinux Isolates enabled for the calling user.

Example:

$ isolatectl site-isolation list
{"result": "success", "enabled_sites": ["example.com", "mysite.org"]}

# Per-Domain Resource Limits

Per-domain resource limits allow end users to set and apply individual CPU, memory, I/O, and process limits for each isolated domain. Domain limits require site isolation to be enabled first.

# List Domain Limits

isolatectl limits list [--domain <domain>]

Shows the configured limits for all domains or a specific domain.

Parameters:

Example:

$ isolatectl limits list
{
  "result": "success",
  "domains": [
    {
      "name": "example.com",
      "lve_id": 1000,
      "limits": {"cpu": 2500, "pmem": 1048576}
    }
  ]
}

$ isolatectl limits list --domain example.com
{
  "result": "success",
  "domains": [
    {
      "name": "example.com",
      "lve_id": 1000,
      "limits": {"cpu": 2500, "pmem": 1048576}
    }
  ]
}

# Set Domain Limits

isolatectl limits set --domain <domain> [--cpu VAL] [--pmem VAL] [--io VAL] [--nproc VAL] [--iops VAL] [--ep VAL] [--vmem VAL]

Stores per-domain limits in the user's config and applies them to the kernel.

Parameters:

At least one limit parameter is required.

Example:

$ isolatectl limits set --domain example.com --cpu 5000 --pmem 268435456 --io 2048 --nproc 30 --iops 500 --ep 20 --vmem 536870912
{
  "result": "success",
  "domain": "example.com",
  "limits": {
    "cpu": 5000,
    "pmem": 268435456,
    "io": 2048,
    "nproc": 30,
    "iops": 500,
    "ep": 20,
    "vmem": 536870912
  }
}

This sets: CPU 50%, 256 MB PMEM, 2048 KB/s IO, 30 procs, 500 IOPS, 20 entry procs, 512 MB VMEM.

# Apply Domain Limits

isolatectl limits apply --domain <domain>

Pushes the stored limits for a domain from the config file to the kernel. Use after manually editing the config or to re-apply limits after a restart.

Parameters:

Example:

$ isolatectl limits apply --domain example.com
{
  "result": "success",
  "domain": "example.com",
  "limits": {"cpu": 5000, "pmem": 268435456}
}

# Per-Domain Statistics

isolatectl stats [--domain <domain>] [--period <period>]

Shows resource usage for the calling account's isolated domains. Like the rest of isolatectl, it is run by the account owner rather than by root, identifies the caller automatically, and returns JSON.

Parameters:

The period grammar is lveinfo's: s, m, h, d, plus today. 1m is one minute, not one month — a month is 30d.

Example:

$ isolatectl stats --domain example.com --period 1d
{
  "result": "success",
  "scope": {
    "owner_uid": 1000,
    "period": "1d",
    "note": "only domains active during the window are recorded"
  },
  "domains": [
    {
      "name": "example.com",
      "lve_id": 60057,
      "owner_uid": 1000,
      "usage":  {"cpu": 120, "ep": 2, "vmem": 0, "pmem": 4096, "nproc": 5, "io": 0, "iops": 0},
      "peak":   {"cpu": 900, "ep": 5, "vmem": 0, "pmem": 9012, "nproc": 9, "io": 0, "iops": 0},
      "limits": {"cpu": 5000, "ep": 20, "vmem": 0, "pmem": 65536, "nproc": 30, "io": 2048, "iops": 500},
      "faults": {"cpu": 0, "ep": 3, "vmem": 0, "pmem": 0, "nproc": 0, "io": 0, "iops": 0}
    }
  ]
}

usage is the average over the window, peak the highest sample in it, and limits the caps in force.

# Executing Commands in an Isolated Site Context

The cagefs_enter_site utility allows executing a command inside CageFS in the context of a specific isolated website. This can be useful for debugging or running site-specific operations.

cagefs_enter_site <site> <command>

Parameters:

Example:

$ cagefs_enter_site example.com /bin/ls /home/user/public_html

Notes:

• This command cannot be run as root
• The site parameter can be either a document root path or a domain name

# Per-Domain PHP Selector

When CloudLinux Isolates is enabled for a domain, per-domain PHP Selector configuration is automatically set up. This allows each isolated website to have its own PHP version and module configuration, independent of other websites on the same account.

Key behaviors:

• When isolation is first enabled for a domain, the domain inherits the user's current PHP version and module settings
• Each isolated domain stores its PHP selector configuration separately

# Setting PHP Version for an Isolated Domain

Use selectorctl with the --domain option to set the PHP version for a specific isolated domain:

selectorctl --set-user-current=<version> --domain <domain> [--user <username>]

Example — set PHP 8.2 for example.com:

# As root:
selectorctl --set-user-current=8.2 --domain example.com --user john

# As the user:
selectorctl --set-user-current=8.2 --domain example.com

# Enabling/Disabling Extensions for an Isolated Domain

Use selectorctl with the --domain option to manage extensions per domain:

# Enable extensions
selectorctl --enable-user-extensions=<ext1>,<ext2> --version <version> --domain <domain> [--user <username>]

# Disable extensions
selectorctl --disable-user-extensions=<ext1>,<ext2> --version <version> --domain <domain> [--user <username>]

# List enabled extensions
selectorctl --list-user-extensions --version <version> --domain <domain> [--user <username>]

# Troubleshooting

# Common Issues

"CloudLinux Isolates is not enabled"

# Solution: Allow server-wide first
cagefsctl --site-isolation-allow-all

"CloudLinux Isolates feature is not available on this platform"

The server does not have the required packages installed. Ensure all prerequisite packages are installed and up to date.

"CloudLinux Isolates is not allowed for user <username>"

# Solution: Allow for the specific user
cagefsctl --site-isolation-allow <username>
# Or allow for all users
cagefsctl --site-isolation-allow-all

"Please specify existing domain name and try again"

• Verify the domain exists in the control panel
• Check that the domain is associated with a valid user account

# Integration with Control Panels

CloudLinux Isolates integrates automatically with supported control panels. When domains are:

• Created: No automatic action (isolation must be explicitly enabled)
• Renamed: Isolation configuration is automatically updated
• Deleted: Isolation configuration is automatically cleaned up
• Document root changed: Configuration is regenerated via hooks

# LVE Per Domain

CloudLinux Isolates also allows resource limits — CPU, memory, I/O, processes and entry processes — to be applied to an individual website rather than to the hosting account as a whole. A single busy or misbehaving site is then throttled on its own, without consuming the resources its sibling sites on the same account depend on.

# How it relates to CageFS per domain

The two halves of CloudLinux Isolates are separate layers and can be reasoned about separately:

In practice you do not enable them separately. The cagefsctl --site-isolation-* commands documented above drive both: each one invokes the matching lvectl per-domain command for you when the prerequisites are met, and silently skips that step when they are not. So on a server that does not support per-domain LVEs, website isolation still works — you get the filesystem separation without the resource limits, rather than an error.

# Per-Domain Prerequisites

Per-domain LVE limits are supported on CloudLinux OS 8 and 9. CloudLinux OS 7 predates the required kernel interface; on it, commands that need per-domain support fail with exit code 38 and the message Domain limits are not supported by this kernel.

In addition to the CloudLinux Isolates prerequisites, per-domain LVE limits require:

To check the installed versions:

rpm -q lve-stats3 lve-utils

# How the containers are arranged

Understanding the container hierarchy explains most of what the statistics show:

ROOT
└── LVP  (reseller, when reseller limits are in use)
    └── LVP  (the hosting account)          <-- reported as "the account"
        ├── LVE  (the account's own processes — cron, SSH, non-isolated sites)
        ├── LVE  (site1.com)
        └── LVE  (site2.com)

The account's container is the parent of its websites', and the kernel keeps the parent's counters as the sum of its children's. So the figure the statistics tools report for an account is the total for everything beneath it — its own processes and every isolated website. The account's own processes are a separate container at the same level as the websites, and are never reported on their own.

Because the websites are siblings of the account's own container rather than nested inside it, work done by an isolated website is charged to that website and to the account total, but never to the account's own processes — and the reverse holds too, so an account's cron jobs are never absorbed by one of its websites.

Limits nest, even though usage does not. A domain is bounded by its account's limits, which are in turn bounded by the reseller's; raising a domain's limit above its account's does not grant it more than the account has. A domain with no explicit limits of its own is simply bounded by its account's — registering a domain does not, by itself, restrict it.

# Enabling per-domain limits

Under a control panel, use the cagefsctl --site-isolation-* commands — they enable both isolation layers together and are the supported administrator path.

The underlying lvectl commands are available for integration scripts, and for inspecting or repairing state:

See lvectl for the full syntax.

The domain renaming, document root changes and account renames performed through a supported control panel are handled by the panel hooks, which call lvectl regenerate-domains automatically. Run it by hand only after changing these outside the panel.

# Setting per-domain limits

Per-domain limits are set by the account owner with isolatectl limits, not by the administrator: there is no lvectl command that sets an individual domain's limits. Administrators control the account-level limits, which bound every domain underneath them.

Where the state lives:

# Viewing per-domain usage

Per-domain statistics are collected by default once the feature is active. Every statistics tool can report them:

Each --domain selector accepts a domain name, a document root, or a numeric domain LVE id. See Command Line Tools for full syntax.

# Reading per-domain figures

Three properties of the numbers regularly surprise people reading them for the first time. None of them indicates a fault.

A website's usage is part of its account's, not additional to it. The per-domain rows break the account's figure down; they do not add to it:

account  =  the account's own work  +  site1.com  +  site2.com  + ...
            (cron, SSH, non-isolated
             sites — everything outside
             an isolated website)

Faults are counted per container, then rolled up. The kernel records a fault only against the container whose limit refused the request. lve-stats then rolls a website's faults into its account's total, so an account read without a per-domain option already includes its websites' faults; passing --with-domains splits them apart again. The user notification email is the one place that subtracts them instead, so that the same refusal is not reported twice in a message that already lists the site.

Per-domain history is kept for fewer days than per-account history — 7 days against 30, by default. A report covering a longer range returns correspondingly less per-domain data than account data, without the rows themselves indicating why. Both windows are administrator-configurable; see keep_history_days_domain in LVE-Stats 2 configuration (/etc/sysconfig/lvestats2).

# Fault notifications

When a website hits one of its own limits, the notification sent to the account owner names the website that faulted, alongside the limit it hit. Notifications continue to be addressed per account, and the thresholds and period that govern the account-level notification govern the per-domain section too — so enabling per-domain limits does not, by itself, change who is emailed or how often.

Administrators customising the email templates should see the domain_faults variable in Customize LVE-stats2 notifications.

# Troubleshooting per-domain limits

"Domain limits are not supported by this kernel (requires lve_lvp_create2)"

The kernel predates per-domain LVE support. Per-domain limits require CloudLinux OS 8 or 9; on CloudLinux OS 7 the CageFS half of CloudLinux Isolates is still available.

Isolation was enabled, but no domain LVEs were created

The cagefsctl --site-isolation-* commands always apply the filesystem layer, and add the per-domain LVE only when the prerequisites are met. Check the installed versions:

rpm -q lve-stats3 lve-utils

If either is below the minimum, update it and then re-run cagefsctl --site-isolation-enable <domain>. Removing isolation is never gated this way, so any containers created by an earlier version can always be torn down.

"No domain limits configured for UID N"

The account exists but has no isolated domains. Enable isolation for a domain first — cagefsctl --site-isolation-enable <domain>. A genuinely unknown account reports UID N does not exist instead.

A domain's statistics stopped after a rename or a document root change

The domain's registry entry is keyed on its document root. Changes made through a supported control panel are handled by the panel hooks; if the change was made outside the panel, refresh the mapping by hand:

lvectl regenerate-domains --username <user> --domain <new> --old-domain <old>