1.\" $NetBSD: useradd.8,v 1.38 2005/11/25 08:00:18 agc 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 November 16, 2005 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 r Ar lowuid Ns Li .. Ns Ar highuid 48.Op Fl s Ar shell 49.Nm 50.Op Fl moSv 51.Op Fl b Ar base-dir 52.Op Fl c Ar comment 53.Op Fl d Ar home-dir 54.Op Fl e Ar expiry-time 55.Op Fl f Ar inactive-time 56.Op Fl G Ar secondary-group 57.Op Fl g Ar gid | name | Li =uid 58.Op Fl k Ar skel-dir 59.Op Fl L Ar login-class 60.Op Fl p Ar password 61.Op Fl r Ar lowuid Ns Li .. Ns Ar highuid 62.Op Fl s Ar shell 63.Op Fl u Ar uid 64.Ar user 65.Sh DESCRIPTION 66The 67.Nm useradd 68utility adds a user to the system, creating and 69populating a home directory if necessary. 70Any skeleton files will be provided 71for the new user if they exist in the 72.Ar skel-dir 73directory (see the 74.Fl k 75option). 76Default values for 77the base directory, 78the time of password expiry, 79the time of account expiry, 80primary group, 81the skeleton directory, 82the range from which the uid will be allocated, 83and default login shell 84can be provided in the 85.Pa /etc/usermgmt.conf 86file, which, if running as root, is created using the built-in defaults if 87it does not exist. 88.Pp 89The first form of the command shown above (using the 90.Fl D 91option) 92sets and displays the defaults for the 93.Nm 94utility. 95.Pp 96See 97.Xr user 8 98for more information about 99.Dv EXTENSIONS . 100.Bl -tag -width Ds 101.It Fl b Ar base-dir 102Set the default base directory. 103This is the directory to which the 104user directory is added, which will be created if the 105.Fl m 106option is specified and no 107.Fl d 108option is specified. 109.It Fl D 110without any further options, 111.Fl D 112will show the current defaults which 113will be used by the 114.Nm 115utility. 116Together with one of the options shown for the first version 117of the command, 118.Fl D 119will set the default to be the new value. 120See 121.Xr usermgmt.conf 5 122for more information. 123.It Fl e Ar expiry-time 124Set the time at which the new user accounts will expire. 125It should be entered in the form 126.Dq month day year , 127where month is the month name (the first three characters are 128sufficient), day is the day of the month, and year is the year. 129Time in seconds since the epoch (UTC) is also valid. 130A value of 0 can be used to disable this feature. 131.It Fl F 132Force the user to change their password upon next login. 133.It Fl f Ar inactive-time 134Set the time at which passwords for the new user accounts will 135expire. 136Also see the 137.Fl e 138option above. 139.It Fl g Ar gid | groupname | Li =uid 140Set the default group for new users. 141.It Fl k Ar skel-dir 142Set the skeleton directory in which to find files with 143which to populate new users' home directories. 144.It Fl L Ar login-class 145Set the default login class for new users. 146See 147.Xr login.conf 5 148for more information on user login classes. 149This option is included if built with 150.Dv EXTENSIONS . 151.It Fl r Ar lowuid Ns Li .. Ns Ar highuid 152Set the low and high bounds of uid ranges for new users. 153A new user can only be created if there are uids which can be 154assigned from one of the free ranges. 155This option is included if built with 156.Dv EXTENSIONS . 157.It Fl s Ar shell 158Set the default login shell for new users. 159.El 160.Pp 161In the second form of the command, 162after setting any defaults, and then reading values from 163.Pa /etc/usermgmt.conf , 164the following command line options are processed: 165.Bl -tag -width Ds 166.It Fl b Ar base-directory 167Set the base directory name, in which the user's new home 168directory will be created, should the 169.Fl m 170option be specified. 171.It Fl c Ar comment 172Set the comment field (also, for historical reasons known as the 173GECOS field) which will be added for the user, and typically will include 174the user's full name, and, perhaps, contact information for the user. 175.It Fl d Ar home-directory 176Set the home directory which will be created and populated for the user, 177should the 178.Fl m 179option be specified. 180.It Fl e Ar expiry-time 181Set the time at which the current password will expire for new 182users. 183It should be entered in the form 184.Dq month day year , 185where month is the month name (the first three characters are 186sufficient), day is the day of the month, and year is the year. 187Time in seconds since the epoch (UTC) is also valid. 188A value of 0 can be used to disable this feature. 189See 190.Xr passwd 5 191for more details. 192.It Fl f Ar inactive-time 193Set the time at which new user accounts will expire. 194Also see the 195.Fl e 196option above. 197.It Fl G Ar secondary-group 198Add the user to the secondary group 199.Ar secondary-group 200in the 201.Pa /etc/group 202file. 203.It Fl g Ar gid | name | Li =uid 204Give the group name or identifier to be used for the new user's primary group. 205If this is 206.Ql =uid , 207then a uid and gid will be picked which are both unique 208and the same, and a line added to 209.Pa /etc/group 210to describe the new group. 211.It Fl k Ar skeleton directory 212Give the skeleton directory in which to find files 213with which to populate the new user's home directory. 214.It Fl L Ar login-class 215Set the login class for the user being created. 216See 217.Xr login.conf 5 218for more information on user login classes. 219This option is included if built with 220.Dv EXTENSIONS . 221.It Fl m 222Create a new home directory for the new user. 223.It Fl o 224Allow the new user to have a uid which is already in use for another user. 225.It Fl p Ar password 226Specify an already-encrypted password for the new user. 227Encrypted passwords can be generated with 228.Xr pwhash 1 . 229The password can be changed later by using 230.Xr chpass 1 231or 232.Xr passwd 1 . 233This option is included if built with 234.Dv EXTENSIONS . 235.It Fl S 236Allow samba user names with a trailing dollar sign to be 237added to the system. 238This option is included if built with 239.Dv EXTENSIONS . 240.It Fl s Ar shell 241Specify the login shell for the new user. 242.It Fl u Ar uid 243Specify a uid for the new user. 244Boundaries for this value can be preset for all users 245by using the 246.Ar range 247field in the 248.Pa /etc/usermgmt.conf 249file. 250.It Fl v 251Enable verbose mode - explain the commands as they are executed. 252This option is included if built with 253.Dv EXTENSIONS . 254.El 255.Pp 256Once the information has been verified, 257.Nm 258uses 259.Xr pwd_mkdb 8 260to update the user database. 261This is run in the background, and, 262at very large sites could take several minutes. 263Until this update 264is completed, the password file is unavailable for other updates 265and the new information is not available to programs. 266.Sh EXIT STATUS 267.Ex -std useradd 268.Sh FILES 269.Bl -tag -width /etc/usermgmt.conf -compact 270.It Pa /etc/usermgmt.conf 271.It Pa /etc/skel/* 272.It Pa /etc/login.conf 273.El 274.Sh SEE ALSO 275.Xr chpass 1 , 276.Xr pwhash 1 , 277.Xr group 5 , 278.Xr login.conf 5 , 279.Xr passwd 5 , 280.Xr usermgmt.conf 5 , 281.Xr pwd_mkdb 8 , 282.Xr user 8 , 283.Xr userdel 8 , 284.Xr usermod 8 285.Sh HISTORY 286The 287.Nm 288utility first appeared in 289.Nx 1.5 . 290It is based on the 291.Ar addnerd 292package by the same author. 293.Sh AUTHORS 294The 295.Nm 296utility was written by 297.An Alistair G. Crooks 298.Aq agc@NetBSD.org . 299