Skip to main content

Quickstart

Install tenantd and put your first tenant under isolation.

Requirements

  • AlmaLinux, Rocky, or RHEL 9 on the stock kernel. (10 is in preparation.)
  • systemd with cgroup v2. This is the default on EL9; you do not need to change anything.
  • Root.
  • cPanel is supported and is the primary target, but is not required for the slice, FPM, namespace, and governor features.

You do not need a forked kernel, a vendor OS, or a license key.

1. Install

dnf install https://extras.getpagespeed.com/release-latest.rpm
dnf install tenantd

That pulls the main tenantd package. Optional subpackages:

dnf install tenantd-ebpf          # per-tenant IO observability
dnf install tenantd-whm-plugin    # WHM panel (cPanel hosts)
dnf install tenantd-fleet         # cross-host dashboard
dnf install tenantd-proxysql      # ProxySQL front door

All of them are free.

2. Check the install

systemctl status tenantd.target
tenantctl

Bare tenantctl prints the full subcommand list. If you installed the governor, confirm it came up:

systemctl status tenantd-mysql-governor

3. Bootstrap the MySQL governor

Only needed once per host, and only if you want MySQL isolation.

tenantctl mysql-bootstrap

This creates the tenantd_governor database user and grants it the performance_schema reads the daemon needs. tenantd never patches MariaDB and never links against it. The governor works entirely over the public SQL surface.

MariaDB ships performance_schema=OFF by default. tenantd installs a drop-in at /etc/systemd/system/mariadb.service.d/tenantd.conf to turn it on. MariaDB needs a restart for that to take effect.

4. Enroll a tenant

tenantctl apply alice

That places the user alice under a per-tenant cgroup v2 slice using the default package profile.

To use a different profile, or to give the tenant a dedicated PHP-FPM master:

tenantctl apply alice --package=burst --fpm-php=ea-php82

Add filesystem isolation (the CageFS equivalent):

tenantctl ns-apply alice

This puts the tenant in a mount namespace where /home shows only their own directory, and peer data under /var/cpanel/users, /var/spool/mail, /var/spool/cron and friends is masked. SSH and cron sessions for that user enter the namespace automatically.

5. Verify

tenantctl show alice

You should see the live slice limits, the FPM master state if you provisioned one, and the namespace pin:

CPUQuotaPerSecUSec=500ms
MemoryMax=536870912
TasksMax=200
IOWeight=100
ControlGroup=/tenantd.slice/tenantd-1001.slice
ActiveState=active
---
NS_PIN=/run/tenantd/ns/alice (live, inode=4026532746)
NS_ENROLLED=yes

Confirm the isolation is real rather than just configured:

# peer home directories should be invisible from inside the namespace
sudo -u alice ls /home

# the slice should be enforcing
systemd-cgls /tenantd.slice

6. Enroll everyone else

On a cPanel host, new accounts are enrolled automatically. tenantd registers posttrueuseradd and postwwwacctcleanup hooks at install time, so accounts created after this point get a slice and a namespace without you doing anything.

For accounts that already existed:

for u in $(ls /var/cpanel/users); do
    tenantctl apply "$u"
    tenantctl ns-apply "$u"
done

Coming from CloudLinux? Do not do this by hand. See migrating from CloudLinux, which reads your existing LVE caps and converts them into matching tenantd profiles.

Next