1.\" $OpenBSD: useradd.8,v 1.17 2003/06/15 06:40:15 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 September 5, 2001 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-dir 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 L Ar login-class 50.Op Fl k Ar skel-dir 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 G Ar secondary-group[,group,...] 60.Op Fl b Ar base-dir 61.Op Fl c Ar comment 62.Op Fl d Ar home-dir 63.Op Fl e Ar expiry-time 64.Op Fl f Ar inactive-time 65.Oo 66.Fl g Ar gid | name | Li =uid Oc 67.Op Fl k Ar skel-dir 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-dir 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 D 109without any further options, 110.Fl D 111will show the current defaults which 112will be used by the 113.Nm 114utility. 115Together with one of the options shown for the first version 116of the command, 117.Fl D 118will set the default to be the new value. 119See 120.Xr usermgmt.conf 5 121for more information. 122.It Fl b Ar base-dir 123sets the base directory. 124This is the directory to which the user directory is added, 125which will be created if the 126.Fl m 127option is specified and no 128.Fl d 129option is specified. 130.It Fl e Ar expiry-time 131sets the default time at which the current password will expire for new 132users. 133It should be entered in the form 134.Dq month day year , 135where month is the month name (the first three characters are 136sufficient), day is the day of the month, and year is the year. 137Time in seconds since the epoch (UTC) is also valid. 138A value of 0 can be used to disable this feature. 139.It Fl f Ar inactive-time 140sets the default time at which new user accounts will expire. 141Also see the 142.Fl e 143option above. 144.It Fl g Ar gid | groupname | Li =uid 145sets the default group for new users. 146.It Fl k Ar skel-dir 147sets the skeleton directory in which to find files with 148which to populate new users' home directories. 149.It Fl L Ar login-class 150sets the default login class for new users. 151See 152.Xr login.conf 5 153for more information on user login classes. 154.It Xo 155.Fl r Ar low Ns Li .. Ns Ar high 156.Xc 157sets the low and high bounds of UID ranges for new users. 158A new user can only be created if there are UIDs which can be assigned 159from one of the free ranges. 160.It Fl s Ar shell 161sets the default login shell for new users. 162.El 163.Pp 164In the second form of the command, 165after setting any defaults, and then reading values from 166.Pa /etc/usermgmt.conf , 167the following command line options are processed: 168.Bl -tag -width Ds 169.It Fl G Ar secondary-group[,group,...] 170are the secondary groups to which the user will be added in the 171.Pa /etc/group 172file. 173.It Fl b Ar base-directory 174is the base directory name, in which the user's new home 175directory will be created, should the 176.Fl m 177option be specified. 178.It Fl c Ar comment 179is the comment field (also, for historical reasons known as the 180GECOS field) which will be added for the user, and typically will include 181the username, and, perhaps, contact information for the user. 182.It Fl d Ar home-directory 183is the home directory which will be created and populated for the user, 184should the -m option be specified. 185.It Fl e Ar expiry-time 186sets the time at which the current password will expire for new 187users. 188It should be entered in the form 189.Dq month day year , 190where month is the month name (the first three characters are 191sufficient), day is the day of the month, and year is the year. 192Time in seconds since the epoch (UTC) is also valid. 193A value of 0 can be used to disable this feature. 194See 195.Xr passwd 5 196for more details. 197.It Fl f Ar inactive-time 198sets the time at which new user accounts will expire. 199Also see the 200.Fl e 201option above. 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 skeleton 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 254The 255.Nm 256utility exits 0 on success, and \*(Gt0 if an error occurs. 257.Sh FILES 258.Bl -tag -width /etc/usermgmt.conf -compact 259.It Pa /etc/usermgmt.conf 260.It Pa /etc/skel/* 261.It Pa /etc/login.conf 262.El 263.Sh SEE ALSO 264.Xr chpass 1 , 265.Xr group 5 , 266.Xr login.conf 5 , 267.Xr passwd 5 , 268.Xr usermgmt.conf 5 , 269.Xr pwd_mkdb 8 , 270.Xr user 8 , 271.Xr userdel 8 , 272.Xr usermod 8 273.Sh HISTORY 274The 275.Nm 276utility first appeared in 277.Ox 2.7 . 278.Sh AUTHORS 279The 280.Nm 281utility was written by 282.An Alistair G. Crooks Aq agc@NetBSD.org . 283