1.\" $NetBSD: useradd.8,v 1.30 2005/02/05 15:28:46 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 January 14, 2004 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.Op Fl k Ar skel-dir 50.Oo 51.Fl r Ar lowuid Ns Li .. Ns Ar highuid 52.Oc 53.Op Fl s Ar shell 54.Nm 55.Op Fl Smov 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 lowuid Ns Li .. Ns Ar highuid 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 (using 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. 115See 116.Xr usermgmt.conf 5 117for more information. 118.It Fl b Ar base-dir 119sets the default base directory. 120This is the directory to which the 121user directory is added, which will be created if the 122.Fl m 123option is specified and no 124.Fl d 125option is specified. 126.It Fl e Ar expiry-time 127sets the default time at which the current password will expire for new 128users. 129It should be entered in the form 130.Dq month day year , 131where month is the month name (the first three characters are 132sufficient), day is the day of the month, and year is the year. 133Time in seconds since the epoch (UTC) is also valid. 134A value of 0 can be used to disable this feature. 135.It Fl f Ar inactive-time 136sets the default time at which new user accounts will expire. 137Also see the 138.Fl e 139option above. 140.It Fl g Ar gid | groupname | Li =uid 141sets the default group for new users. 142.It Fl k Ar skel-dir 143sets the skeleton directory in which to find files with 144which to populate new users' home directories. 145.It Fl L Ar login-class 146sets the default login class for new users. 147See 148.Xr login.conf 5 149for more information on user login classes. 150.It Xo 151.Fl r Ar lowuid Ns Li .. Ns Ar highuid 152.Xc 153sets the low and high bounds of uid ranges for new users. 154A new user can only be created if there are uids which can be 155assigned from one of the free ranges. 156.It Fl s Ar shell 157sets the default login shell for new users. 158.El 159.Pp 160In the second form of the command, 161after setting any defaults, and then reading values from 162.Pa /etc/usermgmt.conf , 163the following command line options are processed: 164.Bl -tag -width Ds 165.It Fl G Ar secondary-group 166is the secondary group to which the user will be added in the 167.Pa /etc/group 168file. 169.It Fl S 170allows samba user names with a trailing dollar sign to be 171added to the system. 172.It Fl b Ar base-directory 173is the base directory name, in which the user's new home 174directory will be created, should the 175.Fl m 176option be specified. 177.It Fl c Ar comment 178is the comment field (also, for historical reasons known as the 179GECOS field) which will be added for the user, and typically will include 180the user's full name, and, perhaps, contact information for the user. 181.It Fl d Ar home-directory 182is the home directory which will be created and populated for the user, 183should the 184.Fl m 185option be specified. 186.It Fl e Ar expiry-time 187sets the time at which the current password will expire for new 188users. 189It should be entered in the form 190.Dq month day year , 191where month is the month name (the first three characters are 192sufficient), day is the day of the month, and year is the year. 193Time in seconds since the epoch (UTC) is also valid. 194A value of 0 can be used to disable this feature. 195See 196.Xr passwd 5 197for more details. 198.It Fl f Ar inactive-time 199sets the time at which new user accounts will expire. 200Also see the 201.Fl e 202option above. 203.It Fl g Ar gid | name | Li =uid 204gives 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 212gives 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 215This option sets the login class for the user being created. 216See 217.Xr login.conf 5 218for more information on user login classes. 219.It Fl m 220create a new home directory for the new user. 221.It Fl o 222allow the new user to have a uid which is already in use for another user. 223.It Fl p Ar password 224specifies an already-encrypted password for the new user. 225This password can then be changed by using the 226.Xr chpass 1 227utility. 228.It Fl s Ar shell 229specifies the login shell for the new user. 230.It Fl u Ar uid 231specifies a uid for the new user. 232Boundaries for this value can be preset for all users 233by using the 234.Ar range 235field in the 236.Pa /etc/usermgmt.conf 237file. 238.It Fl v 239enables verbose mode - explain the commands as they are executed. 240.El 241.Pp 242Once the information has been verified, 243.Nm 244uses 245.Xr pwd_mkdb 8 246to update the user database. 247This is run in the background, and, 248at very large sites could take several minutes. 249Until this update 250is completed, the password file is unavailable for other updates 251and the new information is not available to programs. 252.Pp 253The 254.Nm 255utility exits 0 on success, and \*[Gt]0 if an error occurs. 256.Sh FILES 257.Bl -tag -width /etc/usermgmt.conf -compact 258.It Pa /etc/usermgmt.conf 259.It Pa /etc/skel/* 260.It Pa /etc/login.conf 261.El 262.Sh SEE ALSO 263.Xr chpass 1 , 264.Xr group 5 , 265.Xr login.conf 5 , 266.Xr passwd 5 , 267.Xr usermgmt.conf 5 , 268.Xr pwd_mkdb 8 , 269.Xr user 8 , 270.Xr userdel 8 , 271.Xr usermod 8 272.Sh HISTORY 273The 274.Nm 275utility first appeared in 276.Nx 1.5 . 277It is based on the 278.Ar addnerd 279package by the same author. 280.Sh AUTHORS 281The 282.Nm 283utility was written by 284.An Alistair G. Crooks 285.Aq agc@NetBSD.org . 286