1. Introduction
cPanel & WHM enforces strict rules for usernames to ensure system stability and security. This guide explains username restrictions, reserved names, special exceptions, and how to resolve issues when a username is invalid, reserved, or misconfigured.
2. Basic Username Restrictions
When creating or modifying a cPanel or WHM username, the following rules apply:
- Usernames may only contain lowercase letters (
a–z) and digits (0–9). - Usernames cannot exceed 16 characters.
- Usernames cannot begin with a digit or the string
test. - Usernames cannot end with the string
assword.
3. Special Cases
- You cannot create a username containing a hyphen (
-), but you may transfer an account with a hyphenated username to another system. - To allow usernames longer than eight characters, set the following in
/var/cpanel/whm/nvdata/root.yaml:
LONGUSERS: 1- If using MySQL or PostgreSQL, the first eight characters of all usernames must be unique.
Note: You can disable database prefixing in WHM » Tweak Settings » SQL.
- To allow usernames beginning with digits, create the following file:
/etc/allowstupidstuff- You cannot use a username that matches a group name in
/etc/sudoersor/etc/sudoers.d.
4. Reserved Usernames
cPanel & WHM reserves certain usernames for system use. These cannot be used for cPanel or WHM accounts.
Important: Since TSR‑2017‑0006, email aliases in /etc/aliases and /etc/localaliases are also reserved. Any alias pointing to a reserved username is also restricted.
4.1 Files Checked for Reserved Names
/usr/local/cpanel/Cpanel/Validate/Username/Core.pm/etc/aliases/etc/localaliases
4.2 Default Reserved Aliases
| Username | Aliases |
|---|---|
| root | admin, abuse, adm, apache, bin, daemon, ftp, mail, mysql, named, nobody, postmaster, security, sshd, system, webmaster, wheel, xfs, and many more |
| postmaster | info, mailer-daemon, marketing, sales, support |
| news | newsadm, newsadmin, usenet |
| ftp | ftp-adm, ftp-admin, ftpadm, ftpadmin |
| webmaster | www |
5. Resolving Username Problems
5.1 Rename an Invalid or Reserved Username
To rename an account, run the following command as root:
whmapi1 modifyacct user=username newuser=newusernameNote: Replace username with the current restricted username and newusername with the desired valid username.
5.2 Remove Username Aliases
You may remove reserved aliases from:
/etc/aliases/etc/localaliases
6. Misconfigured Usernames
A misconfigured username is incomplete or missing required system data. To fix it, run:
/usr/local/cpanel/scripts/updateuserdomains --forceConclusion
Understanding cPanel & WHM username restrictions helps prevent account creation issues and ensures system stability. When problems occur, renaming accounts or repairing misconfigurations with the appropriate commands resolves most issues quickly.