The
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.
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
#include <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 (like cvs or ncvs on freefall),
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
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,
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
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:
-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,
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
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 checked.
-u uid
Use UIDs from
uid
on up.
-w type
Password type.
The
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.
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
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.
An -nosplit
This manual page and the original script, in Perl, was written by
An Wolfram Schneider Aq wosch@FreeBSD.org .
The replacement script, written as a Bourne
shell script with some enhancements, and the man page modification that
came with it were done by
An Mike Makonnen Aq mtm@identd.net .
BUGS
In order for
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
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.
