1.\" $NetBSD: useradd.8,v 1.16 2002/05/28 04:39:08 grant 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-secs 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-secs 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.Pa /etc/skel 81directory. 82Default values for 83the base directory, 84the time of password expiry, 85seconds until password change, 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. 93.Pp 94The first format of the command shown above (utilising the 95.Fl D 96option) 97sets and displays the defaults for the 98.Nm 99utility. 100.Bl -tag -width Ds 101.It Fl D 102without any further options, 103.Fl D 104will show the current defaults which 105will be used by the 106.Nm 107utility. Together with one of the options shown for the first version 108of the command, 109.Fl D 110will set the default to be the new value. 111.It Fl b Ar base-dir 112sets the base directory. This is the directory to which the user directory 113is added, which will be created if the 114.Fl m 115option is specified and no 116.Fl d 117option is specified. 118.It Fl e Ar expiry-time 119sets the time at which the current password will expire for new users. 120.It Fl f Ar inactive-secs 121sets the number of seconds after which, if no login has occurred for 122the user during that time, the login will be 123.Dq locked . 124.It Fl g Ar gid | groupname | Li =uid 125sets the default group for any user added using the 126.Nm 127command. 128.It Fl k Ar skel-dir 129sets the skeleton directory in which to find files with 130which to populate new users' home directories. 131.It Fl L Ar login-class 132This option sets the login class for the user being created. See 133.Xr login.conf 5 134for more information on user login classes. 135.It Xo 136.Fl r Ar low Ns Li .. Ns Ar high 137.Xc 138sets the low and high bounds of uid ranges for new users. A new user 139can only be created if there are uids which can be assigned from one 140of the free ranges. 141.It Fl s Ar shell 142sets the login shell for new users. 143.El 144.Pp 145In the second form of the command, 146after setting any defaults, and then values from that file, 147the command line options are processed: 148.Bl -tag -width Ds 149.It Fl G Ar secondary-group 150is the secondary group to which the user will be added in the 151.Pa /etc/group 152file. 153.It Fl b Ar base-directory 154is the base directory name, in which the user's new home 155directory will be created, should the -m option be specified. 156This value can be preset for all users 157by using the 158.Ar base_dir 159field in the 160.Pa /etc/usermgmt.conf 161file - it has the format: 162.D1 Ic base_dir Ar path-to-base-dir 163.It Fl c Ar comment 164is the comment field (also, for historical reasons known as the 165GECOS field) which will be added for the user, and typically will include 166the username, and, perhaps, contact information for the user. 167.It Fl d Ar home-directory 168is the home directory which will be created and populated for the user, 169should the -m option be specified. 170.It Fl e Ar secs-to-expiry 171provides the number of seconds since the epoch (UTC) at 172which the current password change expire. This 173can be used to implement password aging. 174A value of 1750 can be used to switch off this feature. 176The default value for this field is 0. 177See 178.Xr passwd 5 179for more details. 180This value can be preset for all users 181by using the 182.Ar expire 183field in the 184.Pa /etc/usermgmt.conf 185file - it has the format: 186.D1 Ic expire Ar secs-to-expiry 187.It Fl g Ar gid | name | Li =uid 188gives the group name or identifier to be used for the new user's primary group. 189If this is 190.Ql =uid , 191then a uid and gid will be picked which are both unique 192and the same, and a line added to 193.Pa /etc/group 194to describe the new group. 195This value can be preset for all users 196by using the 197.Ar gid 198field in the 199.Pa /etc/usermgmt.conf 200file - it has the format: 201.br \" XXX This shouldn't be needed -- mdoc bug? --bjh21 202.Bd -ragged -offset indent -compact 203.Ic group 204.Ar gid | name | Li =uid 205.Ed 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. 209This value can be preset for all users by using the 210.Ar skel_dir 211field in the 212.Pa /etc/usermgmt.conf 213file - it has the format: 214.br \" XXX skip empty line? - HF 215.Bd -ragged -offset indent -compact 216.Ic skel_dir 217.Ar path-to-skeleton-dir 218.Ed 219.It Fl L Ar login-class 220This option sets the login class for the user being created. See 221.Xr login.conf 5 222for more information on user login classes. The value can be preset 223for all users by using the 224.Ar class 225field in the 226.Pa /etc/usermgmt.conf 227file - it has the format: 228.br \" XXX skip empty line? - HF 229.Bd -ragged -offset indent -compact 230.Ic class 231.Ar login-class 232.Ed 233.It Fl m 234create a new home directory for the new user. 235.It Fl o 236allow the new user to have a uid which is already in use for another user. 237.It Fl p Ar password 238specifies an already-encrypted password for the new user. 239This password can then be changed by using the 240.Xr chpass 1 241utility. 242This value can be preset for all users 243by using the 244.Ar password 245field in the 246.Pa /etc/usermgmt.conf 247file - it has the format: 248.D1 Ic password Ar encrypted-password 249.It Fl s Ar shell 250specifies the login shell for the new user. 251This value can be preset for all users 252by using the 253.Ar shell 254field in the 255.Pa /etc/usermgmt.conf 256file - it has the format: 257.D1 Ic shell Ar login-shell 258.It Fl u Ar uid 259specifies a uid for the new user. 260Boundaries for this value can be preset for all users 261by using the 262.Ar range 263field in the 264.Pa /etc/usermgmt.conf 265file - they have the format: 266.Bd -unfilled -offset indent -compact 267.Ic range Ar starting-uid Ns Li .. Ns Ar ending-uid 268.Ed 269.It Fl v 270enables verbose mode - explain the commands as they are executed. 271.El 272.Pp 273Once the information has been verified, 274.Nm 275uses 276.Xr pwd_mkdb 8 277to update the user database. This is run in the background, and, 278at very large sites could take several minutes. Until this update 279is completed, the password file is unavailable for other updates 280and the new information is not available to programs. 281.Pp 282The 283.Nm 284utility exits 0 on success, and \*[Gt]0 if an error occurs. 285.Sh FILES 286.Bl -tag -width /etc/usermgmt.conf -compact 287.It Pa /etc/usermgmt.conf 288.It Pa /etc/skel/* 289.It Pa /etc/login.conf 290.El 291.Sh SEE ALSO 292.Xr chpass 1 , 293.Xr group 5 , 294.Xr login.conf 5 , 295.Xr passwd 5 , 296.Xr pwd_mkdb 8 , 297.Xr user 8 , 298.Xr userdel 8 , 299.Xr usermod 8 300.Sh HISTORY 301The 302.Nm 303utility first appeared in 304.Nx 1.5 . 305It is based on the 306.Ar addnerd 307package by the same author. 308.Sh AUTHORS 309The 310.Nm 311utility was written by Alistair G. Crooks (agc@netbsd.org). 312