1.\" $NetBSD: useradd.8,v 1.41 2006/12/06 21:49:17 rillig 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. The name of the author may not be used to endorse or promote 15.\" products derived from this software without specific prior written 16.\" permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 19.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 20.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 22.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 24.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 26.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 27.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 28.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" 31.Dd October 7, 2006 32.Dt USERADD 8 33.Os 34.Sh NAME 35.Nm useradd 36.Nd add a user to the system 37.Sh SYNOPSIS 38.Nm 39.Fl D 40.Op Fl F 41.Op Fl b Ar base-dir 42.Op Fl e Ar expiry-time 43.Op Fl f Ar inactive-time 44.Op Fl g Ar gid | name | Li =uid 45.Op Fl k Ar skel-dir 46.Op Fl L Ar login-class 47.Op Fl M Ar home-perm 48.Op Fl r Ar lowuid Ns Li .. Ns Ar highuid 49.Op Fl s Ar shell 50.Nm 51.Op Fl moSv 52.Op Fl b Ar base-dir 53.Op Fl c Ar comment 54.Op Fl d Ar home-dir 55.Op Fl e Ar expiry-time 56.Op Fl f Ar inactive-time 57.Op Fl G Ar secondary-group 58.Op Fl g Ar gid | name | Li =uid 59.Op Fl k Ar skel-dir 60.Op Fl L Ar login-class 61.Op Fl M Ar home-perm 62.Op Fl p Ar password 63.Op Fl r Ar lowuid Ns Li .. Ns Ar highuid 64.Op Fl s Ar shell 65.Op Fl u Ar uid 66.Ar user 67.Sh DESCRIPTION 68The 69.Nm useradd 70utility adds a user to the system, creating and 71populating a home directory if necessary. 72Any skeleton files will be provided 73for the new user if they exist in the 74.Ar skel-dir 75directory (see the 76.Fl k 77option). 78Default values for 79the base directory, 80the time of password expiry, 81the time of account expiry, 82primary group, 83the skeleton directory, 84the range from which the uid will be allocated, 85and default login shell 86can be provided in the 87.Pa /etc/usermgmt.conf 88file, which, if running as root, is created using the built-in defaults if 89it does not exist. 90.Pp 91The first form of the command shown above (using the 92.Fl D 93option) 94sets and displays the defaults for the 95.Nm 96utility. 97.Pp 98See 99.Xr user 8 100for more information about 101.Dv EXTENSIONS . 102.Bl -tag -width Ds 103.It Fl b Ar base-dir 104Set the default base directory. 105This is the directory to which the 106user directory is added, which will be created if the 107.Fl m 108option is specified and no 109.Fl d 110option is specified. 111.It Fl D 112without any further options, 113.Fl D 114will show the current defaults which 115will be used by the 116.Nm 117utility. 118Together with one of the options shown for the first version 119of the command, 120.Fl D 121will set the default to be the new value. 122See 123.Xr usermgmt.conf 5 124for more information. 125.It Fl e Ar expiry-time 126Set the time at which the new user accounts will expire. 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. 131Time in seconds since the epoch (UTC) is also valid. 132A value of 0 can be used to disable this feature. 133.It Fl F 134Force the user to change their password upon next login. 135.It Fl f Ar inactive-time 136Set the time at which passwords for the new user accounts will 137expire. 138Also see the 139.Fl e 140option above. 141.It Fl g Ar gid | groupname | Li =uid 142Set the default group for new users. 143.It Fl k Ar skel-dir 144Set the skeleton directory in which to find files with 145which to populate new users' home directories. 146.It Fl L Ar login-class 147Set the default login class for new users. 148See 149.Xr login.conf 5 150for more information on user login classes. 151This option is included if built with 152.Dv EXTENSIONS . 153.It Fl M Ar home-perm 154sets the default permissions of the newly created home directory if 155.Fl m 156is given. 157The permission is specified as an octal number, with or without a leading zero. 158.It Fl r Ar lowuid Ns Li .. Ns Ar highuid 159Set the low and high bounds of uid ranges for new users. 160A new user can only be created if there are uids which can be 161assigned from one of the free ranges. 162This option is included if built with 163.Dv EXTENSIONS . 164.It Fl s Ar shell 165Set the default login shell for new users. 166.El 167.Pp 168In the second form of the command, 169after setting any defaults, and then reading values from 170.Pa /etc/usermgmt.conf , 171the following command line options are processed: 172.Bl -tag -width Ds 173.It Fl b Ar base-directory 174Set 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 179Set the comment field (also, for historical reasons known as the 180GECOS field) which will be added for the user, and typically will include 181the user's full name, and, perhaps, contact information for the user. 182.It Fl d Ar home-directory 183Set the home directory which will be created and populated for the user, 184should the 185.Fl m 186option be specified. 187.It Fl e Ar expiry-time 188Set the time at which the current password will expire for new 189users. 190It should be entered in the form 191.Dq month day year , 192where month is the month name (the first three characters are 193sufficient), day is the day of the month, and year is the year. 194Time in seconds since the epoch (UTC) is also valid. 195A value of 0 can be used to disable this feature. 196See 197.Xr passwd 5 198for more details. 199.It Fl f Ar inactive-time 200Set the time at which new user accounts will expire. 201Also see the 202.Fl e 203option above. 204.It Fl G Ar secondary-group 205Add the user to the secondary group 206.Ar secondary-group 207in the 208.Pa /etc/group 209file. 210.It Fl g Ar gid | name | Li =uid 211Give the group name or identifier to be used for the new user's primary group. 212If this is 213.Ql =uid , 214then a uid and gid will be picked which are both unique 215and the same, and a line added to 216.Pa /etc/group 217to describe the new group. 218.It Fl k Ar skeleton directory 219Give the skeleton directory in which to find files 220with which to populate the new user's home directory. 221.It Fl L Ar login-class 222Set the login class for the user being created. 223See 224.Xr login.conf 5 225for more information on user login classes. 226This option is included if built with 227.Dv EXTENSIONS . 228.It Fl M Ar home-perm 229sets the permissions of the newly created home directory if 230.Fl m 231is given. 232The permission is specified as an octal number, with or without a leading zero. 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 238Specify an already-encrypted password for the new user. 239Encrypted passwords can be generated with 240.Xr pwhash 1 . 241The password can be changed later by using 242.Xr chpass 1 243or 244.Xr passwd 1 . 245This option is included if built with 246.Dv EXTENSIONS . 247.It Fl S 248Allow samba user names with a trailing dollar sign to be 249added to the system. 250This option is included if built with 251.Dv EXTENSIONS . 252.It Fl s Ar shell 253Specify the login shell for the new user. 254.It Fl u Ar uid 255Specify a uid for the new user. 256Boundaries for this value can be preset for all users 257by using the 258.Ar range 259field in the 260.Pa /etc/usermgmt.conf 261file. 262.It Fl v 263Enable verbose mode - explain the commands as they are executed. 264This option is included if built with 265.Dv EXTENSIONS . 266.El 267.Pp 268Once the information has been verified, 269.Nm 270uses 271.Xr pwd_mkdb 8 272to update the user database. 273This is run in the background, and, 274at very large sites could take several minutes. 275Until this update 276is completed, the password file is unavailable for other updates 277and the new information is not available to programs. 278.Sh EXIT STATUS 279.Ex -std useradd 280.Sh FILES 281.Bl -tag -width /etc/usermgmt.conf -compact 282.It Pa /etc/usermgmt.conf 283.It Pa /etc/skel/* 284.It Pa /etc/login.conf 285.El 286.Sh SEE ALSO 287.Xr chpass 1 , 288.Xr passwd 1 , 289.Xr pwhash 1 , 290.Xr group 5 , 291.Xr login.conf 5 , 292.Xr passwd 5 , 293.Xr usermgmt.conf 5 , 294.Xr pwd_mkdb 8 , 295.Xr user 8 , 296.Xr userdel 8 , 297.Xr usermod 8 298.Sh HISTORY 299The 300.Nm 301utility first appeared in 302.Nx 1.5 . 303It is based on the 304.Ar addnerd 305package by the same author. 306.Sh AUTHORS 307The 308.Nm 309utility was written by 310.An Alistair G. Crooks 311.Aq agc@NetBSD.org . 312.Pp 313Support for setting permissions of home directories was added by Hubert Feyrer. 314