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