usr.sbin/pw/pw.conf.5

   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.16 2007/03/30 11:23:10 le Exp $
  26 .\"
  27 .Dd March 30, 2007
  28 .Dt PW.CONF 5
  29 .Os
  30 .Sh NAME
  31 .Nm pw.conf
  32 .Nd format of the pw.conf configuration file
  33 .Sh DESCRIPTION
  34 The file
  35 .In /etc/pw.conf
  36 contains configuration data for the
  37 .Xr pw 8
  38 utility.
  39 The
  40 .Xr pw 8
  41 utility is used for maintenance of the system password and group
  42 files, allowing users and groups to be added, deleted and changed.
  43 This file may be modified via the
  44 .Xr pw 8
  45 command using the
  46 .Ar useradd
  47 command and the
  48 .Fl D
  49 option, or by editing it directly with a text editor.
  50 .Pp
  51 Each line in
  52 .Pa /etc/pw.conf
  53 is treated either a comment or as configuration data;
  54 blank lines and lines commencing with a
  55 .Ql \&#
  56 character are considered comments, and any remaining lines are
  57 examined for a leading keyword, followed by corresponding data.
  58 .Pp
  59 Keywords recognized by
  60 .Xr pw 8
  61 are:
  62 .Bl -tag -width password_days -offset indent -compact
  63 .It defaultpasswd
  64 affect passwords generated for new users
  65 .It reuseuids
  66 reuse gaps in uid sequences
  67 .It reusegids
  68 reuse gaps in gid sequences
  69 .It nispasswd
  70 path to the
  71 .Tn NIS
  72 passwd database
  73 .It skeleton
  74 where to obtain default home contents
  75 .It newmail
  76 mail to send to new users
  77 .It logfile
  78 log user/group modifications to this file
  79 .It home
  80 root directory for home directories
  81 .It homemode
  82 permissions for home directory
  83 .It shellpath
  84 paths in which to locate shell programs
  85 .It shells
  86 list of valid shells (without path)
  87 .It defaultshell
  88 default shell (without path)
  89 .It defaultgroup
  90 default group
  91 .It extragroups
  92 add new users to this groups
  93 .It defaultclass
  94 place new users in this login class
  95 .It minuid
  96 .It maxuid
  97 range of valid default user ids
  98 .It mingid
  99 .It maxgid
 100 range of valid default group ids
 101 .It expire_days
 102 days after which account expires
 103 .It password_days
 104 days after which password expires
 105 .El
 106 .Pp
 107 Valid values for
 108 .Ar defaultpasswd
 109 are:
 110 .Bl -tag -width password_days -offset indent -compact
 111 .It no
 112 disable login on newly created accounts
 113 .It yes
 114 force the password to be the account name
 115 .It none
 116 force a blank password
 117 .It random
 118 generate a random password
 119 .El
 120 .Pp
 121 The second and third options are insecure and should be avoided if
 122 possible on a publicly accessible system.
 123 The first option requires that the superuser run
 124 .Xr passwd 1
 125 to set a password before the account may be used.
 126 This may also be useful for creating administrative accounts.
 127 The final option causes
 128 .Xr pw 8
 129 to respond by printing a randomly generated password on stdout.
 130 This is the preferred and most secure option.
 131 The
 132 .Xr pw 8
 133 utility also provides a method of setting a specific password for the new
 134 user via a filehandle (command lines are not secure).
 135 .Pp
 136 Both
 137 .Ar reuseuids
 138 and
 139 .Ar reusegids
 140 determine the method by which new user and group id numbers are
 141 generated.
 142 A
 143 .Ql \&yes
 144 in this field will cause
 145 .Xr pw 8
 146 to search for the first unused user or group id within the allowed
 147 range, whereas a
 148 .Ql \&no
 149 will ensure that no other existing user or group id within the range
 150 is numerically lower than the new one generated, and therefore avoids
 151 reusing gaps in the user or group id sequence that are caused by
 152 previous user or group deletions.
 153 Note that if the default group is not specified using the
 154 .Ar defaultgroup
 155 keyword,
 156 .Xr pw 8
 157 will create a new group for the user and attempt to keep the new
 158 user's uid and gid the same.
 159 If the new user's uid is currently in use as a group id, then the next
 160 available group id is chosen instead.
 161 .Pp
 162 On
 163 .Tn NIS
 164 servers which maintain a separate passwd database to
 165 .Pa /etc/master.passwd ,
 166 this option allows the additional file to be concurrently updated
 167 as user records are added, modified or removed.
 168 If blank or set to 'no', no additional database is updated.
 169 An absolute pathname must be used.
 170 .Pp
 171 The
 172 .Ar skeleton
 173 keyword nominates a directory from which the contents of a user's
 174 new home directory is constructed.
 175 This is
 176 .Pa /usr/share/skel
 177 by default.
 178 The
 179 .Xr pw 8 Ns 's
 180 .Fl m
 181 option causes the user's home directory to be created and populated
 182 using the files contained in the
 183 .Ar skeleton
 184 directory.
 185 .Pp
 186 To send an initial email to new users, the
 187 .Ar newmail
 188 keyword may be used to specify a path name to a file containing
 189 the message body of the message to be sent.
 190 To avoid sending mail when accounts are created, leave this entry
 191 blank or specify
 192 .Ql \&no .
 193 .Pp
 194 The
 195 .Ar logfile
 196 option allows logging of password file modifications into the
 197 nominated log file.
 198 To avoid creating or adding to such a logfile, then leave this
 199 field blank or specify
 200 .Ql \&no .
 201 .Pp
 202 The
 203 .Ar home
 204 keyword is mandatory.
 205 This specifies the location of the directory in which all new user
 206 home directories are created.
 207 .Pp
 208 The
 209 .Ar homemode
 210 keyword is optional.
 211 It specifies the creation mask of the user's home directory and is modified by
 212 .Xr umask 2 .
 213 .Pp
 214 The
 215 .Ar shellpath
 216 keyword specifies a list of directories - separated by colons
 217 .Ql \&:
 218 - which contain the programs used by the login shells.
 219 .Pp
 220 The
 221 .Ar shells
 222 keyword specifies a list of programs available for use as login
 223 shells.
 224 This list is a comma-separated list of shell names which should
 225 not contain a path.
 226 These shells must exist in one of the directories nominated by
 227 .Ar shellpath .
 228 .Pp
 229 The
 230 .Ar defaultshell
 231 keyword nominates which shell program to use for new users when
 232 none is specified on the
 233 .Xr pw 8
 234 command line.
 235 .Pp
 236 The
 237 .Ar defaultgroup
 238 keyword defines the primary group (the group id number in the
 239 password file) used for new accounts.
 240 If left blank, or the word
 241 .Ql \&no
 242 is used, then each new user will have a corresponding group of
 243 their own created automatically.
 244 This is the recommended procedure for new users as it best secures each
 245 user's files against interference by other users of the system
 246 irrespective of the
 247 .Em umask
 248 normally used by the user.
 249 .Pp
 250 The
 251 .Ar extragroups
 252 keyword provides an automatic means of placing new users into groups within
 253 the
 254 .Pa /etc/groups
 255 file.
 256 This is useful where all users share some resources, and is preferable
 257 to placing users into the same primary group.
 258 The effect of this keyword can be overridden using the
 259 .Fl G
 260 option on the
 261 .Xr pw 8
 262 command line.
 263 .Pp
 264 The
 265 .Ar defaultclass
 266 field determines the login class (See
 267 .Xr login.conf 5 )
 268 that new users will be allocated unless overwritten by
 269 .Xr pw 8 .
 270 .Pp
 271 The
 272 .Ar minuid ,
 273 .Ar maxuid ,
 274 .Ar mingid ,
 275 .Ar maxgid
 276 keywords determine the allowed ranges of automatically allocated user
 277 and group id numbers.
 278 The default values for both user and group ids are 1000 and 32000 as
 279 minimum and maximum respectively.
 280 The user and group id's actually used when creating an account with
 281 .Xr pw 8
 282 may be overridden using the
 283 .Fl u
 284 and
 285 .Fl g
 286 command line options.
 287 .Pp
 288 The
 289 .Ar expire_days
 290 and
 291 .Ar password_days
 292 are used to automatically calculate the number of days from the date
 293 on which an account is created when the account will expire or the
 294 user will be forced to change the account's password.
 295 A value of
 296 .Ql \&0
 297 in either field will disable the corresponding (account or password)
 298 expiration date.
 299 .Sh LIMITS
 300 The maximum line length of
 301 .Pa /etc/pw.conf
 302 is 1024 characters.
 303 Longer lines will be skipped and treated
 304 as comments.
 305 .Sh FILES
 306 .Bl -tag -width /etc/master.passwd -compact
 307 .It Pa /etc/pw.conf
 308 .It Pa /etc/passwd
 309 .It Pa /etc/master.passwd
 310 .It Pa /etc/group
 311 .El
 312 .Sh SEE ALSO
 313 .Xr passwd 1 ,
 314 .Xr umask 2 ,
 315 .Xr group 5 ,
 316 .Xr login.conf 5 ,
 317 .Xr passwd 5 ,
 318 .Xr pw 8