userdb/makeuserdb.8.in

   1 '\" t
   2 .\"  <!-- Copyright 1998 - 2007 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: makeuserdb
   5 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   6 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
   7 .\"      Date: 08/25/2013
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"  Language: English
  11 .\"
  12 .TH "MAKEUSERDB" "8" "08/25/2013" "Double Precision, Inc." "Double Precision, Inc."
  13 .\" -----------------------------------------------------------------
  14 .\" * Define some portability stuff
  15 .\" -----------------------------------------------------------------
  16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17 .\" http://bugs.debian.org/507673
  18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20 .ie \n(.g .ds Aq \(aq
  21 .el       .ds Aq '
  22 .\" -----------------------------------------------------------------
  23 .\" * set default formatting
  24 .\" -----------------------------------------------------------------
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .\" -----------------------------------------------------------------
  30 .\" * MAIN CONTENT STARTS HERE *
  31 .\" -----------------------------------------------------------------
  32 .SH "NAME"
  33 makeuserdb \- create @userdb@
  34 .SH "SYNOPSIS"
  35 .HP \w'\fBmakeuserdb\fR\ 'u
  36 \fBmakeuserdb\fR [\-f\ \fIfilename\fR]
  37 .HP \w'\fBpw2userdb\fR\ 'u
  38 \fBpw2userdb\fR
  39 .HP \w'\fBvchkpw2userdb\fR\ 'u
  40 \fBvchkpw2userdb\fR [\-\-vpopmailhome=\fIdir\fR] [\-\-todir=\fIdir\fR]
  41 .SH "DESCRIPTION"
  42 .PP
  43 \fBmakeuserdb\fR
  44 creates
  45 @userdb@\&.dat
  46 from the contents of
  47 @userdb@\&.
  48 @userdb@\*(Aqs contents are described later in this document\&.
  49 Maildrop,
  50 Courier, and other applications use
  51 @userdb@\&.dat
  52 as a substitute/complement for your system password file\&. The usual purpose for
  53 @userdb@\&.dat
  54 is to specify "virtual" accounts \- accounts that do not have an associated system login\&. Usually (but not necessarily) all virtual accounts share the same system userid\&.
  55 @userdb@\&.dat
  56 may also replace your system password file\&. Because the system password file is a text file, when there\*(Aqs a large number of accounts it will be significantly faster to search
  57 @userdb\&.dat@, which is a binary database, instead of a flat text file that the system password file usually is\&.
  58 .PP
  59 The
  60 \fBmakeuserdb\fR
  61 command can be safely executed during normal system activity\&.
  62 .PP
  63 The
  64 \fB\-f\fR
  65 option creates
  66 \fIfilename\fR\&.dat
  67 from
  68 \fIfilename\fR, instead of the default
  69 @userdb@\&.dat
  70 from
  71 @userdb@\&.
  72 .SS "Format of @userdb@"
  73 .PP
  74 @userdb@
  75 is a plain text file that can be created using any text editor\&. Blank lines are ignored\&. Lines that start with the # character are comments, and are also ignored\&. Other lines define properties of a single "account", one line per account\&.
  76 @userdb@
  77 may be a directory instead of a plain file\&. In that case all files in
  78 @userdb@
  79 are essentially concatenated, and are treated as a single file\&. Each line takes the following format:
  80 .sp
  81 .if n \{\
  82 .RS 4
  83 .\}
  84 .nf
  85 \fIname\fR<TAB>\fIfield\fR=\fIvalue\fR|\fIfield\fR=\fIvalue\fR\&.\&.\&.
  86 .fi
  87 .if n \{\
  88 .RE
  89 .\}
  90 .PP
  91 \fIname\fR
  92 is the account name\&.
  93 \fIname\fR
  94 MUST contain only lowercase characters If
  95 Courier
  96 is configured to treat lowercase and uppercase account names as identical,
  97 \fIname\fR
  98 is followed by exactly one tab character, then a list of field/value pairs separated by vertical slashes\&.
  99 \fIfield\fR
 100 is the name of the field,
 101 \fIvalue\fR
 102 is the field value\&. Fields and values themself cannot contain slashes or control characters\&. Fields may be specified in any order\&. Here are all the currently defined fields\&. Note that not every field is used by every application that reads
 103 @userdb@\&.dat\&.
 104 .PP
 105 \fIuid\fR
 106 \-
 107 \fIvalue\fR
 108 is a (possibly) unique numerical user ID for this account\&.
 109 .PP
 110 \fIgid\fR
 111 \-
 112 \fIvalue\fR
 113 is a (possibly) unique numerical group ID for this account\&.
 114 .PP
 115 \fIhome\fR
 116 \-
 117 \fIvalue\fR
 118 is the account\*(Aqs home directory\&.
 119 .PP
 120 \fIshell\fR
 121 \-
 122 \fIvalue\fR
 123 is the account\*(Aqs default login shell\&.
 124 .PP
 125 \fIsystempw\fR
 126 \-
 127 \fIvalue\fR
 128 is the account\*(Aqs password\&. See
 129 \m[blue]\fB\fBuserdbpw\fR(8)\fR\m[]\&\s-2\u[1]\d\s+2
 130 for details on how to set up this field\&.
 131 .PP
 132 \fIpop3pw, esmtppw, imappw\&.\&.\&.\fR
 133 \-
 134 \fIvalue\fR
 135 specifies a separate password used only for authenticating access using a specific service, such as POP3, IMAP, or anything else\&. If not defined,
 136 \fIsystempw\fR
 137 is always used\&. This allows access to an account to be restricted only to certain services, such as POP3, even if other services are also enabled on the server\&.
 138 .PP
 139 \fImail\fR
 140 \-
 141 \fIvalue\fR
 142 specifies the location of the account\*(Aqs Maildir mailbox\&. This is an optional field that is normally used when
 143 \fBuserdb\fR
 144 is used to provide aliases for other mail accounts\&. For example, one particular multi\-domain E\-mail service configuration that\*(Aqs used by both
 145 Qmail
 146 and
 147 Courier
 148 servers is to deliver mail for a mailbox in a virtual domain, such as "user@example\&.com", to a local mailbox called "example\-user"\&. Instead of requiring the E\-mail account holder to log in as "example\-user" to download mail from this account, a
 149 \fBuserdb\fR
 150 entry for "user@example\&.com" is set up with
 151 \fImail\fR
 152 set to the location of example\-user\*(Aqs Maildir mailbox, thus hiding the internal mail configuration from the E\-mail account holder\*(Aqs view\&.
 153 .PP
 154 \fIquota\fR
 155 \-
 156 \fIvalue\fR
 157 specifies the maildir quota for the account\*(Aqs Maildir\&. This has nothing to do with actual filesystem quotas\&.
 158 Courier
 159 has a software\-based Maildir quota enforcement mechanism which requires additional setup and configuration\&. See
 160 \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[2]\d\s+2
 161 for additional information\&.
 162 .SS "@userdb@shadow\&.dat"
 163 .PP
 164 All fields whose name ends with \*(Aqpw\*(Aq will NOT copied to
 165 @userdb@\&.dat\&. These fields will be copied to
 166 @userdb@shadow\&.dat\&.
 167 \fBmakeuserdb\fR
 168 creates
 169 @userdb@shadow\&.dat
 170 without any group and world permissions\&. Note that
 171 \fBmakeuserdb\fR
 172 reports an error if
 173 \fB@userdb@\fR
 174 has any group or world permissions\&.
 175 .SS "CONVERTING /etc/passwd and vpopmail to @userdb@ format"
 176 .PP
 177 \fBpw2userdb\fR
 178 reads the
 179 /etc/passwd
 180 and
 181 /etc/shadow
 182 files and converts all entries to the
 183 @userdb@
 184 format, printing the result on standard output\&. The output of
 185 \fBpw2userdb\fR
 186 can be saved as
 187 \fB@userdb@\fR
 188 (or as some file in this subdirectory)\&. Linear searches of
 189 /etc/passwd
 190 can be very slow when you have tens of thousands of accounts\&. Programs like
 191 \fBmaildrop\fR
 192 always look in
 193 @userdb@
 194 first\&. By saving the system password file in
 195 @userdb@
 196 it is possible to significantly reduce the amount of time it takes to look up this information\&.
 197 .PP
 198 After saving the output of
 199 \fBpw2userdb\fR, you must still run
 200 \fBmakeuserdb\fR
 201 to create
 202 @userdb@\&.dat\&.
 203 .PP
 204 \fBvchkpw2userdb\fR
 205 converts a vpopmail\-style directory hierarchy to the
 206 @userdb@
 207 format\&. This is an external virtual domain management package that\*(Aqs often used with
 208 Qmail
 209 servers\&.
 210 .PP
 211 Generally, an account named \*(Aqvpopmail\*(Aq is reserved for this purpose\&. In that account the file
 212 users/vpasswd
 213 has the same layout as
 214 /etc/passwd, and performs a similar function, except that all userid in
 215 users/vpasswd
 216 have the same userid\&. Additionally, the
 217 domains
 218 subdirectory stores virtual accounts for multiple domains\&. For example,
 219 domains/example\&.com/vpasswd
 220 has the passwd file for the domain
 221 \fIexample\&.com\fR\&. Some systems also have a soft link,
 222 \fIdomains/default\fR, that points to a domain that\*(Aqs considered a "default" domain\&.
 223 .PP
 224 The
 225 \fBvchkpw2userdb\fR
 226 reads all this information, and tries to convert it into the
 227 @userdb@
 228 format\&. The
 229 \fI\-\-vpopmailhost\fR
 230 option specifies the top level directory, if it is not the home directory of the vpopmail account\&.
 231 .PP
 232 The
 233 \fBvchkpw2userdb\fR
 234 script prints the results on standard output\&. If specified, the
 235 \fI\-\-todir\fR
 236 option tries to convert all
 237 vpasswd
 238 files one at a time, saving each one individually in
 239 \fIdir\fR\&. For example:
 240 .sp
 241 .if n \{\
 242 .RS 4
 243 .\}
 244 .nf
 245 mkdir @userdb@
 246 vchkpw2userdb \-\-todir=@userdb@/vpopmail
 247 makeuserdb
 248 .fi
 249 .if n \{\
 250 .RE
 251 .\}
 252 .PP
 253 It is still necessary to run
 254 \fBmakeuserdb\fR, of course, to create the binary database file
 255 @userdb@\&.dat
 256 .PP
 257 NOTE: You are still required to create the
 258 \fB@userdb@\fR
 259 entry which maps system userids back to accounts, "\fIuid\fR=<TAB>\fIname\fR", if that\*(Aqs applicable\&.
 260 \fBvchkpw2userdb\fR
 261 will not do it for you\&.
 262 .PP
 263 NOTE:
 264 \fBmakeuserdb\fR
 265 may complain about duplicate entries, if your "default" entries in
 266 users/vpasswd
 267 or
 268 domains/default/vpasswd
 269 are the same as anything in any other
 270 @userdb@
 271 file\&. It is also likely that you\*(Aqll end up with duplicate, but distinct, entries for every account in the default domain\&. For example, if your default domain is example\&.com, you\*(Aqll end up with duplicate entries \- you\*(Aqll have entries for both
 272 \fIuser\fR
 273 and
 274 \fIuser@example\&.com\fR\&.
 275 .PP
 276 If you intend to maintain the master set of accounts using vchkpw/vpopmail, in order to avoid cleaning this up every time, you might want to consider doing the following: run
 277 \fBvchkpw2userdb\fR
 278 once, using the
 279 \fI\-\-todir\fR
 280 option\&. Then, go into the resulting directory, and replace one of the redundant files with a soft link to
 281 /dev/null\&. This allows you to run
 282 \fBvchkpw2userdb\fR
 283 without having to go in and cleaning up again, afterwards\&.
 284 .SH "FILES"
 285 .sp
 286 .if n \{\
 287 .RS 4
 288 .\}
 289 .nf
 290 @userdb@
 291 @userdb@\&.dat
 292 @userdb@shadow\&.dat
 293 @tmpdir@/userdb\&.tmp \- temporary file
 294 @tmpdir@/userdbshadow\&.tmp \- temporary file
 295 .fi
 296 .if n \{\
 297 .RE
 298 .\}
 299 .SH "BUGS"
 300 .PP
 301 \fBmakeuserdb\fR
 302 is a Perl script, and uses Perl\*(Aqs portable locking\&. Perl\*(Aqs documentation notes that certain combinations of locking options may not work with some networks\&.
 303 .SH "SEE ALSO"
 304 .PP
 305 \m[blue]\fB\fBuserdb\fR(8)\fR\m[]\&\s-2\u[3]\d\s+2,
 306 \m[blue]\fB\fBmaildrop\fR(8)\fR\m[]\&\s-2\u[4]\d\s+2,
 307 \m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[5]\d\s+2,
 308 \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[2]\d\s+2\&.
 309 .SH "NOTES"
 310 .IP " 1." 4
 311 \fBuserdbpw\fR(8)
 312 .RS 4
 313 \%[set $man.base.url.for.relative.links]/userdbpw.html
 314 .RE
 315 .IP " 2." 4
 316 \fBmaildirquota\fR(7)
 317 .RS 4
 318 \%[set $man.base.url.for.relative.links]/maildirquota.html
 319 .RE
 320 .IP " 3." 4
 321 \fBuserdb\fR(8)
 322 .RS 4
 323 \%[set $man.base.url.for.relative.links]/userdb.html
 324 .RE
 325 .IP " 4." 4
 326 \fBmaildrop\fR(8)
 327 .RS 4
 328 \%[set $man.base.url.for.relative.links]/maildrop.html
 329 .RE
 330 .IP " 5." 4
 331 \fBcourier\fR(8)
 332 .RS 4
 333 \%[set $man.base.url.for.relative.links]/courier.html
 334 .RE