14.1 Users and Basic Account Management

All access to the FreeBSD system is achieved through accounts, and all processes are run by users, therefore user and account management is the foundation of system security.

FreeBSD provides various user management tools. The adduser command adds new users interactively, automatically performing operations such as creating passwd entries, constructing new user home directories, and copying default configuration files from /usr/share/skel.

adduser(8) is a shell script that internally calls pw(8) to perform the actual user database operations. adduser(8) is not unique to FreeBSD; OpenBSD and DragonFly BSD also have their own implementations of adduser(8), but the options and behaviors differ.

The pw command is a lower-level user and group management tool that supports non-interactive batch operations and can directly modify system user database files.

User account information is stored in the master.passwd(5) file, which contains fields such as username, encrypted password, UID, GID, login class, password expiration time, account expiration time, GECOS information, home directory, and login shell.

Account Types

A valid user account is required to log in to the FreeBSD system.

The following shows users directly observed through the password file /etc/master.passwd:

root:$6$huh5iMfeueumGM3B$ycd9HsGOzKfFq6hbWMxceNBRCLibbSj5Ofjv/ed6Kq60M2F.syaGaxfdfYMqB79DZzqyhQlIiRZ4.D9ST90Gv/:0:0::0:0:Charlie &:/root:/bin/sh
toor:*:0:0::0:0:Bourne-again Superuser:/root:
daemon:*:1:1::0:0:Owner of many system processes:/root:/usr/sbin/nologin
operator:*:2:5::0:0:System &:/:/usr/sbin/nologin

……some entries omitted……

www:*:80:80::0:0:World Wide Web Owner:/nonexistent:/usr/sbin/nologin
ntpd:*:123:123::0:0:NTP Daemon:/var/db/ntp:/usr/sbin/nologin
nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/usr/sbin/nologin
ykla:$6$SqMJXrv5aC6Wq.by$nmbZs078aHNBVyh9noLFouJsGHyFSvQIzH0W4zpdfXuPtGtt.FHgWfXDHVBa.g9P0eZ32UwfByzRKdVnTaO7W.:1001:1001::0:0:User &:/home/ykla:/bin/sh

It can be seen that several user accounts exist in the system.

There are three main types of accounts in FreeBSD: system accounts, regular user accounts, and the superuser account.

System Accounts

System accounts are used to run services such as DNS, mail, and web servers. If all services run as the superuser, their operations will be unrestricted; this is the security rationale for using system accounts.

System accounts are defined by the main/etc/master.passwd file in the source code, totaling 27 as of this writing (26 accounts with UID < 1000 plus nobody(65534); this number may change with version iterations). _dhcp and ntpd are examples of such system accounts. System accounts are dedicated accounts with restricted permissions, typically used to run system services and daemons.

nobody is a generic unprivileged system account, but the more services use nobody, the more files and processes are associated with that user, and the greater its privileges become. Therefore, the best practice is to assign a separate system account to each service rather than sharing nobody.

Regular User Accounts

Regular user accounts are assigned to actual users for logging in and using the system. To facilitate administrators tracking user actions and prevent users from interfering with each other's settings, every person accessing the system should have a unique user account.

ykla is a regular user account created during system installation. If you want to switch to the root user via the su command, you must add this user to the wheel group. Additionally, some user accounts are system users automatically created by Ports.

Each user account on the FreeBSD system is associated with several attributes:

Attribute	Description
Username	The name entered at the login: prompt; each user must have a unique username. passwd(5) documents the rules for creating valid usernames. It is recommended to use eight or fewer lowercase characters as the username for backward compatibility
Password	Each account has an associated password
User ID (UID)	A number used to uniquely identify a user in the FreeBSD system. Since higher values may cause compatibility issues with some software, it is recommended to use UIDs less than 65535
Group ID (GID)	A number used to uniquely identify the primary group to which a user belongs. It is recommended to use a GID of 65535 or lower
Login Class	An extension of the group mechanism, providing additional flexibility when customizing the system for different users
Password Change Time	By default, passwords do not expire, but password expiration can be enabled on a per-user basis
Account Expiration Time	By default, FreeBSD does not expire accounts
Full Name	The username uniquely identifies a FreeBSD account, but does not necessarily reflect the user's real name
Home Directory	The starting directory when a user logs in. A common convention is to place all user home directories under /home/username or /usr/home/username
User Shell	The shell provides the default environment for user interaction with the system

