| 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 |