1.\" $NetBSD: useradd.8,v 1.43 2014/09/19 16:02:59 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. 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 January 13, 2009 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. 210The 211.Ar secondary-group 212may be a comma-delimited list for multiple groups. 213Or the option may be repeated for multiple groups. 214(16 groups maximum.) 215.It Fl g Ar gid | name | Li =uid 216Give the group name or identifier to be used for the new user's primary group. 217If this is 218.Ql =uid , 219then a uid and gid will be picked which are both unique 220and the same, and a line added to 221.Pa /etc/group 222to describe the new group. 223.It Fl k Ar skeleton directory 224Give the skeleton directory in which to find files 225with which to populate the new user's home directory. 226.It Fl L Ar login-class 227Set the login class for the user being created. 228See 229.Xr login.conf 5 230for more information on user login classes. 231This option is included if built with 232.Dv EXTENSIONS . 233.It Fl M Ar home-perm 234sets the permissions of the newly created home directory if 235.Fl m 236is given. 237The permission is specified as an octal number, with or without a leading zero. 238.It Fl m 239Create a new home directory for the new user. 240.It Fl o 241Allow the new user to have a uid which is already in use for another user. 242.It Fl p Ar password 243Specify an already-encrypted password for the new user. 244Encrypted passwords can be generated with 245.Xr pwhash 1 . 246The password can be changed later by using 247.Xr chpass 1 248or 249.Xr passwd 1 . 250This option is included if built with 251.Dv EXTENSIONS . 252.It Fl S 253Allow samba user names with a trailing dollar sign to be 254added to the system. 255This option is included if built with 256.Dv EXTENSIONS . 257.It Fl s Ar shell 258Specify the login shell for the new user. 259.It Fl u Ar uid 260Specify a uid for the new user. 261Boundaries for this value can be preset for all users 262by using the 263.Ar range 264field in the 265.Pa /etc/usermgmt.conf 266file. 267.It Fl v 268Enable verbose mode - explain the commands as they are executed. 269This option is included if built with 270.Dv EXTENSIONS . 271.El 272.Pp 273Once the information has been verified, 274.Nm 275uses 276.Xr pwd_mkdb 8 277to update the user database. 278This is run in the background, and, 279at very large sites could take several minutes. 280Until this update 281is completed, the password file is unavailable for other updates 282and the new information is not available to programs. 283.Sh FILES 284.Bl -tag -width /etc/usermgmt.conf -compact 285.It Pa /etc/usermgmt.conf 286.It Pa /etc/skel/* 287.It Pa /etc/login.conf 288.El 289.Sh EXIT STATUS 290.Ex -std useradd 291.Sh SEE ALSO 292.Xr chpass 1 , 293.Xr passwd 1 , 294.Xr pwhash 1 , 295.Xr group 5 , 296.Xr login.conf 5 , 297.Xr passwd 5 , 298.Xr usermgmt.conf 5 , 299.Xr pwd_mkdb 8 , 300.Xr user 8 , 301.Xr userdel 8 , 302.Xr usermod 8 303.Sh HISTORY 304The 305.Nm 306utility first appeared in 307.Nx 1.5 . 308It is based on the 309.Ar addnerd 310package by the same author. 311.Sh AUTHORS 312The 313.Nm 314utility was written by 315.An Alistair G. Crooks 316.Aq agc@NetBSD.org . 317.Pp 318Support for setting permissions of home directories was added by Hubert Feyrer. 319