'\" te
.\" Copyright (c) 2018 Peter Tribble.
.\" Copyright (c) 2013 Gary Mills
.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH USERADD 8 "Jan 7, 2018"
.SH NAME
useradd \- administer a new user login on the system
.SH SYNOPSIS
.LP
.nf
\fBuseradd\fR [\fB-A\fR \fIauthorization\fR[,\fIauthorization\fR]...]
     [\fB-b\fR \fIbase_dir\fR] [\fB-c\fR \fIcomment\fR] [\fB-d\fR \fIdir\fR] [\fB-e\fR \fIexpire\fR]
     [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR] [\fB-G\fR \fIgroup\fR[,\fIgroup\fR]...]
     [\fB-K\fR \fIkey=value\fR] [\fB-m\fR [\fB-z|-Z\fR] [\fB-k\fR \fIskel_dir\fR]] [\fB-p\fR \fIprojname\fR]
     [\fB-P\fR \fIprofile\fR[,\fIprofile\fR]...] [\fB-R\fR \fIrole\fR[,\fIrole\fR]...]
     [\fB-s\fR \fIshell\fR] [\fB-u\fR \fIuid\fR [\fB-o\fR]] \fIlogin\fR
.fi

.LP
.nf
\fBuseradd\fR \fB-D\fR [\fB-A\fR \fIauthorization\fR[,\fIauthorization\fR]...]
     [\fB-b\fR \fIbase_dir\fR] [\fB-e\fR \fIexpire\fR] [\fB-f\fR \fIinactive\fR] [\fB-g\fR \fIgroup\fR]
     [\fB-k\fR \fIskel_dir\fR] [\fB-K\fR \fIkey=value\fR] [\fB-p\fR \fIprojname\fR]
     [\fB-P\fR \fIprofile\fR[,\fIprofile\fR]...] [\fB-R\fR \fIrole\fR[,\fIrole\fR]...]
     [\fB-s\fR \fIshell\fR]
.fi

.SH DESCRIPTION
.LP
\fBuseradd\fR adds a new user to the \fB/etc/passwd\fR and \fB/etc/shadow\fR
and \fB/etc/user_attr\fR files. The \fB-A\fR and \fB-P\fR options respectively
assign authorizations and profiles to the user. The \fB-R\fR option assigns
roles to the user. The \fB-p\fR option associates a project with the user. The
\fB-K\fR option adds a \fIkey=value\fR pair to \fB/etc/user_attr\fR for the
user. Multiple \fIkey=value\fR pairs may be added with multiple \fB-K\fR
options.
.sp
.LP
\fBuseradd\fR also creates supplementary group memberships for the user
(\fB-G\fR option) and creates the home directory (\fB-m\fR option) for the user
if requested. The new login remains locked until the \fBpasswd\fR(1) command is
executed.
.sp
.LP
Specifying \fBuseradd\fR \fB-D\fR with the \fB-A\fR, \fB-b\fR, \fB-e\fR,
\fB-f\fR, \fB-g\fR, \fB-k\fR, \fB-K\fR, \fB-p\fR, \fB-P\fR, \fB-R\fR, or
\fB-s\fR option (or any combination of these options) sets the default values
for the respective fields. See the \fB-D\fR option, below. Subsequent
\fBuseradd\fR commands without the \fB-D\fR option use these arguments.
.sp
.LP
The system file entries created with this command have a limit of 2048
characters per line. Specifying long arguments to several options can exceed
this limit.
.sp
.LP
\fBuseradd\fR requires that usernames be in the format described in
\fBpasswd\fR(5). A warning message is displayed if these restrictions are not
met. See \fBpasswd\fR(5) for the requirements for usernames.
.LP
To change the action of \fBuseradd\fR when the traditional login name
length limit of eight characters is exceeded, edit the file
\fB/etc/default/useradd\fR by removing the \fB#\fR (pound sign) before the
appropriate \fBEXCEED_TRAD=\fR entry, and adding it before the others.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-A\fR \fIauthorization\fR\fR
.ad
.sp .6
.RS 4n
One or more comma separated authorizations defined in \fBauth_attr\fR(5). Only
a user or role who has \fBgrant\fR rights to the authorization can assign it to
an account.
.RE

