1.\" $NetBSD: useradd.8,v 1.22 2002/10/02 17:30:08 wiz Exp $ */ 2.\" 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 "" 42.Fl D 43.Op Fl b Ar base-dir 44.Op Fl e Ar expiry-time 45.Op Fl f Ar inactive-time 46.Oo 47.Fl g Ar gid | name | Li =uid Oc 48.Op Fl L Ar login-class 49.Oo 50.Op Fl k Ar skel-dir 51.Fl r Ar low Ns Li .. Ns Ar high 52.Oc 53.Op Fl s Ar shell 54.Nm "" 55.Op Fl mov 56.Op Fl G Ar secondary-group 57.Op Fl b Ar base-dir 58.Op Fl c Ar comment 59.Op Fl d Ar home-dir 60.Op Fl e Ar expiry-time 61.Op Fl f Ar inactive-time 62.Oo 63.Fl g Ar gid | name | Li =uid Oc 64.Op Fl k Ar skel-dir 65.Op Fl L Ar login-class 66.Op Fl p Ar password 67.Oo 68.Fl r Ar low Ns Li .. Ns Ar high 69.Oc 70.Op Fl s Ar shell 71.Op Fl u Ar uid 72.Ar user 73.Sh DESCRIPTION 74The 75.Nm useradd 76utility adds a user to the system, creating and 77populating a home directory if necessary. 78Any skeleton files will be provided 79for the new user if they exist in the 80.Ar skel-dir 81directory (see the 82.Fl k 83option). 84Default values for 85the base directory, 86the time of password expiry, 87the time of account expiry, 88primary group, 89the skeleton directory, 90the range from which the uid will be allocated, 91and default login shell 92can be provided in the 93.Pa /etc/usermgmt.conf 94file, which, if running as root, is created using the built-in defaults if 95it does not exist. 96.Pp 97The first form of the command shown above (utilising the 98.Fl D 99option) 100sets and displays the defaults for the 101.Nm 102utility. 103.Bl -tag -width Ds 104.It Fl D 105without any further options, 106.Fl D 107will show the current defaults which 108will be used by the 109.Nm 110utility. 111Together with one of the options shown for the first version 112of the command, 113.Fl D 114will set the default to be the new value. See 115.Xr usermgmt.conf 5 116for more information. 117.It Fl b Ar base-dir 118sets the default base directory. This is the directory to which the 119user directory is added, which will be created if the 120.Fl m 121option is specified and no 122.Fl d 123option is specified. 124.It Fl e Ar expiry-time 125sets the default time at which the current password will expire for new 126users. 127It should be entered in the form 128.Dq month day year , 129where month is the month name (the first three characters are 130sufficient), day is the day of the month, and year is the year. Time 131in seconds since the epoch (UTC) is also valid. 132A value of 0 can be used to disable this feature. 133.It Fl f Ar inactive-time 134sets the default time at which new user accounts will expire. 135Also see the 136.Fl e 137option above. 138.It Fl g Ar gid | groupname | Li =uid 139sets the default group for new users. 140.It Fl k Ar skel-dir 141sets the skeleton directory in which to find files with 142which to populate new users' home directories. 143.It Fl L Ar login-class 144sets the default login class for new users. 145See 146.Xr login.conf 5 147for more information on user login classes. 148.It Xo 149.Fl r Ar low Ns Li .. Ns Ar high 150.Xc 151sets the low and high bounds of uid ranges for new users. A new user 152can only be created if there are uids which can be assigned from one 153of the free ranges. 154.It Fl s Ar shell 155sets the default login shell for new users. 156.El 157.Pp 158In the second form of the command, 159after setting any defaults, and then reading values from 160.Pa /etc/usermgmt.conf , 161the following command line options are processed: 162.Bl -tag -width Ds 163.It Fl G Ar secondary-group 164is the secondary group to which the user will be added in the 165.Pa /etc/group 166file. 167.It Fl b Ar base-directory 168is the base directory name, in which the user's new home 169directory will be created, should the 170.Fl m 171option be specified. 172.It Fl c Ar comment 173is the comment field (also, for historical reasons known as the 174GECOS field) which will be added for the user, and typically will include 175the username, and, perhaps, contact information for the user. 176.It Fl d Ar home-directory 177is the home directory which will be created and populated for the user, 178should the 179.Fl m 180option be specified. 181.It Fl e Ar expiry-time 182sets the time at which the current password will expire for new 183users. 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. Time 188in 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 new user accounts will expire. 195Also see the 196.Fl e 197option above. 198.It Fl g Ar gid | name | Li =uid 199gives the group name or identifier to be used for the new user's primary group. 200If this is 201.Ql =uid , 202then a uid and gid will be picked which are both unique 203and the same, and a line added to 204.Pa /etc/group 205to describe the new group. 206.It Fl k Ar skeleton directory 207gives the skeleton directory in which to find files 208with which to populate the new user's home directory. 209.It Fl L Ar login-class 210This option sets the login class for the user being created. See 211.Xr login.conf 5 212for more information on user login classes. 213.It Fl m 214create a new home directory for the new user. 215.It Fl o 216allow the new user to have a uid which is already in use for another user. 217.It Fl p Ar password 218specifies an already-encrypted password for the new user. 219This password can then be changed by using the 220.Xr chpass 1 221utility. 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. This is run in the background, and, 241at very large sites could take several minutes. Until this update 242is completed, the password file is unavailable for other updates 243and the new information is not available to programs. 244.Pp 245The 246.Nm 247utility exits 0 on success, and \*[Gt]0 if an error occurs. 248.Sh FILES 249.Bl -tag -width /etc/usermgmt.conf -compact 250.It Pa /etc/usermgmt.conf 251.It Pa /etc/skel/* 252.It Pa /etc/login.conf 253.El 254.Sh SEE ALSO 255.Xr chpass 1 , 256.Xr group 5 , 257.Xr login.conf 5 , 258.Xr passwd 5 , 259.Xr usermgmt.conf 5 , 260.Xr pwd_mkdb 8 , 261.Xr user 8 , 262.Xr userdel 8 , 263.Xr usermod 8 264.Sh HISTORY 265The 266.Nm 267utility first appeared in 268.Nx 1.5 . 269It is based on the 270.Ar addnerd 271package by the same author. 272.Sh AUTHORS 273The 274.Nm 275utility was written by Alistair G. Crooks (agc@netbsd.org). 276