Note that although regular users have limited privileges, the more software they run, the larger the system's attack surface becomes, providing more vulnerability entry points for attackers to exploit. Attackers can only leverage these processes for privilege escalation if the programs have vulnerabilities or are misconfigured.

Superuser Account

The superuser account, commonly referred to as root, is used for unrestricted system administration. Unlike regular user accounts, the superuser's operations are unrestricted, and misuse can lead to catastrophic consequences. Regular user accounts cannot damage the operating system through accidental actions, so it is recommended to log in as a regular user and switch to the superuser only when a command requires additional privileges.

In fact, the kernel determines whether an account has root privileges based on whether the account's EUID (Effective User ID) is 0. See: main/sys/kern/kern_priv.c[EB/OL]. [2026-03-26]. https://github.com/freebsd/freebsd-src/blob/main/sys/kern/kern_priv.c in the if (suser_enabled(cred)) code block.

There are multiple ways to obtain superuser privileges. Although it is possible to log in directly as root, this is not recommended; it is advisable to use the su(1) command to switch to the superuser.

Account Management

FreeBSD provides several different commands for managing user accounts.

Tools for Managing User Accounts

Command	Summary
adduser(8)	Recommended command-line application for adding new users.
rmuser(8)	Recommended command-line application for removing users.
chpass(1)	A flexible tool for changing user database information.
passwd(1)	A command-line tool for changing user passwords.
pw(8)	A powerful and flexible tool that can modify all aspects of user accounts.
bsdconfig(8)	A system configuration tool with account management support.

adduser Creating Users

The recommended program for adding new users is the script adduser(8). When adding a new user, this program automatically updates /etc/passwd and /etc/group.

adduser also creates a home directory for the new user and copies default configuration files from /usr/share/skel (source code path share/skel). The source code path for adduser is usr.sbin/adduser/adduser.sh.

adduser(8) is interactive and guides the creation of new user accounts step by step. As shown below, enter the required information or press Enter to accept the default values in brackets.

In this example, the user is invited to join the wheel group, enabling them to become the superuser via su(1).

After completion, the tool will prompt whether to create another user or exit.

Example: Create a regular user ykla and add it to the video group:

# adduser -G video -s sh -w yes
# Username: ykla

Example: Create user test and add it to the wheel group, setting its default shell to sh:

# adduser # This tool must be run by the superuser
Username: test # Username ①
Full name:  # Full name, can be left empty
Uid (Leave empty for default): # UID setting, can be left empty
Login group [test]: # Login group
Login group is test. Invite test into other groups? []: wheel # Set groups to join, separate multiple with spaces, can be left empty
Login class [default]: # Login class, can be left empty
Shell (sh csh tcsh nologin) [sh]: sh  # Unless the default Shell is manually set, the default Shell is sh
Home directory [/home/test]: # Specify home directory
Home directory permissions (Leave empty for default): # Specify home directory permissions
Enable ZFS encryption? (yes/no) [no]: # Whether to use ZFS encryption
Use password-based authentication? [yes]:  # Whether to use a password
Use an empty password? (yes/no) [no]:   # Whether to use an empty password
Use a random password? (yes/no) [no]:   # Whether to use a random password
Enter password: # Enter password
Enter password again: # Re-enter password
Lock out the account after creation? [no]: # Lock account?
Username   : test
Password   : *****
Full Name  :
Uid        : 1002
ZFS dataset : zroot/home/test
Class      :
Groups     : test wheel
Home       : /home/test
Home Mode  :
Shell      : /bin/sh
Locked     : no
OK? (yes/no): yes # Check for errors
adduser: INFO: Successfully created ZFS dataset (zroot/home/test).
adduser: INFO: Successfully added (test) to the user database.
Add another user? (yes/no): no # Need to create another account?
Goodbye!

Note

Since passwords are not printed on the screen when entered, nor displayed as mask characters *, please create user accounts carefully.

• ① Login name naming has some restrictions, see passwd(5)[EB/OL]. [2026-03-26]. https://man.freebsd.org/cgi/man.cgi?query=passwd&sektion=5. However, please note that login names do not support eight-bit encoded character sets, for example Chinese is not supported (i.e., only specific ASCII characters are supported).

