Renaming a FreeBSD account is more than changing a login name. A safe change preserves the numeric UID where possible, updates the primary group when appropriate, moves the home directory, repairs ownership, and checks files or scheduled jobs that still reference the old name.
Plan the change during a maintenance window. Do not rename an account that is actively logged in, owns a running service, or is the only administrative access path to the host. Keep a root or separate administrator console session open until the new account has been tested.
Record the current state
Start by inspecting the user, group, home directory, and active sessions. Replace <oldname> with the existing account.
pw usershow <oldname>
id <oldname>
getent passwd <oldname>
getent group <oldname>
who
Record the UID, primary GID, supplementary groups, login class, shell, and home directory. The UID matters because file ownership is stored numerically even when a display name changes.
Back up the account databases before editing them:
cp -p /etc/passwd /etc/passwd.pre-rename
cp -p /etc/master.passwd /etc/master.passwd.pre-rename
cp -p /etc/group /etc/group.pre-rename
These copies are a local rollback aid, not a replacement for a tested system backup.
Rename the user and group
For a typical local account with a matching private group, rename the user and then the group. The pw usermod command changes account attributes; pw groupmod changes the group name.
pw usermod <oldname> -n <newname> -d /home/<newname>
pw groupmod <oldname> -n <newname>
This example preserves the existing UID and GID because it does not request new numeric values. If the account uses a shared primary group, do not rename that group without first identifying every member and service that depends on it.
Confirm the account databases show the intended result:
pw usershow <newname>
id <newname>
getent passwd <newname>
getent group <newname>
Move the home directory deliberately
Changing the directory field does not necessarily move existing files. Move the home directory after the account rename, while no session is writing into it:
mv /home/<oldname> /home/<newname>
chown -R <newname>:<newname> /home/<newname>
Use the actual primary group if it is not named after the account. For large home directories, inspect ownership first and avoid an indiscriminate recursive change if the directory intentionally contains files owned by other users or service accounts.
Check the new path and representative ownership:
ls -ld /home/<newname>
find /home/<newname> -xdev -user <oldname> -print
The final command should return no files still associated with the old account name. A numeric-UID check is also useful if the old name no longer resolves.
Check references outside the account database
A local account name can appear in scheduled jobs, service configuration, sudo rules, SSH authorized-key locations, mail aliases, backup jobs, and application configuration. Search the configuration locations that exist on the host before removing any compatibility references:
grep -R "<oldname>" /etc /usr/local/etc 2>/dev/null
crontab -l -u <newname>
Review each hit rather than performing a global replacement. Some occurrences may be comments, audit records, or intentional historical references.
If the account has SSH access, confirm the new home directory contains the expected .ssh directory and that permissions remain restrictive:
ls -ld /home/<newname> /home/<newname>/.ssh
ls -l /home/<newname>/.ssh/authorized_keys
Verify and retain a rollback path
Open a new login session as <newname> before ending the original administrative session. Confirm the expected UID, group membership, home directory, shell, and access to required files.
id
pwd
If the account cannot log in, restore the saved account database files from a root console, then rebuild the password database with pwd_mkdb -p /etc/master.passwd. Do not attempt that rollback through the account being renamed.
This workflow applies to local FreeBSD accounts. Directory-backed identities, service accounts, ZFS home datasets, jail users, and configuration-management-managed accounts require an environment-specific change plan.
Treat service identities differently
Do not apply this workflow blindly to a daemon account. Service accounts may own files below /var, /usr/local, application data directories, or ZFS datasets; they can also be referenced by an rc script, jail configuration, database, or package-maintained file. Renaming one without an application-specific plan can prevent a service from starting or create a privilege boundary that no longer matches the service design.
For a person’s interactive account, inspect scheduled jobs, backups, and deployment tooling before the rename. Configuration-management systems should own the account declaration when they are in use; make the change in that system first, then apply it through its normal convergence path. A manual local change that is later overwritten by automation is not a successful migration.
Consider datasets and jails
A home directory may be a mount point rather than an ordinary directory. Check with mount, zfs list, and local storage documentation before using mv. If /home/<oldname> is a dedicated ZFS dataset, renaming or moving the directory is not enough: the dataset name, mountpoint property, snapshot policy, replication targets, and backup selection may also need to change.
Jails introduce a separate account database and filesystem root. A user visible inside a jail may not be the host account of the same name. Perform the account discovery and rename in the correct administrative domain, and avoid recursively changing ownership across a jail boundary from the host without understanding its UID mapping and service ownership.
Use numeric ownership checks
After a rename, most files remain correctly owned because the UID did not change. Validate that assumption numerically rather than relying only on displayed names. Compare the pre-change UID with id -u <newname>, then search appropriate application and home-directory paths for that UID. Keep the search scope narrow enough to avoid walking mounted backups, jails, or unrelated datasets.
Document the old name, retained UID, changed home path, approval, and verification result in the change record. That record is useful when a backup job or access-control list surfaces the historical name months later. Retain the old login name only when an explicit compatibility requirement exists; otherwise remove stale aliases after the new access path is proven.
Sources
- FreeBSD
pw(8)manual page: https://man.freebsd.org/cgi/man.cgi?query=pw&sektion=8 - FreeBSD Handbook: https://docs.freebsd.org/en/books/handbook/