ADDUSER(8) FreeBSD System Manager's Manual ADDUSER(8)
NAME
adduser - command for adding new users
SYNOPSIS
adduser [-CDENSZhq] [-G groups] [-L login_class] [-M mode] [-d partition]
[-f file] [-g login_group] [-k dotdir] [-m message_file]
[-s shell] [-u uid_start] [-w type]
DESCRIPTION
The adduser utility is a shell script, implemented around the pw(8)
command, for adding new users. It creates passwd/group entries, a home
directory, copies dotfiles and sends the new user a welcome message. On
systems where the parent of home directory is a ZFS dataset, adduser will
create the home directory as a ZFS dataset by default, unless the system
administrator specified otherwise. It supports two modes of operation.
It may be used interactively at the command line to add one user at a
time, or it may be directed to get the list of new users from a file and
operate in batch mode without requiring any user interaction.
RESTRICTIONS
username
Login name. The user name is restricted to whatever pw(8) will
accept. Generally this means it may contain only lowercase
characters or digits but cannot begin with the `-' character.
Maximum length is 16 characters. The reasons for this limit are
historical. Given that people have traditionally wanted to break
this limit for aesthetic reasons, it has never been of great
importance to break such a basic fundamental parameter in Unix.
You can change UT_NAMESIZE in <utmp.h> and recompile the world;
people have done this and it works, but you will have problems
with any precompiled programs, or source that assumes the
8-character name limit, such as NIS. The NIS protocol mandates
an 8-character username. If you need a longer login name for e-
mail addresses, you can define an alias in /etc/mail/aliases.
full name
This is typically known as the gecos field and usually contains
the user's full name. Additionally, it may contain a comma
separated list of values such as office number and work and home
phones. If the name contains an ampersand it will be replaced by
the capitalized login name when displayed by other programs. The
`:' character is not allowed.
shell Unless the -S argument is supplied only valid shells from the
shell database (/etc/shells) are allowed. In addition, either
the base name or the full path of the shell may be supplied.
UID Automatically generated or your choice. It must be less than
32000.
GID/login group
Automatically generated or your choice. It must be less than
32000.
password
You may choose an empty password, disable the password, use a
randomly generated password or specify your own plaintext
password, which will be encrypted before being stored in the user
database.
UNIQUE GROUPS
Perhaps you are missing what can be done with this scheme that falls
apart with most other schemes. With each user in their own group, they
can safely run with a umask of 002 instead of the usual 022 and create
files in their home directory without worrying about others being able to
change them.
For a shared area you create a separate UID/GID, you place each person
that should be able to access this area into that new group.
This model of UID/GID administration allows far greater flexibility than
lumping users into groups and having to muck with the umask when working
in a shared area.
I have been using this model for almost 10 years and found that it works
for most situations, and has never gotten in the way. (Rod Grimes)
CONFIGURATION
The adduser utility reads its configuration information from
/etc/adduser.conf. If this file does not exist, it will use predefined
defaults. While this file may be edited by hand, the safer option is to
use the -C command line argument. With this argument, adduser will start
interactive input, save the answers to its prompts in /etc/adduser.conf,
and promptly exit without modifying the user database. Options specified
on the command line will take precedence over any values saved in this
file.
OPTIONS
-C Create new configuration file and exit. This option is mutually
exclusive with the -f option.
-d partition
Home partition. Default partition, under which all user
directories will be located. The /nonexistent partition is
considered special. The adduser script will not create and
populate a home directory by that name. Otherwise, by default it
attempts to create a home directory.
-D Do not attempt to create the home directory.
-E Disable the account. This option will lock the account by
prepending the string "*LOCKED*" to the password field. The
account may be unlocked by the super-user with the pw(8) command:
pw unlock [name | uid]
-f file
Get the list of accounts to create from file. If file is "-",
then get the list from standard input. If this option is
specified, adduser will operate in batch mode and will not seek
any user input. If an error is encountered while processing an
account, it will write a message to standard error and move to
the next account. The format of the input file is described
below.
-g login_group
Normally, if no login group is specified, it is assumed to be the
same as the username. This option makes login_group the default.
-G groups
Space-separated list of additional groups. This option allows
the user to specify additional groups to add users to. The user
is a member of these groups in addition to their login group.
-h Print a summary of options and exit.
-k directory
Copy files from directory into the home directory of new users;
dot.foo will be renamed to .foo.
-L login_class
Set default login class.
-m file
Send new users a welcome message from file. Specifying a value
of no for file causes no message to be sent to new users. Please
note that the message file can reference the internal variables
of the adduser script.
-M mode
Create the home directory with permissions set to mode, modified
by the current umask(2).
-N Do not read the default configuration file.
-q Minimal user feedback. In particular, the random password will
not be echoed to standard output.
-s shell
Default shell for new users. The shell argument may be the base
name of the shell or the full path. Unless the -S argument is
supplied the shell must exist in /etc/shells or be the special
shell nologin to be considered a valid shell.
-S The existence or validity of the specified shell will not be
checked.
-u uid Use UIDs from uid on up.
-w type
Password type. The adduser utility allows the user to specify
what type of password to create. The type argument may have one
of the following values:
no Disable the password. Instead of an encrypted string,
the password field will contain a single `*' character.
The user may not log in until the super-user manually
enables the password.
none Use an empty string as the password.
yes Use a user-supplied string as the password. In
interactive mode, the user will be prompted for the
password. In batch mode, the last (10th) field in the
line is assumed to be the password.
random Generate a random string and use it as a password. The
password will be echoed to standard output. In addition,
it will be available for inclusion in the message file in
the randompass variable.
-Z Do not attempt to create ZFS home dataset.
FORMAT
When the -f option is used, the account information must be stored in a
specific format. All empty lines or lines beginning with a `#' will be
ignored. All other lines must contain ten colon (`:') separated fields
as described below. Command line options do not take precedence over
values in the fields. Only the password field may contain a `:'
character as part of the string.
name:uid:gid:class:change:expire:gecos:home_dir:shell:password
name Login name. This field may not be empty.
uid Numeric login user ID. If this field is left empty, it will be
automatically generated.
gid Numeric primary group ID. If this field is left empty, a group
with the same name as the user name will be created and its GID
will be used instead.
class Login class. This field may be left empty.
change Password ageing. This field denotes the password change date
for the account. The format of this field is the same as the
format of the -p argument to pw(8). It may be dd-mmm-yy[yy],
where dd is for the day, mmm is for the month in numeric or
alphabetical format: "10" or "Oct", and yy[yy] is the four or
two digit year. To denote a time relative to the current date
the format is: +n[mhdwoy], where n denotes a number, followed
by the minutes, hours, days, weeks, months or years after which
the password must be changed. This field may be left empty to
turn it off.
expire Account expiration. This field denotes the expiry date of the
account. The account may not be used after the specified date.
The format of this field is the same as that for password
ageing. This field may be left empty to turn it off.
gecos Full name and other extra information about the user.
home_dir Home directory. If this field is left empty, it will be
automatically created by appending the username to the home
partition. The /nonexistent home directory is considered
special and is understood to mean that no home directory is to
be created for the user.
shell Login shell. This field should contain either the base name or
the full path to a valid login shell.
password User password. This field should contain a plaintext string,
which will be encrypted before being placed in the user
database. If the password type is yes and this field is empty,
it is assumed the account will have an empty password. If the
password type is random and this field is not empty, its
contents will be used as a password. This field will be
ignored if the -w option is used with a no or none argument.
Be careful not to terminate this field with a closing `:'
because it will be treated as part of the password.
FILES
/etc/master.passwd user database
/etc/group group database
/etc/shells shell database
/etc/login.conf login classes database
/etc/adduser.conf configuration file for adduser
/etc/adduser.message message file for adduser
/usr/share/skel skeletal login directory
/var/log/userlog logfile for adduser
SEE ALSO
chpass(1), passwd(1), adduser.conf(5), aliases(5), group(5),
login.conf(5), passwd(5), shells(5), groups(7), pw(8), pwd_mkdb(8),
rmuser(8), vipw(8), yp(8)
HISTORY
The adduser command appeared in FreeBSD 2.1.
AUTHORS
This manual page and the original script, in Perl, was written by Wolfram
Schneider <wosch@FreeBSD.org>. The replacement script, written as a
POSIX shell script with some enhancements, and the man page modification
that came with it were done by Mike Makonnen <mtm@identd.net>.
BUGS
In order for adduser to correctly expand variables such as $username and
$randompass in the message sent to new users, it must let the shell
evaluate each line of the message file. This means that shell commands
can also be embedded in the message file. The adduser utility attempts
to mitigate the possibility of an attacker using this feature by refusing
to evaluate the file if it is not owned and writable only by the root
user. In addition, shell special characters and operators will have to
be escaped when used in the message file.
Also, password ageing and account expiry times are currently settable
only in batch mode or when specified in /etc/adduser.conf. The user
should be able to set them in interactive mode as well.
FreeBSD 15.1-STABLE-HBSD April 19, 2026 ADDUSER(8)