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