1.\" $OpenBSD: useradd.8,v 1.34 2016/08/14 09:52:08 tb Exp $ 2.\" $NetBSD: useradd.8,v 1.26 2003/02/25 10:36:21 wiz Exp $ 3.\" 4.\" Copyright (c) 1999 Alistair G. Crooks. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Alistair G. Crooks. 17.\" 4. The name of the author may not be used to endorse or promote 18.\" products derived from this software without specific prior written 19.\" permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 22.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 25.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 27.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 29.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 30.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 31.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" 34.Dd $Mdocdate: August 14 2016 $ 35.Dt USERADD 8 36.Os 37.Sh NAME 38.Nm useradd 39.Nd add a user to the system 40.Sh SYNOPSIS 41.Nm useradd 42.Fl D 43.Op Fl b Ar base-directory 44.Op Fl e Ar expiry-time 45.Op Fl f Ar inactive-time 46.Op Fl g Ar gid | name | Cm =uid 47.Op Fl k Ar skel-directory 48.Op Fl L Ar login-class 49.Op Fl r Ar low Ns .. Ns Ar high 50.Op Fl s Ar shell 51.Nm useradd 52.Op Fl mov 53.Op Fl b Ar base-directory 54.Op Fl c Ar comment 55.Op Fl d Ar home-directory 56.Op Fl e Ar expiry-time 57.Op Fl f Ar inactive-time 58.Op Fl G Ar secondary-group Ns Op , Ns Ar group , Ns ... 59.Op Fl g Ar gid | name | Cm =uid 60.Op Fl k Ar skel-directory 61.Op Fl L Ar login-class 62.Op Fl p Ar password 63.Op Fl r Ar low Ns .. Ns Ar high 64.Op Fl s Ar shell 65.Op Fl u Ar uid 66.Ar user 67.Sh DESCRIPTION 68The 69.Nm useradd 70utility adds a user to the system, creating and 71populating a home directory if necessary. 72Any skeleton files will be provided 73for the new user if they exist in the 74.Ar skel-directory 75directory (see the 76.Fl k 77option). 78Default values for 79the base directory, 80the time of password expiry, 81the time of account expiry, 82primary group, 83the skeleton directory, 84the range from which the UID will be allocated, 85and default login shell 86can be provided in the 87.Pa /etc/usermgmt.conf 88file, which, if running as root, is created using the built-in defaults if 89it does not exist. 90.Pp 91The first form of the command shown above (using the 92.Fl D 93option) 94sets and displays the defaults for the 95.Nm 96utility. 97.Bl -tag -width Ds 98.It Fl b Ar base-directory 99Sets the base directory. 100This is the directory to which the user directory is added, 101which will be created if the 102.Fl m 103option is specified and no 104.Fl d 105option is specified. 106.It Fl D 107Without any further options, 108.Fl D 109will show the current defaults which 110will be used by the 111.Nm 112utility. 113Together with one of the options shown for the first version 114of the command, 115.Fl D 116will set the default to be the new value. 117See 118.Xr usermgmt.conf 5 119for more information. 120.It Fl e Ar expiry-time 121Sets the default time at which new accounts will expire. 122It should be entered in the form 123.Dq month day year , 124where month is the month name (the first three characters are 125sufficient), day is the day of the month, and year is the year. 126Time in seconds since the Epoch (UTC) is also valid. 127A value of 0 can be used to disable this feature. 128.It Fl f Ar inactive-time 129Sets the time at which passwords of new accounts will expire. 130Also see the 131.Fl e 132option above. 133.It Fl g Ar gid | name | Cm =uid 134Sets the default group for new users. 135.It Fl k Ar skel-directory 136Sets the skeleton directory in which to find files with 137which to populate new users' home directories. 138.It Fl L Ar login-class 139Sets the default login class for new users. 140See 141.Xr login.conf 5 142for more information on user login classes. 143.It Xo 144.Fl r Ar low Ns .. Ns Ar high 145.Xc 146Sets the low and high bounds of UID ranges for new users. 147A new user can only be created if there are UIDs which can be assigned 148from one of the free ranges. 149.It Fl s Ar shell 150Sets the default login shell for new users. 151.El 152.Pp 153In the second form of the command, 154after setting any defaults, and then reading values from 155.Pa /etc/usermgmt.conf , 156the following command line options are processed: 157.Bl -tag -width Ds 158.It Fl b Ar base-directory 159Sets the base directory name, in which the user's new home 160directory will be created, should the 161.Fl m 162option be specified. 163.It Fl c Ar comment 164Sets the comment field (also, for historical reasons known as the 165GECOS field) which will be added for the user, and typically will include 166the user's full name and, perhaps, contact information for the user. 167.It Fl d Ar home-directory 168Sets the home directory which will be created and populated for the user, 169should the 170.Fl m 171option be specified. 172.It Fl e Ar expiry-time 173Sets the time at which the user account will expire. 174It should be entered in the form 175.Dq month day year , 176where month is the month name (the first three characters are 177sufficient), day is the day of the month, and year is the year. 178Time in seconds since the Epoch (UTC) is also valid. 179A value of 0 can be used to disable this feature. 180See 181.Xr passwd 5 182for more details. 183.It Fl f Ar inactive-time 184Sets the time at which the current password will expire. 185Also see the 186.Fl e 187option above. 188.It Fl G Ar secondary-group Ns Op , Ns Ar group , Ns ... 189Sets the secondary groups to which the user will be added in the 190.Pa /etc/group 191file. 192.It Fl g Ar gid | name | Cm =uid 193Gives the group name or identifier to be used for the new user's primary group. 194If this is the special string 195.Cm =uid , 196then a UID and GID will be picked which are both unique 197and the same, and a line added to 198.Pa /etc/group 199to describe the new group. 200.It Fl k Ar skel-directory 201Gives the skeleton directory in which to find files 202with which to populate the new user's home directory. 203.It Fl L Ar login-class 204This option sets the login class for the user being created. 205See 206.Xr login.conf 5 207for more information on user login classes. 208.It Fl m 209Create a new home directory for the new user. 210.It Fl o 211Allow the new user to have a UID which is already in use for another user. 212.It Fl p Ar password 213Specifies a password encrypted with 214.Xr encrypt 1 215for the new user. 216This password can then be changed by using the 217.Xr chpass 1 218utility. 219If this option is not specified, and no default exists in 220.Pa /etc/usermgmt.conf , 221the account will be disabled by default. 222.It Fl s Ar shell 223Specifies the login shell for the new user. 224.It Fl u Ar uid 225Specifies a UID for the new user. 226Boundaries for this value can be preset for all users 227by using the 228.Ar range 229field in the 230.Pa /etc/usermgmt.conf 231file. 232.It Fl v 233Enables verbose mode - explain the commands as they are executed. 234.El 235.Pp 236Once the information has been verified, 237.Nm 238uses 239.Xr pwd_mkdb 8 240to update the user database. 241This is run in the background and, 242at very large sites, could take several minutes. 243Until this update is completed, the password file is unavailable for other 244updates and the new information is not available to programs. 245.Sh FILES 246.Bl -tag -width /etc/usermgmt.conf -compact 247.It Pa /etc/usermgmt.conf 248.It Pa /etc/skel/* 249.It Pa /etc/login.conf 250.El 251.Sh EXIT STATUS 252.Ex -std useradd 253.Sh SEE ALSO 254.Xr chpass 1 , 255.Xr group 5 , 256.Xr login.conf 5 , 257.Xr passwd 5 , 258.Xr usermgmt.conf 5 , 259.Xr pwd_mkdb 8 , 260.Xr user 8 , 261.Xr userdel 8 , 262.Xr usermod 8 263.Sh STANDARDS 264Other implementations of the 265.Nm useradd 266utility use the 267.Ar inactive-time 268parameter to refer to the maximum number of days allowed between logins (this 269is used to lock "stale" accounts that have not been used for a period of time). 270However, on 271.Ox 272systems this parameter refers instead to the password change time. 273This is due to differences in the 274.Xr passwd 5 275database compared to other operating systems. 276.Sh HISTORY 277The 278.Nm 279utility first appeared in 280.Ox 2.7 . 281.Sh AUTHORS 282The 283.Nm 284utility was written by 285.An Alistair G. Crooks Aq Mt agc@NetBSD.org . 286