.sp
.ne 2
.na
\fB\fB-b\fR \fIbase_dir\fR\fR
.ad
.sp .6
.RS 4n
The base directory for new login home directories (see the \fB-d\fR option
below). The directory named by \fIbase_dir\fR must already exist and be an
absolute path.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIcomment\fR\fR
.ad
.sp .6
.RS 4n
A text string. It is generally a short description of the login, and is
currently used as the field for the user's full name. This information is
stored in the user's \fB/etc/passwd\fR entry.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIdir\fR\fR
.ad
.sp .6
.RS 4n
The home directory of the new user. If not supplied, it defaults to
\fIbase_dir\fR/\fIaccount_name\fR, where \fIbase_dir\fR is the base directory
for new login home directories and \fIaccount_name\fR is the new login name.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.sp .6
.RS 4n
Display the default values for \fBgroup\fR, \fBbase_dir\fR, \fBskel_dir\fR,
\fBshell\fR, \fBinactive\fR, \fBexpire\fR, \fBproj\fR, \fBprojname\fR and
\fBkey=value\fR pairs. When used with the \fB-A\fR, \fB-b\fR, \fB-e\fR,
\fB-f\fR, \fB-g\fR, \fB-P\fR, \fB-p\fR, \fB-R\fR, or \fB-K\fR options, the
\fB-D\fR option sets the default values for the specified fields. The default
values are:
.sp
.ne 2
.na
\fBgroup\fR
.ad
.sp .6
.RS 4n
\fBother\fR (\fBGID\fR of 1)
.RE

.sp
.ne 2
.na
\fBbase_dir\fR
.ad
.sp .6
.RS 4n
\fB/home\fR
.RE

.sp
.ne 2
.na
\fBskel_dir\fR
.ad
.sp .6
.RS 4n
\fB/etc/skel\fR
.RE

.sp
.ne 2
.na
\fBshell\fR
.ad
.sp .6
.RS 4n
\fB/bin/sh\fR
.RE

.sp
.ne 2
.na
\fBinactive\fR
.ad
.sp .6
.RS 4n
\fB0\fR
.RE

.sp
.ne 2
.na
\fBexpire\fR
.ad
.sp .6
.RS 4n
null
.RE

.sp
.ne 2
.na
\fBauths\fR
.ad
.sp .6
.RS 4n
null
.RE

.sp
.ne 2
.na
\fBprofiles\fR
.ad
.sp .6
.RS 4n
null
.RE

.sp
.ne 2
.na
\fBproj\fR
.ad
.sp .6
.RS 4n
\fB3\fR
.RE

.sp
.ne 2
.na
\fBprojname\fR
.ad
.sp .6
.RS 4n
\fBdefault\fR
.RE

.sp
.ne 2
.na
\fBkey=value\fR (pairs defined in \fBuser_attr\fR(5))
.ad
.sp .6
.RS 4n
not present
.RE

.sp
.ne 2
.na
\fBroles\fR
.ad
.sp .6
.RS 4n
null
.RE

.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIexpire\fR\fR
.ad
.sp .6
.RS 4n
Specify the expiration date for a login. After this date, no user will be able
to access this login. The expire option argument is a date entered using one of
the date formats included in the template file \fB/etc/datemsk\fR. See
\fBgetdate\fR(3C).
.sp
If the date format that you choose includes spaces, it must be quoted. For
example, you can enter \fB10/6/90\fR or \fBOctober 6, 1990\fR. A null value
(\fB" "\fR) defeats the status of the expired date. This option is useful for
creating temporary logins.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIinactive\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of days allowed between uses of a login ID before that
\fBID\fR is declared invalid. Normal values are positive integers. A value of
\fB0\fR defeats the status.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR \fIgroup\fR\fR
.ad
.sp .6
.RS 4n
An existing group's integer \fBID\fR or character-string name. Without the
\fB-D\fR option, it defines the new user's primary group membership and
defaults to the default group. You can reset this default value by invoking
\fBuseradd\fR \fB-D\fR \fB-g\fR \fIgroup\fR. GIDs 0-99 are reserved for
allocation by the Operating System.
.RE

.sp
.ne 2
.na
\fB\fB-G\fR \fIgroup\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated existing groups, specified by integer \fBID\fR or
character-string name. It defines the new user's supplementary group
membership. Any duplicate groups between the \fB-g\fR and \fB-G\fR options are
ignored. No more than \fBNGROUPS_MAX\fR groups can be specified. GIDs 0-99 are
reserved for allocation by the Operating System.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR \fIskel_dir\fR\fR
.ad
.sp .6
.RS 4n
A directory that contains skeleton information (such as \fB\&.profile\fR) that
can be copied into a new user's home directory. This directory must already
exist. The system provides the \fB/etc/skel\fR directory that can be used for
this purpose.
.RE