Only root can use this command; otherwise, the following error will be displayed:

$ adduser test
adduser: ERROR: you must be the super-user (uid 0) to use this utility.

This indicates that only users with UID 0 (typically root) can invoke the adduser command.

rmuser Deleting Users

Warning

rmuser will permanently delete the user account and all related information including the home directory and mail, and this operation is irreversible. Using the -y parameter will skip the confirmation step, so make sure the username is correct.

rmuser is used to delete users. Like the adduser command, it is also an interactive script. The source code path for rmuser is usr.sbin/adduser/rmuser.sh.

Example: Delete users test1 test2.

# rmuser -y test1 test2 # Delete users test1 and test2 simultaneously
Removing user (test1): mailspool home passwd.
Removing user (test2): home passwd.

The -y parameter is used to skip the confirmation step.

chpass Changing User Information

All users can use chpass(1) to change their default shell and personal account information. The chpass source code is located at usr.bin/chpass.

Example: A regular user opens and modifies current user information using the nvi text editor.

$ chpass ykla       # Modify ykla's account information database
#Changing user information for ykla.
Shell: /bin/sh      # User shell
Full Name: User &   # User full name
Office Location:    # Office location
Office Phone:       # Office phone
Home Phone: # Home phone
Other information:  # Other information
~
~
~
/etc/pw.ogzb33: unmodified: line 1

root can use this tool to change additional account information for any user.

