Command Section
ADDUSER(8)              FreeBSD System Manager's Manual             ADDUSER(8)

     adduser - command for adding new users

     adduser [-CDENShq] [-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]

     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.  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.

             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

     GID/login group
             Automatically generated or your choice.  It must be less than

             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

     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)

     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

     -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

     -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;
    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.

     -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

     -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.

     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          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

     /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/adduser          logfile for adduser

     chpass(1), passwd(1), adduser.conf(5), aliases(5), group(5),
     login.conf(5), passwd(5), shells(5), adding_user(8), pw(8), pwd_mkdb(8),
     rmuser(8), vipw(8), yp(8)

     The adduser command appeared in FreeBSD 2.1.

     This manual page and the original script, in Perl, was written by Wolfram
     Schneider <[email protected]>.  The replacement script, written as a
     Bourne shell script with some enhancements, and the man page modification
     that came with it were done by Mike Makonnen <[email protected]>.

     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 11.1-RELEASE-p4       September 15, 2012       FreeBSD 11.1-RELEASE-p4
Command Section