xref: /dragonfly/usr.sbin/pw/pw.conf.5 (revision 10cbe914)
1.\" Copyright (C) 1996
2.\" David L. Nugent.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY DAVID L. NUGENT AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL DAVID L. NUGENT OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: src/usr.sbin/pw/pw.conf.5,v 1.10.2.3 2001/07/22 12:41:27 dd Exp $
26.\" $DragonFly: src/usr.sbin/pw/pw.conf.5,v 1.2 2003/06/17 04:30:01 dillon Exp $
27.\"
28.Dd December 9, 1996
29.Dt PW.CONF 5
30.Os
31.Sh NAME
32.Nm pw.conf
33.Nd format of the pw.conf configuration file
34.Sh DESCRIPTION
35The file
36.Aq Pa /etc/pw.conf
37contains configuration data for the
38.Xr pw 8
39program.
40The
41.Xr pw 8
42program is used for maintenance of the system password and group
43files, allowing users and groups to be added, deleted and changed.
44This file may be modified via the
45.Xr pw 8
46command using the
47.Ar useradd
48command and the
49.Fl D
50option, or by editing it directly with a text editor.
51.Pp
52Each line in
53.Aq Pa /etc/pw.conf
54is treated either a comment or as configuration data;
55blank lines and lines commencing with a
56.Ql \&#
57character are considered comments, and any remaining lines are
58examined for a leading keyword, followed by corresponding data.
59.Pp
60Keywords recognized by
61.Xr pw 8
62are:
63.Bl -tag -width password_days -offset indent -compact
64.It defaultpasswd
65affect passwords generated for new users
66.It reuseuids
67reuse gaps in uid sequences
68.It reusegids
69reuse gaps in gid sequences
70.It nispasswd
71path to the NIS passwd database
72.It skeleton
73where to obtain default home contents
74.It newmail
75mail to send to new users
76.It logfile
77log user/group modifications to this file
78.It home
79root directory for home directories
80.It shellpath
81paths in which to locate shell programs
82.It shells
83list of valid shells (without path)
84.It defaultshell
85default shell (without path)
86.It defaultgroup
87default group
88.It extragroups
89add new users to this groups
90.It defaultclass
91place new users in this login class
92.It minuid
93.It maxuid
94range of valid default user ids
95.It mingid
96.It maxgid
97range of valid default group ids
98.It expire_days
99days after which account expires
100.It password_days
101days after which password expires
102.El
103.Pp
104Valid values for
105.Ar defaultpasswd
106are:
107.Bl -tag -width password_days -offset indent -compact
108.It no
109disable login on newly created accounts
110.It yes
111force the password to be the account name
112.It none
113force a blank password
114.It random
115generate a random password
116.El
117.Pp
118The second and third options are insecure and should be avoided if
119possible on a publicly accessible system.
120The first option requires that the superuser run
121.Xr passwd 1
122to set a password before the account may be used.
123This may also be useful for creating administrative accounts.
124The final option causes
125.Xr pw 8
126to respond by printing a randomly generated password on stdout.
127This is the preferred and most secure option.
128.Xr Pw 8
129also provides a method of setting a specific password for the new
130user via a filehandle (command lines are not secure).
131.Pp
132Both
133.Ar reuseuids
134and
135.Ar reusegids
136determine the method by which new user and group id numbers are
137generated.
138A
139.Ql \&yes
140in this field will cause
141.Xr pw 8
142to search for the first unused user or group id within the allowed
143range, whereas a
144.Ql \&no
145will ensure that no other existing user or group id within the range
146is numerically lower than the new one generated, and therefore avoids
147reusing gaps in the user or group id sequence that are caused by
148previous user or group deletions.
149Note that if the default group is not specified using the
150.Ar defaultgroup
151keyword,
152.Xr pw 8
153will create a new group for the user and attempt to keep the new
154user's uid and gid the same.
155If the new user's uid is currently in use as a group id, then the next
156available group id is chosen instead.
157.Pp
158On NIS servers which maintain a separate passwd database to
159.Pa /etc/master.passwd ,
160this option allows the additional file to be concurrently updated
161as user records are added, modified or removed.
162If blank or set to 'no', no additional database is updated.
163An absolute pathname must be used.
164.Pp
165The
166.Ar skeleton
167keyword nominates a directory from which the contents of a user's
168new home directory is constructed.
169This is
170.Pa /usr/share/skel
171by default.
172.Xr Pw 8 Ns 's
173.Fl m
174option causes the user's home directory to be created and populated
175using the files contained in the
176.Ar skeleton
177directory.
178.Pp
179To send an initial email to new users, the
180.Ar newmail
181keyword may be used to specify a path name to a file containing
182the message body of the message to be sent.
183To avoid sending mail when accounts are created, leave this entry
184blank or specify
185.Ql \&no .
186.Pp
187The
188.Ar logfile
189option allows logging of password file modifications into the
190nominated log file.
191To avoid creating or adding to such a logfile, then leave this
192field blank or specify
193.Ql \&no .
194.Pp
195The
196.Ar home
197keyword is mandatory.
198This specifies the location of the directory in which all new user
199home directories are created.
200.Pp
201.Ar shellpath
202specifies a list of directories - separated by colons
203.Ql \&:
204- which contain the programs used by the login shells.
205.Pp
206The
207.Ar shells
208keyword specifies a list of programs available for use as login
209shells.
210This list is a comma-separated list of shell names which should
211not contain a path.
212These shells must exist in one of the directories nominated by
213.Ar shellpath .
214.Pp
215The
216.Ar defaultshell
217keyword nominates which shell program to use for new users when
218none is specified on the
219.Xr pw 8
220command line.
221.Pp
222The
223.Ar defaultgroup
224keyword defines the primary group (the group id number in the
225password file) used for new accounts.
226If left blank, or the word
227.Ql \&no
228is used, then each new user will have a corresponding group of
229their own created automatically.
230This is the recommended procedure for new users as it best secures each
231user's files against interference by other users of the system
232irrespective of the
233.Em umask
234normally used by the user.
235.Pp
236.Ar extragroups
237provides an automatic means of placing new users into groups within
238the
239.Pa /etc/groups
240file.
241This is useful where all users share some resources, and is preferable
242to placing users into the same primary group.
243The effect of this keyword can be overridden using the
244.Fl G
245option on the
246.Xr pw 8
247command line.
248.Pp
249The
250.Ar defaultclass
251field determines the login class (See
252.Xr login.conf 5 )
253that new users will be allocated unless overwritten by
254.Xr pw 8 .
255.Pp
256The
257.Ar minuid ,
258.Ar maxuid ,
259.Ar mingid ,
260.Ar maxgid
261keywords determines the allowed ranges of automatically allocated user
262and group id numbers.
263The default values for both user and group ids are 1000 and 32000 as
264minimum and maximum respectively.
265The user and group id's actually used when creating an account with
266.Xr pw 8
267may be overridden using the
268.Fl u
269and
270.Fl g
271command line options.
272.Pp
273The
274.Ar expire_days
275and
276.Ar password_days
277are used to automatically calculate the number of days from the date
278on which an account is created when the account will expire or the
279user will be forced to change the account's password.
280A value of
281.Ql \&0
282in either field will disable the corresponding (account or password)
283expiration date.
284.Sh LIMITS
285The maximum line length of
286.Pa /etc/pw.conf
287is 1024 characters.
288Longer lines will be skipped and treated
289as comments.
290.Sh FILES
291.Bl -tag -width /etc/master.passwd -compact
292.It Pa /etc/pw.conf
293.It Pa /etc/passwd
294.It Pa /etc/master.passwd
295.It Pa /etc/group
296.El
297.Sh SEE ALSO
298.Xr passwd 1 ,
299.Xr group 5 ,
300.Xr login.conf 5 ,
301.Xr passwd 5 ,
302.Xr pw 8
303