GoAdmio

username

Change the GoAdmio account username

On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · See also


Overview

/go/username renames the username of an existing hosting account in one command. It:

The domain and the /home/<domain> folder keep their names. Only the username changes.

Run it as root, or as a user with sudo access.


Quick start

# Rename an account's username
/go/username example.com newname

Syntax

/go/username <domain> <username>

Arguments are positional. This command has no --option flags.

Input is checked before anything is changed. After that, the steps run one after another with no rollback, so see Output for what happens on a failure.


Arguments

Argument Position Required Default Notes
<domain> 1 Yes — The account's domain. /home/<domain> must exist.
<username> 2 Yes — The new username. See username rules.

Output

The command prints plain text, not JSON.

Outcome What you get
Account renamed No message from this command. Any output comes from adduser and phpmyadmin.
Invalid username Invalid Username <username>
Username too short Username must be at least 3 chars
Username already in use Username <username> already exists.
/home/<domain> doesn't exist Directory /home/<domain> not exists.

Every validation failure exits with status 1 before anything is changed.

[!WARNING] The steps after validation are not wrapped in a transaction. If one fails partway, the earlier changes stay in place, and the databases may show the new username while the system user is still the old one. Check the output of each step if something goes wrong.


Examples

# Rename an account's username
/go/username example.com example

# Use a username with digits, dots, and hyphens
/go/username shop.example.net shop-01

Troubleshooting

Symptom Likely cause Fix
Invalid Username <username> The name has uppercase letters, spaces, or other characters outside the username rules. Use lowercase letters, numbers, and _, ., -.
Username must be at least 3 chars The name is one or two characters. Use at least three.
Username <username> already exists. A system user with that name already exists. Choose another name.
Directory /home/<domain> not exists. The domain is misspelled or has no account. Check the domain, or create the account with create.
Nothing was printed Success prints no message of its own. Confirm with id <username>.
Login with the new username fails The command doesn't pass a password when it creates the system user. Set one with password.
Site or FTP errors after the rename Services may still be using the old user. Rebuild the configuration with conf, then run restart.
chown errors on an unsupported operating system The system user step is skipped, so the new user doesn't exist. See Supported operating systems.

Details

What it changes

In order:

  1. Appends the call to a log file (see Logging).
  2. Validates the new username (see Username rules).
  3. Looks up the account's current username in the Site table.
  4. Checks that /home/<domain> exists.
  5. Updates the username in the GoAdmio databases, for rows matching the domain.
  6. Deletes the old system user and group, then creates the new user with adduser. Active logins for the old user may be interrupted.
  7. Sets the group of /home/<domain>/www to nobody.
  8. Sets the owner and group of /home/<domain>/www, including everything inside it, to the new username. This can take a while on large sites.
  9. Sets permissions on /home/<domain> to 755.
  10. Runs phpmyadmin for the domain. The script's own comment describes this step as changing the default password for all MySQL databases.

The script doesn't rename /home/<domain>, and it doesn't touch the account's password, web server configuration, or PHP-FPM pool.

Username rules

Check Rule
Characters Lowercase letters, numbers, _, ., and -. One $ is allowed at the end.
First character A lowercase letter or a number.
Length At least 3 characters. No maximum is checked.
System users Rejected if the name already exists as a system user (id, or /etc/passwd).

[!NOTE] These rules differ from create, which requires a letter first, allows at most 32 characters, rejects all-digit names, and blocks reserved names. /go/username does not check the Site table for another account with the same name, or a list of reserved names.

Databases updated

The username is changed in these databases, in /var/lib/sqlite/, where the domain matches:

Database Table
site.db Site
sqlite.db SQLite
ftp.db FTP
httplog.db Httplog
ftplog.db Ftplog
mysql.db Mysql
mail.db Mail
subdomain.db Subdomain
directory.db Directory
github.db Github
alias.db Alias
block.db Block

Supported operating systems

The system user is replaced only on these operating systems, read from /usr/local/goadmio/linux/os.db:

Family Systems
Red Hat AlmaLinux, Rocky, CentOS, Red Hat, Fedora
Debian Debian, Ubuntu

On any other system the user step is skipped without a message, but the database updates and the ownership steps still run.

Logging

Each run appends one line to /var/log/go/username.log, with the time, the command name, and the arguments in plain text. For example:

[Nov 19 12:00:00]# username example.com newname

See also

Command Description
create Create a GoAdmio account from the command line
password Change a GoAdmio account password from the command line
domain Change the primary domain of a hosting account
conf Rebuild the Apache/Nginx configuration in GoAdmio
restart Restart all PHP-FPM pools and the active web server
phpmyadmin Install the latest phpMyAdmin on a GoAdmio server
adduser Create the system/FTP user for the account (used internally)