.sp
.ne 2
.na
\fB\fB-K\fR \fIkey=value\fR\fR
.ad
.sp .6
.RS 4n
A \fIkey=value\fR pair to add to the user's attributes. Multiple \fB-K\fR
options may be used to add multiple \fIkey=value\fR pairs. The generic \fB-K\fR
option with the appropriate key may be used instead of the specific implied key
options (\fB-A\fR, \fB-p\fR, \fB-P\fR, \fB-R\fR). See \fBuser_attr\fR(5) for a
list of valid \fIkey=value\fR pairs. The "type" key is not a valid key for this
option. Keys cannot be repeated.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR [\fB-z|-Z\fR]
.ad
.sp .6
.RS 4n
Create the new user's home directory if it does not already exist. If the
directory already exists, it must have read, write, and execute permissions by
\fIgroup\fR, where \fIgroup\fR is the user's primary group.
.sp
If the parent directory of the user's home directory is located on a separate
\fBZFS\fR file system and the \fB/etc/default/useradd\fR file contains the
parameter \fBMANAGE_ZFS\fR set to the value \fBYES\fR, a new \fBZFS\fR
file system will be created for the user.
.sp
If the \fB-z\fR option is specified, \fBuseradd\fR will always try to create
a new file system for the home directory.
.sp
If the \fB-Z\fR option is specified, a new file system will never be created.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.sp .6
.RS 4n
This option allows a \fBUID\fR to be duplicated (non-unique).
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIprojname\fR\fR
.ad
.sp .6
.RS 4n
Name of the project with which the added user is associated. See the
\fIprojname\fR field as defined in \fBproject\fR(5).
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIprofile\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated execution profiles defined in \fBprof_attr\fR(5).
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fIrole\fR\fR
.ad
.sp .6
.RS 4n
One or more comma-separated roles defined in \fBuser_attr\fR(5).
Roles cannot be assigned to other roles.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIshell\fR\fR
.ad
.sp .6
.RS 4n
Full pathname of the program used as the user's shell on login. It defaults to
an empty field causing the system to use \fB/bin/sh\fR as the default. The
value of \fIshell\fR must be a valid executable file.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIuid\fR\fR
.ad
.sp .6
.RS 4n
The \fBUID\fR of the new user. This \fBUID\fR must be a non-negative decimal
integer below \fBMAXUID\fR as defined in \fB<sys/param.h>\fR\&. The \fBUID\fR
defaults to the next available (unique) number above the highest number
currently assigned. For example, if \fBUID\fRs 100, 105, and 200 are assigned,
the next default \fBUID\fR number will be 201. \fBUID\fRs \fB0\fR-\fB99\fR are
reserved for allocation by the Operating System.
.RE

.SH FILES
.LP
\fB/etc/default/useradd\fR
.sp
.LP
\fB/etc/datemsk\fR
.sp
.LP
\fB/etc/passwd\fR
.sp
.LP
\fB/etc/shadow\fR
.sp
.LP
\fB/etc/group\fR
.sp
.LP
\fB/etc/skel\fR
.sp
.LP
\fB/usr/include/limits.h\fR
.sp
.LP
\fB/etc/user_attr\fR
.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.LP
.BR passwd (1),
.BR profiles (1),
.BR roles (1),
.BR getdate (3C),
.BR auth_attr (5),
.BR passwd (5),
.BR prof_attr (5),
.BR project (5),
.BR user_attr (5),
.BR attributes (7),
.BR groupadd (8),
.BR groupdel (8),
.BR groupmod (8),
.BR grpck (8),
.BR logins (8),
.BR pwck (8),
.BR userdel (8),
.BR usermod (8),
.BR zfs (8)
.SH DIAGNOSTICS
.LP
In case of an error, \fBuseradd\fR prints an error message and exits with a
non-zero status.
.sp
.LP
The following indicates that \fBlogin\fR specified is already in use:
.sp
.in +2
.nf
UX: useradd: ERROR: login is already in use. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIuid\fR specified with the \fB-u\fR option
is not unique:
.sp
.in +2
.nf
UX: useradd: ERROR: uid \fIuid\fR is already in use. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIgroup\fR specified with the \fB-g\fR option
is already in use:
.sp
.in +2
.nf
UX: useradd: ERROR: group \fIgroup\fR does not exist. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIuid\fR specified with the \fB-u\fR option
is in the range of reserved \fBUID\fRs (from \fB0\fR-\fB99\fR):
.sp
.in +2
.nf
UX: useradd: WARNING: uid \fIuid\fR is reserved.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fIuid\fR specified with the \fB-u\fR option
exceeds \fBMAXUID\fR as defined in \fB<sys/param.h>\fR:
.sp
.in +2
.nf
UX: useradd: ERROR: uid \fIuid\fR is too big. Choose another.
.fi
.in -2
.sp

.sp
.LP
The following indicates that the \fB/etc/passwd\fR or \fB/etc/shadow\fR files
do not exist:
.sp
.in +2
.nf
UX: useradd: ERROR: Cannot update system files - login cannot be created.
.fi
.in -2
.sp

.SH NOTES
.LP
The \fBuseradd\fR utility adds definitions to only the local \fB/etc/group\fR,
\fB/etc/passwd\fR, \fB/etc/shadow\fR, \fB/etc/project\fR, and
\fB/etc/user_attr\fR files. If a network name service
is being used to supplement the local \fB/etc/passwd\fR file with
additional entries, \fBuseradd\fR cannot change information supplied by the
network name service. However \fBuseradd\fR will verify the uniqueness of the
user name (or role) and user id and the existence of any group names specified
against the external name service.