xref: /freebsd/usr.sbin/adduser/adduser.8 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\" Copyright (c) 1995-1996 Wolfram Schneider <wosch@FreeBSD.org>. Berlin.
2.\" All rights reserved.
3.\" Copyright (c) 2002-2004 Michael Telahun Makonnen <mtm@FreeBSD.org>
4.\" 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.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd June 7, 2006
30.Dt ADDUSER 8
31.Os
32.Sh NAME
33.Nm adduser
34.Nd command for adding new users
35.Sh SYNOPSIS
36.Nm
37.Op Fl CDENShq
38.Op Fl G Ar groups
39.Op Fl L Ar login_class
40.Op Fl d Ar partition
41.Op Fl f Ar file
42.Op Fl g Ar login_group
43.Op Fl k Ar dotdir
44.Op Fl m Ar message_file
45.Op Fl s Ar shell
46.Op Fl u Ar uid_start
47.Op Fl w Ar type
48.Sh DESCRIPTION
49The
50.Nm
51utility is a shell script, implemented around the
52.Xr pw 8
53command, for adding new users.
54It creates passwd/group entries, a home directory,
55copies dotfiles and sends the new user a welcome message.
56It supports two modes of operation.
57It may be used interactively
58at the command line to add one user at a time, or it may be directed
59to get the list of new users from a file and operate in batch mode
60without requiring any user interaction.
61.Sh RESTRICTIONS
62.Bl -tag -width indent
63.It username
64Login name.
65The user name is restricted to whatever
66.Xr pw 8
67will accept.
68Generally this means it
69may contain only lowercase characters or digits but cannot begin with the
70.Ql -
71character.
72Maximum length
73is 16 characters.
74The reasons for this limit are historical.
75Given that people have traditionally wanted to break this
76limit for aesthetic reasons, it has never been of great importance to break
77such a basic fundamental parameter in
78.Ux .
79You can change
80.Dv UT_NAMESIZE
81in
82.In utmp.h
83and recompile the
84world; people have done this and it works, but you will have problems
85with any precompiled programs, or source that assumes the 8-character
86name limit, such as NIS.
87The NIS protocol mandates an 8-character username.
88If you need a longer login name for e-mail addresses,
89you can define an alias in
90.Pa /etc/mail/aliases .
91.It "full name"
92This is typically known as the gecos field and usually contains
93the user's full name.
94Additionally, it may contain a comma separated
95list of values such as office number and work and home phones.
96If the
97name contains an ampersand it will be replaced by the capitalized
98login name when displayed by other programs.
99The
100.Ql \&:
101character is not allowed.
102.It shell
103Unless the
104.Fl S
105argument is supplied only valid shells from the shell database
106.Pq Pa /etc/shells
107are allowed.
108In addition,
109either the base name or the full path of the shell may be supplied.
110.It UID
111Automatically generated or your choice.
112It must be less than 32000.
113.It "GID/login group"
114Automatically generated or your choice.
115It must be less than 32000.
116.It password
117You may choose an empty password, disable the password, use a
118randomly generated password or specify your own plaintext password,
119which will be encrypted before being stored in the user database.
120.El
121.Sh UNIQUE GROUPS
122Perhaps you are missing what
123.Em can
124be done with this scheme that falls apart
125with most other schemes.
126With each user in their own group,
127they can safely run with a umask of 002 instead of the usual 022
128and create files in their home directory
129without worrying about others being able to change them.
130.Pp
131For a shared area you create a separate UID/GID (like cvs or ncvs on freefall),
132you place each person that should be able to access this area into that new
133group.
134.Pp
135This model of UID/GID administration allows far greater flexibility than lumping
136users into groups and having to muck with the umask when working in a shared
137area.
138.Pp
139I have been using this model for almost 10 years and found that it works
140for most situations, and has never gotten in the way.
141(Rod Grimes)
142.Sh CONFIGURATION
143The
144.Nm
145utility reads its configuration information from
146.Pa /etc/adduser.conf .
147If this file does not exist, it will use predefined defaults.
148While this file may be edited by hand,
149the safer option is to use the
150.Fl C
151command line argument.
152With this argument,
153.Nm
154will start interactive input, save the answers to its prompts in
155.Pa /etc/adduser.conf ,
156and promptly exit without modifying the user
157database.
158Options specified on the command line will take precedence over
159any values saved in this file.
160.Sh OPTIONS
161.Bl -tag -width indent
162.It Fl C
163Create new configuration file and exit.
164This option is mutually exclusive with the
165.Fl f
166option.
167.It Fl d Ar partition
168Home partition.
169Default partition, under which all user directories
170will be located.
171The
172.Pa /nonexistent
173partition is considered special.
174The
175.Nm
176script will not create and populate a home directory by that name.
177Otherwise,
178by default it attempts to create a home directory.
179.It Fl D
180Do not attempt to create the home directory.
181.It Fl E
182Disable the account.
183This option will lock the account by prepending the string
184.Dq Li *LOCKED*
185to the password field.
186The account may be unlocked
187by the super-user with the
188.Xr pw 8
189command:
190.Pp
191.D1 Nm pw Cm unlock Op Ar name | uid
192.It Fl f Ar file
193Get the list of accounts to create from
194.Ar file .
195If
196.Ar file
197is
198.Dq Fl ,
199then get the list from standard input.
200If this option is specified,
201.Nm
202will operate in batch mode and will not seek any user input.
203If an error is encountered while processing an account, it will write a
204message to standard error and move to the next account.
205The format
206of the input file is described below.
207.It Fl g Ar login_group
208Normally,
209if no login group is specified,
210it is assumed to be the same as the username.
211This option makes
212.Ar login_group
213the default.
214.It Fl G Ar groups
215Space-separated list of additional groups.
216This option allows the user to specify additional groups to add users to.
217The user is a member of these groups in addition to their login group.
218.It Fl h
219Print a summary of options and exit.
220.It Fl k Ar directory
221Copy files from
222.Ar directory
223into the home
224directory of new users;
225.Pa dot.foo
226will be renamed to
227.Pa .foo .
228.It Fl L Ar login_class
229Set default login class.
230.It Fl m Ar file
231Send new users a welcome message from
232.Ar file .
233Specifying a value of
234.Cm no
235for
236.Ar file
237causes no message to be sent to new users.
238Please note that the message
239file can reference the internal variables of the
240.Nm
241script.
242.It Fl N
243Do not read the default configuration file.
244.It Fl q
245Minimal user feedback.
246In particular, the random password will not be echoed to
247standard output.
248.It Fl s Ar shell
249Default shell for new users.
250The
251.Ar shell
252argument may be the base name of the shell or the full path.
253Unless the
254.Fl S
255argument is supplied the shell must exist in
256.Pa /etc/shells
257or be the special shell
258.Em nologin
259to be considered a valid shell.
260.It Fl S
261The existence or validity of the specified shell will not be checked.
262.It Fl u Ar uid
263Use UIDs from
264.Ar uid
265on up.
266.It Fl w Ar type
267Password type.
268The
269.Nm
270utility allows the user to specify what type of password to create.
271The
272.Ar type
273argument may have one of the following values:
274.Bl -tag -width ".Cm random"
275.It Cm no
276Disable the password.
277Instead of an encrypted string, the password field will contain a single
278.Ql *
279character.
280The user may not log in until the super-user
281manually enables the password.
282.It Cm none
283Use an empty string as the password.
284.It Cm yes
285Use a user-supplied string as the password.
286In interactive mode,
287the user will be prompted for the password.
288In batch mode, the
289last (10th) field in the line is assumed to be the password.
290.It Cm random
291Generate a random string and use it as a password.
292The password will be echoed to standard output.
293In addition, it will be available for inclusion in the message file in the
294.Va randompass
295variable.
296.El
297.El
298.Sh FORMAT
299When the
300.Fl f
301option is used, the account information must be stored in a specific
302format.
303All empty lines or lines beginning with a
304.Ql #
305will be ignored.
306All other lines must contain ten colon
307.Pq Ql \&:
308separated fields as described below.
309Command line options do not take precedence
310over values in the fields.
311Only the password field may contain a
312.Ql \&:
313character as part of the string.
314.Pp
315.Sm off
316.D1 Ar name : uid : gid : class : change : expire : gecos : home_dir : shell : password
317.Sm on
318.Bl -tag -width ".Ar password"
319.It Ar name
320Login name.
321This field may not be empty.
322.It Ar uid
323Numeric login user ID.
324If this field is left empty, it will be automatically generated.
325.It Ar gid
326Numeric primary group ID.
327If this field is left empty, a group with the
328same name as the user name will be created and its GID will be used
329instead.
330.It Ar class
331Login class.
332This field may be left empty.
333.It Ar change
334Password ageing.
335This field denotes the password change date for the account.
336The format of this field is the same as the format of the
337.Fl p
338argument to
339.Xr pw 8 .
340It may be
341.Ar dd Ns - Ns Ar mmm Ns - Ns Ar yy Ns Op Ar yy ,
342where
343.Ar dd
344is for the day,
345.Ar mmm
346is for the month in numeric or alphabetical format:
347.Dq Li 10
348or
349.Dq Li Oct ,
350and
351.Ar yy Ns Op Ar yy
352is the four or two digit year.
353To denote a time relative to the current date the format is:
354.No + Ns Ar n Ns Op Ar mhdwoy ,
355where
356.Ar n
357denotes a number, followed by the minutes, hours, days, weeks,
358months or years after which the password must be changed.
359This field may be left empty to turn it off.
360.It Ar expire
361Account expiration.
362This field denotes the expiry date of the account.
363The account may not be used after the specified date.
364The format of this field is the same as that for password ageing.
365This field may be left empty to turn it off.
366.It Ar gecos
367Full name and other extra information about the user.
368.It Ar home_dir
369Home directory.
370If this field is left empty, it will be automatically
371created by appending the username to the home partition.
372The
373.Pa /nonexistent
374home directory is considered special and
375is understood to mean that no home directory is to be
376created for the user.
377.It Ar shell
378Login shell.
379This field should contain either the base name or
380the full path to a valid login shell.
381.It Ar password
382User password.
383This field should contain a plaintext string, which will
384be encrypted before being placed in the user database.
385If the password type is
386.Cm yes
387and this field is empty, it is assumed the account will have an empty password.
388If the password type is
389.Cm random
390and this field is
391.Em not
392empty, its contents will be used
393as a password.
394This field will be ignored if the
395.Fl p
396option is used with a
397.Cm no
398or
399.Cm none
400argument.
401Be careful not to terminate this field with a closing
402.Ql \&:
403because it will be treated as part of the password.
404.El
405.Sh FILES
406.Bl -tag -width ".Pa /etc/adduser.message" -compact
407.It Pa /etc/master.passwd
408user database
409.It Pa /etc/group
410group database
411.It Pa /etc/shells
412shell database
413.It Pa /etc/login.conf
414login classes database
415.It Pa /etc/adduser.conf
416configuration file for
417.Nm
418.It Pa /etc/adduser.message
419message file for
420.Nm
421.It Pa /usr/share/skel
422skeletal login directory
423.It Pa /var/log/adduser
424logfile for
425.Nm
426.El
427.Sh SEE ALSO
428.Xr chpass 1 ,
429.Xr passwd 1 ,
430.Xr adduser.conf 5 ,
431.Xr aliases 5 ,
432.Xr group 5 ,
433.Xr login.conf 5 ,
434.Xr passwd 5 ,
435.Xr shells 5 ,
436.Xr adding_user 8 ,
437.Xr pw 8 ,
438.Xr pwd_mkdb 8 ,
439.Xr rmuser 8 ,
440.Xr vipw 8 ,
441.Xr yp 8
442.Sh HISTORY
443The
444.Nm
445command appeared in
446.Fx 2.1 .
447.Sh AUTHORS
448.An -nosplit
449This manual page and the original script, in Perl, was written by
450.An Wolfram Schneider Aq wosch@FreeBSD.org .
451The replacement script, written as a Bourne
452shell script with some enhancements, and the man page modification that
453came with it were done by
454.An Mike Makonnen Aq mtm@identd.net .
455.Sh BUGS
456In order for
457.Nm
458to correctly expand variables such as
459.Va $username
460and
461.Va $randompass
462in the message sent to new users, it must let the shell evaluate
463each line of the message file.
464This means that shell commands can also be embedded in the message file.
465The
466.Nm
467utility attempts to mitigate the possibility of an attacker using this
468feature by refusing to evaluate the file if it is not owned and writable
469only by the root user.
470In addition, shell special characters and operators will have to be
471escaped when used in the message file.
472.Pp
473Also, password ageing and account expiry times are currently settable
474only in batch mode or when specified in
475.Pa /etc/adduser.conf .
476The user should be able to set them in interactive mode as well.
477