1.\" $OpenBSD: useradd.8,v 1.10 2001/08/02 18:37:35 mpech Exp $ */ 2.\" $NetBSD: useradd.8,v 1.5 2000/02/28 05:10:57 enami Exp $ */ 3.\" 4.\" 5.\" Copyright (c) 1999 Alistair G. Crooks. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by Alistair G. Crooks. 18.\" 4. The name of the author may not be used to endorse or promote 19.\" products derived from this software without specific prior written 20.\" permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 23.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 24.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 26.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 28.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 30.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 31.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 32.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33.\" 34.\" 35.Dd November 30, 1999 36.Dt USERADD 8 37.Os 38.Sh NAME 39.Nm useradd 40.Nd add a user to the system 41.Sh SYNOPSIS 42.Nm useradd 43.Op Fl D 44.Op Fl b Ar base-dir 45.Op Fl e Ar expiry-time 46.Op Fl f Ar inactive-secs 47.Op Fl g Ar gid/name/=uid 48.Op Fl r Ar low..high 49.Op Fl s Ar shell 50.Nm useradd 51.Op Fl G Ar secondary-group[,group,...] 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-secs 57.Op Fl g Ar gid/name/=uid 58.Op Fl k Ar skel-dir 59.Op Fl m 60.Op Fl o 61.Op Fl p Ar password 62.Op Fl r Ar low..high 63.Op Fl s Ar shell 64.Op Fl u Ar uid 65.Op Fl v 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 dot files will be provided 73for the new user if they exist in the 74.Pa /etc/skel 75directory. 76Default values for the base directory, the time of password expiry, 77the skeleton directory, 78seconds until password change, primary group, the range from which the uid will be 79allocated, 80and default login shell can be provided in the 81.Pa /etc/usermgmt.conf 82file. 83.Pp 84The first format of the command shown above (utilising the -D option) 85sets and displays the defaults for the 86.Nm 87utility. 88.Bl -tag -width Ds 89.It Fl D 90without any further options, -D will show the current defaults which 91will be used by the 92.Nm 93utility. Together with one of the options shown for the first version 94of the command, -D will set the default to be the new value. 95.It Fl b Ar base-dir 96sets the base directory. This is the directory to which the user name 97is added, which will be created if the -m option is specified and no 98-d option is specified. 99.It Fl e Ar expiry-time 100sets the time at which the current password will expire for this user. 101.It Fl f Ar inactive-secs 102sets the number of seconds after which, if no login has occurred for 103the user during that time, the login will be "locked". 104.It Fl g Ar gid/groupname/=uid 105sets the default group for any user added using the 106.Nm 107command. 108.It Fl r Ar low..high 109sets the low and high bounds of uid ranges for new users. A new user 110can only be created if there are uids which can be assigned from one 111of the free ranges. 112.It Fl s Ar shell 113sets the login shell for new users. 114.El 115.Pp 116In the second form of the command, 117after setting any defaults, and then values from that file, 118the command line options are processed: 119.Bl -tag -width Ds 120.It Fl G Ar secondary-group[,group,...] 121is the secondary groups to which the user will be added in the 122.Pa /etc/group 123file. 124.It Fl b Ar base-directory 125is the base directory name, in which the user's new home 126directory will be created, should the -m option be specified. 127This value can be preset for all users 128by using the 129.Ar base_dir 130field in the 131.Pa /etc/usermgmt.conf 132file - it has the format: 133.Ar base_dir <path-to-base-dir> . 134.It Fl c Ar comment 135is the comment field (also, for historical reasons known as the 136GECOS field) which will be added for the user, and typically will include 137the username, and, perhaps, contact information for the user. 138.It Fl d Ar home-directory 139is the home directory which will be created and populated for the user, 140should the -m option be specified. 141.It Fl e Ar secs-to-expiry 142provides the number of seconds since the epoch (UTC) at 143which the current password change expire. This 144can be used to implement password aging. 145A value of 1460 can be used to switch off this feature. 147The default value for this field is 0. 148See 149.Xr passwd 5 150for more details. 151This value can be preset for all users 152by using the 153.Ar expire 154field in the 155.Pa /etc/usermgmt.conf 156file - it has the format: 157.Ar expire <secs-to-expiry> . 158.It Fl g Ar gid/name/=uid 159gives the group name or identifier to be used for the new user's primary group. 160If this is 161.Ar "-g=uid" , 162then a uid and gid will be picked which are both unique 163and the same, and a line added to 164.Pa /etc/group 165to describe the new group. 166This value can be preset for all users 167by using the 168.Ar gid 169field in the 170.Pa /etc/usermgmt.conf 171file - it has the format: 172.Ar group <groupname/groupid/=uid> . 173.It Fl k Ar skeleton directory 174gives the skeleton directory in which to find dot files 175with which to populate the new user's home directory. 176.It Fl m 177create a new home directory for the new user. 178.It Fl o 179allow the new user to have a uid which is already in use for another user. 180.It Fl p Ar password 181specifies an already-encrypted password for the new user. 182This password can then be changed by using the 183.Xr chpass 1 184utility. 185This value can be preset for all users 186by using the 187.Ar password 188field in the 189.Pa /etc/usermgmt.conf 190file - it has the format: 191.Ar password <encrypted-password> . 192.It Fl s Ar shell 193specifies the login shell for the new user. 194This value can be preset for all users 195by using the 196.Ar shell 197field in the 198.Pa /etc/usermgmt.conf 199file - it has the format: 200.Ar shell <login-shell> . 201.It Fl u Ar uid 202specifies a uid for the new user. 203Boundaries for this value can be preset for all users 204by using the 205.Ar range 206field in the 207.Pa /etc/usermgmt.conf 208file - they have the format: 209.Ar range <starting-uid>..<ending-uid> . 210.It Fl v 211enables verbose mode - explain the commands as they are executed. 212.El 213.Pp 214The 215.Nm 216utility exits 0 on success, and >0 if an error occurs. 217.Sh FILES 218.Bl -tag -width /etc/usermgmt.conf -compact 219.It Pa /etc/usermgmt.conf 220.It Pa /etc/skel/.[A-z]* 221.El 222.Sh SEE ALSO 223.Xr chpass 1 , 224.Xr passwd 5 , 225.Xr group 5 , 226.Xr user 8 , 227.Xr userdel 8 , 228.Xr usermod 8 229.Sh HISTORY 230The 231.Nm 232utility first appeared in 233.Ox 2.7 . 234.Sh AUTHORS 235The 236.Nm 237utility was written by Alistair G. Crooks (agc@netbsd.org). 238