1.\" $OpenBSD: useradd.8,v 1.27 2009/01/21 16:56:03 sobrado 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: January 21 2009 $ 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.Bk -words 43.Fl D 44.Op Fl b Ar base-directory 45.Op Fl e Ar expiry-time 46.Op Fl f Ar inactive-time 47.Oo 48.Fl g Ar gid | name | Li =uid Oc 49.Op Fl k Ar skel-directory 50.Op Fl L Ar login-class 51.Oo 52.Fl r Ar low Ns Li .. Ns Ar high 53.Oc 54.Op Fl s Ar shell 55.Ek 56.Nm useradd 57.Bk -words 58.Op Fl mov 59.Op Fl b Ar base-directory 60.Op Fl c Ar comment 61.Op Fl d Ar home-directory 62.Op Fl e Ar expiry-time 63.Op Fl f Ar inactive-time 64.Op Fl G Ar secondary-group[,group,...] 65.Oo 66.Fl g Ar gid | name | Li =uid Oc 67.Op Fl k Ar skel-directory 68.Op Fl L Ar login-class 69.Op Fl p Ar password 70.Oo 71.Fl r Ar low Ns Li .. Ns Ar high 72.Oc 73.Op Fl s Ar shell 74.Op Fl u Ar uid 75.Ar user 76.Ek 77.Sh DESCRIPTION 78The 79.Nm useradd 80utility adds a user to the system, creating and 81populating a home directory if necessary. 82Any skeleton files will be provided 83for the new user if they exist in the 84.Ar skel-directory 85directory (see the 86.Fl k 87option). 88Default values for 89the base directory, 90the time of password expiry, 91the time of account expiry, 92primary group, 93the skeleton directory, 94the range from which the UID will be allocated, 95and default login shell 96can be provided in the 97.Pa /etc/usermgmt.conf 98file, which, if running as root, is created using the built-in defaults if 99it does not exist. 100.Pp 101The first form of the command shown above (using the 102.Fl D 103option) 104sets and displays the defaults for the 105.Nm 106utility. 107.Bl -tag -width Ds 108.It Fl b Ar base-directory 109Sets the base directory. 110This is the directory to which the user directory is added, 111which will be created if the 112.Fl m 113option is specified and no 114.Fl d 115option is specified. 116.It Fl D 117Without any further options, 118.Fl D 119will show the current defaults which 120will be used by the 121.Nm 122utility. 123Together with one of the options shown for the first version 124of the command, 125.Fl D 126will set the default to be the new value. 127See 128.Xr usermgmt.conf 5 129for more information. 130.It Fl e Ar expiry-time 131Sets the default time at which new accounts will expire. 132It should be entered in the form 133.Dq month day year , 134where month is the month name (the first three characters are 135sufficient), day is the day of the month, and year is the year. 136Time in seconds since the Epoch (UTC) is also valid. 137A value of 0 can be used to disable this feature. 138.It Fl f Ar inactive-time 139Sets the time at which passwords of new accounts will expire. 140Also see the 141.Fl e 142option above. 143.It Fl g Ar gid | name | Li =uid 144Sets the default group for new users. 145.It Fl k Ar skel-directory 146Sets the skeleton directory in which to find files with 147which to populate new users' home directories. 148.It Fl L Ar login-class 149Sets the default login class for new users. 150See 151.Xr login.conf 5 152for more information on user login classes. 153.It Xo 154.Fl r Ar low Ns Li .. Ns Ar high 155.Xc 156Sets the low and high bounds of UID ranges for new users. 157A new user can only be created if there are UIDs which can be assigned 158from one of the free ranges. 159.It Fl s Ar shell 160Sets the default login shell for new users. 161.El 162.Pp 163In the second form of the command, 164after setting any defaults, and then reading values from 165.Pa /etc/usermgmt.conf , 166the following command line options are processed: 167.Bl -tag -width Ds 168.It Fl b Ar base-directory 169Sets the base directory name, in which the user's new home 170directory will be created, should the 171.Fl m 172option be specified. 173.It Fl c Ar comment 174Sets the comment field (also, for historical reasons known as the 175GECOS field) which will be added for the user, and typically will include 176the user's full name, and, perhaps, contact information for the user. 177.It Fl d Ar home-directory 178Sets the home directory which will be created and populated for the user, 179should the 180.Fl m 181option be specified. 182.It Fl e Ar expiry-time 183Sets the time at which the user account will expire. 184It should be entered in the form 185.Dq month day year , 186where month is the month name (the first three characters are 187sufficient), day is the day of the month, and year is the year. 188Time in seconds since the Epoch (UTC) is also valid. 189A value of 0 can be used to disable this feature. 190See 191.Xr passwd 5 192for more details. 193.It Fl f Ar inactive-time 194Sets the time at which the current password will expire. 195Also see the 196.Fl e 197option above. 198.It Fl G Ar secondary-group[,group,...] 199Sets the secondary groups to which the user will be added in the 200.Pa /etc/group 201file. 202.It Fl g Ar gid | name | Li =uid 203Gives the group name or identifier to be used for the new user's primary group. 204If this is 205.Ql =uid , 206then a UID and GID will be picked which are both unique 207and the same, and a line added to 208.Pa /etc/group 209to describe the new group. 210.It Fl k Ar skel-directory 211Gives the skeleton directory in which to find files 212with which to populate the new user's home directory. 213.It Fl L Ar login-class 214This option sets the login class for the user being created. 215See 216.Xr login.conf 5 217for more information on user login classes. 218.It Fl m 219Create a new home directory for the new user. 220.It Fl o 221Allow the new user to have a UID which is already in use for another user. 222.It Fl p Ar password 223Specifies an already-encrypted password for the new user. 224This password can then be changed by using the 225.Xr chpass 1 226utility. 227If this option is not specified, and no default exists in 228.Pa /etc/usermgmt.conf , 229the account will be disabled by default. 230.It Fl s Ar shell 231Specifies the login shell for the new user. 232.It Fl u Ar uid 233Specifies a UID for the new user. 234Boundaries for this value can be preset for all users 235by using the 236.Ar range 237field in the 238.Pa /etc/usermgmt.conf 239file. 240.It Fl v 241Enables verbose mode - explain the commands as they are executed. 242.El 243.Pp 244Once the information has been verified, 245.Nm 246uses 247.Xr pwd_mkdb 8 248to update the user database. 249This is run in the background, and, 250at very large sites could take several minutes. 251Until this update is completed, the password file is unavailable for other 252updates and the new information is not available to programs. 253.Pp 254.Ex -std useradd 255.Sh FILES 256.Bl -tag -width /etc/usermgmt.conf -compact 257.It Pa /etc/usermgmt.conf 258.It Pa /etc/skel/* 259.It Pa /etc/login.conf 260.El 261.Sh SEE ALSO 262.Xr chpass 1 , 263.Xr group 5 , 264.Xr login.conf 5 , 265.Xr passwd 5 , 266.Xr usermgmt.conf 5 , 267.Xr pwd_mkdb 8 , 268.Xr user 8 , 269.Xr userdel 8 , 270.Xr usermod 8 271.Sh STANDARDS 272Other implementations of the 273.Nm useradd 274utility use the 275.Ar inactive-time 276parameter to refer to the maximum number of days allowed between logins (this 277is used to lock "stale" accounts that have not been used for a period of time). 278However, on 279.Ox 280systems this parameter refers instead to the password change time. 281This is due to differences in the 282.Xr passwd 5 283database compared to other operating systems. 284.Sh HISTORY 285The 286.Nm 287utility first appeared in 288.Ox 2.7 . 289.Sh AUTHORS 290The 291.Nm 292utility was written by 293.An Alistair G. Crooks Aq agc@NetBSD.org . 294