Skip to main content

tenantctl command reference

tenantctl is the main tenantd CLI. Run it with no arguments to print usage.

All commands that change state require root.

Tenant enrollment

tenantctl apply <user> [--package=<name>] [--fpm-php=<ea-phpXX>]

Place a Unix user under a per-tenant cgroup v2 slice driven by a package profile.

  • --package=<name> selects a profile from /etc/tenantd/packages/<name>.conf. Defaults to default.
  • --fpm-php=<ea-phpXX> additionally provisions a dedicated PHP-FPM master for this user at the named EasyApache PHP version.

Re-running apply against an already-enrolled tenant is how you move them between profiles. It takes effect immediately and does not drop their running processes.

tenantctl show <user>

Print the live state: slice limits as systemd currently enforces them, the FPM master state if one exists, the mount-namespace pin, and enrollment status. This reads the running system, not the config, so it is the right command for confirming that a change actually took.

tenantctl remove <user>

Remove the tenant's slice, FPM master, and enrollment. Safe to run after the OS user is already gone, which is what makes it usable from the cPanel account-removal hook.

Filesystem isolation

tenantctl ns-apply <user>

Put the tenant in a mount namespace. /home shows only their own directory; peer data under /var/cpanel/users, /var/cpanel/userdata, /var/spool/mail, /var/spool/cron, /etc/valiases and similar shared parents is masked. /tmp and /var/tmp become a per-tenant tmpfs. This is the CageFS equivalent.

SSH and cron sessions for the user enter the namespace automatically.

tenantctl ns-ensure <user>

Idempotent version of ns-apply. Creates the namespace only if it is not already live. Intended for hooks and automation.

tenantctl ns-remove <user>

Tear down the tenant's namespace.

tenantctl ns-reapply-all

Roll a changed /etc/tenantd/ns-layout.conf out to every enrolled tenant. Editing the layout file does not affect namespaces that are already pinned, so run this after changing it.

MySQL

tenantctl mysql-bootstrap

Once per host. Creates the tenantd_governor MariaDB user and its grants. See the MySQL governor.

tenantctl mysql-promote <user>

Move the tenant off the shared mysqld onto a dedicated mariadb@ instance inside their own slice, where per-tenant IO enforcement works. Free, with no cap on how many tenants you promote.

tenantctl mysql-demote <user>

Move a promoted tenant back onto the shared mysqld.

tenantctl mysql-promote-suggest

Rank tenants by how much they would benefit from promotion, based on observed load.

tenantctl auto-promote {show|enable|disable} [--max=N]

Let tenantd promote heavy tenants automatically. --max=N caps how many instances it will create.

Fleet and routing

tenantctl fleet-enroll <fleet-url>

Register this host with a tenantd-fleet dashboard.

tenantctl proxysql-enroll <user> / tenantctl proxysql-remove <user>

Add or remove a tenant from the ProxySQL front door. Requires the tenantd-proxysql package. The per-query delay comes from the tenant's package profile (MYSQL_PROXYSQL_DELAY_MS).

Other

tenantctl audit-export

Export the audit trail of tenantd state changes.

tenantctl tier {show|set <free|solo-cloud|enterprise>}

Historical. tenantd was briefly planned as a tiered commercial product, and the tier label survives in the config. It does not gate anything: every feature is free on every tier. There is no reason to change it.

Related commands

tenantctl-migrate is a separate binary for CloudLinux conversion. See migrating from CloudLinux.