.\" Copyright 2007 Davor Ocelic. (Complete adduser rewrite)
.\" Copyright 1997, 1998, 1999 Guy Maor.
.\" Adduser and this manpage are copyright 1995 by Ted Hajek,
.\" With much borrowing from the original adduser copyright 1994 by
.\" Ian Murdock.
.\" 
.\" This is free software; see the GNU General Public License version
.\" 2 or later for copying conditions.  There is NO warranty.
.TH ADDUSER 8 "Version VERSION" "Debian GNU/Linux"
.SH NAME
adduser, addgroup \- add new system user, or existing user to existing group
.SH SYNOPSIS
.BR adduser " [options] user"
.PP
.BR adduser " [options] --system user"
.PP
.BR adduser " [options] user group"
.PP
.SH DESCRIPTION
.PP
.BR adduser
adds users to the system according to command line options
and configuration information in
.IR /etc/adduser/adduser.conf .
It is a friendlier front end to the low level tools like 
.BR useradd ", " groupadd " and " usermod.
It automatically chooses Debian policy conformant UID and GID values, 
creates home directories with skeletal configuration, runs custom 
script and provides other convenient features.

When two arguments are provided, they are treated as the name of an existing
user and the name of the existing group to which the user should be added.

Additionally, this enhanced version of 
.BR adduser
is based on a modular design, and it sports built-in support for
MIT Kerberos 5, OpenAFS, Coda and OpenLDAP.

.BR adduser 
can be run in one of three modes:
.SS "Add a normal user"
If called with one argument and without the
.BR --system
option, adduser will add a normal user.

.SS "Add a system user"
If called with one argument and the
.BR --system " option, " adduser
will add a system user. (The ability to distinguish between regular,
human users and system users is very important for
.BR adduser;
it comes really handy when using advanced modules,
such as Kerberos or OpenLDAP).

.SS "Add an existing user to an existing group"
If called with two non-option arguments,
.B adduser
will add an existing user to an existing group.

.SH OPTIONS
.TP
.B --uid ID
Force the new userid to be the given number.  adduser will fail if the userid
is already taken. If unspecified, the UID is chosen as first free ID 
between FIRST_UID and LAST_UID (or FIRST_SYSTEM_UID and LAST_SYSTEM_UID
respectively, depending on the --system option). If EQUAL_IDS is set, then
.BR adduser
will try to find the same ID for UID and GID value, making users have
the same UID and GID as long as there are any such combinations possible
(in respect to {FIRST,LAST}_[SYSTEM_]UID and {FIRST,LAST}_[SYSTEM_]GID).
.TP
.B --shell SHELL
Use SHELL as the user's login shell, rather than the default specified by
DSHELL.
.TP
.B --home DIR
Use DIR as the user's home directory. If the directory does not exist, all
elements of its path are created and skeleton files are copied.
When unspecified, home directory is derived
by combining DHOME, GROUPHOMES and LETTERHOMES variables.
.TP
.B --system
Add system user. This means that the account is intented to be used
by system daemons or other processes, and not by people directly. 
UID/GID numbers are selected from the [FIRST|LAST]_SYSTEM_[UID|GID] range
and the default Kerberos 5 policy is 'service' instead of 'user'.
.TP
.B --ingroup --in-group GROUP
Add the new user to existing GROUP instead of to its own new group 
(USERGROUPS=yes) or the default users' group (USERGROUPS=no,
USERS_GID=...).
.TP
.B --gecos GECOS
Set the gecos field for the new user.
.BR adduser
will not ask for finger information if this option is given.
GECOS is actually split in five fields separated by a comma:
a real name, room number, work phone, home phone, and other information.
This is a convention understood by the 'chfn' program. Stick to this rule
to ensure smooth operation in all modules. To specify just someone's
"other information", use --gecos ",,,,Other information".
.TP
.B --disabled-login
Do not run passwd to set the password.  The user won't be able to use
her account until the password is set. Exactly how is this implemented 
depends on the module. For example, if backend 'files' is used, user
password is set to the recognizable password-disabled string '*'. If using
files and Kerberos 5, then the password would be set to 'K' (another
spoken convention), and Kerberos principal would be added with option
.BR -randkey.
The -randkey option would actually set the password, but users would have
no practical chance of guessing it, thus as expected, login would be disabled.
.TP
.B --disabled-password
Like --disabled-login, but logins are still possible (for example using 
SSH RSA keys) but not using password authentication.
(TODO see exactly the diff between this and --disabled-login).
.TP
.B --no-create-home
Do not create the home directory.
.TP
.B --force\-badname
By default, usernames are checked against a configurable
regular expression (NAME_REGEX). This option forces
.B adduser
to apply only a weak, almost inexistent check for validity of the name.
.TP
.B --extra-groups --extra_groups
Override the list of extra groups (EXTRA_GROUPS) and imply
.BR --add-extra-groups.
.TP
.B --add-extra-groups --add_extra_groups
Add new user to extra groups defined in EXTRA_GROUPS.

.SH COMMON OPTIONS
.TP
.B --help -h
Display brief instructions.
.TP
.B --conf --configfile --cfg FILE
Use FILE instead of
.IR /etc/adduser/adduser.conf .
.TP
.B --action NAME
Manually set action to perform, and don't allow 
.BR adduser
to figure it out itself based on invoking program name and given
options and arguments.
.TP
.B --quiet -q
Suppress all informational messages, and only show serious warnings and errors.
.TP
.B --verbose
Be verbose. This is the default and produces a few lines of text
per module.
.TP
.B --debug
Be very verbose and informative, and report on each step. This is most useful
if you want to nail down a problem with
.BR adduser.
Make sure you include this debug output when filling bug reports.
.TP
.B --version -v
Display version and copyright information.
.SH FILES
/etc/adduser.conf
.SH "SEE ALSO"
adduser.conf(5), deluser(8), useradd(8), groupadd(8), usermod(8),
Debian Policy 9.2.2.

.SH COPYRIGHT
Copyright (C) 2007 Davor Ocelic. (Complete rewrite).
.br
Copyright (C) 1997, 1998, 1999 Guy Maor. Modifications by Roland
Bauerschmidt and Marc Haber.
.br
Copyright (C) 1995 Ted Hajek, with a great deal borrowed from the original
Debian 
.B adduser
.br
Copyright (C) 1994 Ian Murdock.
.br
.B adduser
is free software; see the GNU General Public Licence version 2 or
later for copying conditions.  There is
.I no
warranty.