# chpass ykla       # Modify ykla's account information database
#Changing user information for ykla.
Login: ykla # Specify ykla
Password: $6$SqMJXrv5aC6Wq.by$nmbZs078aHNBVyh9noLFouJsGHyFSvQIzH0W4zpdfXuPtGtt.FHgWfXDHVBa
.g9P0eZ32UwfByzRKdVnTaO7W.  # User password
Uid [#]: 1001
Gid [# or name]: 1001
Change [month day year]:    # Password change date
Expire [month day year]:    # Account expiration date
Class:      # User class
Home directory: /home/ykla  # User home directory
Shell: /bin/sh
Full Name: User &
Office Location:
Office Phone:
Home Phone:
Other information:
~
~
~
/etc/pw.mDp9q3: unmodified: line 1

Example: Change user test1's login environment to /bin/sh.

# chpass -s sh test1
chpass: user information updated

Commonly used parameter: -s, used to modify the login shell.

Tip

chfn(1) and chsh(1) are linked commands to chpass(1), as are ypchpass(1), ypchfn(1), and ypchsh(1). Since NIS support is automatic, there is no need to prefix the command with yp. This can be inferred from the source code usr.bin/chpass/Makefile:

SYMLINKS= chpass ${BINDIR}/chfn
SYMLINKS+=        chpass ${BINDIR}/chsh
.if ${MK_NIS} != "no"     # If the system has NIS enabled
SYMLINKS+=        chpass ${BINDIR}/ypchfn
SYMLINKS+=        chpass ${BINDIR}/ypchpass
SYMLINKS+=        chpass ${BINDIR}/ypchsh
.endif

MLINKS=   chpass.1 chfn.1 chpass.1 chsh.1
.if ${MK_NIS} != "no"
MLINKS+= chpass.1 ypchpass.1 chpass.1 ypchfn.1 chpass.1 ypchsh.1
.endif

passwd Changing User Password

To change a user's password; if no user is specified, the current user is assumed. Regular users can only change their own passwords; otherwise, the following error will be displayed:

$ passwd test
passwd: permission denied

Example: Use ykla to change its own password.

$ passwd ykla
Changing local password for ykla
Old Password:       # Enter old password
New Password:       # Enter new password
Retype New Password:        # Re-enter new password

The root user can change all users' passwords without requiring the old password.

Example: Use root to change user ykla's password.

# passwd ykla
Changing local password for ykla
New Password:       # Enter new password
Retype New Password:        # Re-enter new password

Tip

FreeBSD's passwd options differ from Linux; for locking/unlocking accounts, use pw lock/unlock.

Group Management

A group is a list of users. A group is identified by its group name and GID. In FreeBSD, the kernel uses the process's UID and its group list to determine the range of operations a process can perform. In most cases, the user or process GID usually refers to the first group in the list.

The mapping of group names to GIDs is listed in /etc/group. /etc/group is a plain text file with four colon-separated fields.

# cat /etc/group
wheel:*:0:root,ykla #
operator:*:5:root

……partial output omitted……

ykla:*:1001:
test:*:1002:

It can be seen that the format of /etc/group is like group_name:encrypted_password:GID:member_list, separated by colons.

The superuser can modify /etc/group using a text editor, but editing errors may cause serious consequences, so this is not recommended. It is recommended to use pw(8) to add and edit groups.

Warning

The operator group may grant unexpected superuser-like access privileges, including but not limited to shutdown (shutdown) and access to some devices in /dev (such as disk devices), so please be careful when using this group. Note that reboot and halt are restricted to root users only; operator group members cannot execute them.

In FreeBSD, the pw command can be used to manage users and groups: it is a front-end to the system user and group files. pw(8) provides very powerful command-line options suitable for shell scripts, but may be more complex for new users than other commands in this section.

Adding Groups

Use pw(8) to add groups:

# pw groupadd ykla2
# pw groupshow ykla2
ykla2:*:1002:

In this example, 1002 is the GID of ykla2. At this point, ykla2 has no members.

Adding Users to Groups

Use pw(8) to add users to groups.

Example: Set the members of group test5 to test1.

# pw groupmod test5 -M test1 # Existing members will be deleted!

Example: Add user ykla to both ykla2 and wheel groups:

# pw usermod ykla -G ykla2,wheel

-G group list, comma-separated.

Verify as follows:

# id ykla
uid=1001(ykla) gid=1001(ykla) groups=1001(ykla),0(wheel),1002(ykla2)

Example: Add user test to the wheel group (the wheel group is a system default group and does not need to be created):

# pw groupmod wheel -m test

In this example, the argument passed to -m is a list of users (comma-separated) that are appended to the group and do not replace existing users.

Deleting Groups

Example: Delete the admin group:

# pw groupdel admin

Removing Users from Groups

Example: Remove user ykla from the admin group:

# pw groupmod admin -d ykla

Adding Users

The pw useradd command is used to create new users.

Example: Create user test1.

# pw useradd test1 # uid system default, test1 group, login environment /bin/sh, home directory not created

Example: Create user test2.

# pw useradd test2 -u 1200 -m -d /tmp/test -g test2 -G wheel -s sh -c test2 # Create user test2: UID 1200, create home directory /tmp/test, primary group test2, supplementary wheel group, login shell sh, full name test2

Modifying User Information

The pw usermod command is used to modify user information.

Example:

# pw usermod test1 -l test2 # Rename user test1 to test2

The -l option modifies the username.

Deleting Users

The pw userdel command is used to delete users.

Warning

pw userdel -r will permanently delete the user and their home directory and all related information, and this operation is irreversible. If the home directory is a ZFS dataset, pw(8) only deletes the files within it and does not destroy the dataset; you must manually execute zfs destroy to destroy the dataset and its child datasets and snapshots. Please make sure the username is correct.

Example: Delete user test2 and its home directory.

# pw userdel -r test2

Commonly used parameter: -r deletes the user along with the home directory and all related information; without this parameter, only the user is deleted and the information is retained. If the home directory is a ZFS dataset, pw(8) only deletes the files within it and does not destroy the dataset; you must manually execute zfs destroy to destroy the dataset and its child datasets and snapshots.

Displaying User Information

The pw usershow command is used to display user information.

Example: Display detailed information for user test2.

# pw usershow test2
test2:$6$FkxPcs2y.Y8cxyuj$kVDoV1LC.IWKGlSitll3oLArF18aHQYID0JYE.TUuD0YFgba.c7MbGs3xLnmpCZyu1nVKHhNqW2X7a57qN0xg/:1201:1201::0:0:User &:/home/test2:/bin/sh

Modifying Group Information

The pw groupmod command is used to modify group information.

Example: Change the gid of group test to 1300.

# pw groupmod test -g 1300

Example: Rename group test to test2.

# pw groupmod test -l test2

References

• FreeBSD Project. pw(8)[EB/OL]. [2026-03-26]. https://man.freebsd.org/cgi/man.cgi?query=pw&sektion=8. Manual page, introducing user and group management commands.

Exercises

1. Modify the FreeBSD source code to enable UTF-8 encoding support for usernames.
2. Review the source code implementation of the pw command in FreeBSD and make it more modernized.