1 .TH "VMM.CFG" "5" "2014-02-17" "vmm 0.6" "vmm" |
|
2 .SH NAME |
|
3 vmm.cfg \- configuration file for vmm |
|
4 .\" ----------------------------------------------------------------------- |
|
5 .SH SYNOPSIS |
|
6 vmm.cfg |
|
7 .\" ----------------------------------------------------------------------- |
|
8 .SH DESCRIPTION |
|
9 .BR vmm (1) |
|
10 reads its configuration data from |
|
11 .IR vmm.cfg . |
|
12 .PP |
|
13 The configuration file is split into multiple sections. |
|
14 A section starts with the section name, enclosed in square brackets |
|
15 .RB ` [ "' and `" ] ', |
|
16 followed by |
|
17 .RI ` option " = " value ' |
|
18 pairs. |
|
19 .br |
|
20 Whitespace around the `=' and at the end of a value is ignored. |
|
21 Empty lines and lines starting with `#' or `;' will be ignored. |
|
22 .PP |
|
23 Each value uses one of the following data types: |
|
24 .TP 8 |
|
25 .I Boolean |
|
26 to indicate if something is enabled/activated (true) or |
|
27 disabled/deactivated (false). |
|
28 .br |
|
29 Accepted values for |
|
30 .I true |
|
31 are: |
|
32 .BR 1 , " yes" , " true" " and " on . |
|
33 .br |
|
34 Accepted values for |
|
35 .I false |
|
36 are: |
|
37 .BR 0 , " no" , " false" " and " off . |
|
38 .TP |
|
39 .I Int |
|
40 an integer number, written without a fractional or decimal component. |
|
41 .br |
|
42 For example |
|
43 .BR 1 , " 50" " or " 321 |
|
44 are integers. |
|
45 .TP |
|
46 .I String |
|
47 a sequence of characters and/or numbers. |
|
48 .br |
|
49 For example |
|
50 .RB ` word "', `" "hello world" "' or `" /usr/bin/strings ' |
|
51 are strings. |
|
52 .PP |
|
53 Most options have a default value, shown in parentheses after the option's |
|
54 name. |
|
55 In order to use a option's default setting, comment out the line, either |
|
56 with a |
|
57 .BR # " or " ; |
|
58 or simply remove the setting from |
|
59 .IR vmm.cfg . |
|
60 .PP |
|
61 A minimal |
|
62 .I vmm.cfg |
|
63 would be: |
|
64 .PP |
|
65 .nf |
|
66 [database] |
|
67 user = me |
|
68 pass = xxxxxxxx |
|
69 |
|
70 [misc] |
|
71 dovecot_version = 1.2.16 |
|
72 .fi |
|
73 .\" ----------------------------------------------------------------------- |
|
74 .SH SEARCH ORDER |
|
75 By default |
|
76 .BR vmm (1) |
|
77 looks for the |
|
78 .I vmm.cfg |
|
79 file in the following directories in the order listed: |
|
80 .RS |
|
81 .PD 0 |
|
82 .TP |
|
83 .I |
|
84 /root |
|
85 .TP |
|
86 .I |
|
87 /usr/local/etc |
|
88 .TP |
|
89 .I |
|
90 /etc |
|
91 .PD |
|
92 .RE |
|
93 .PP |
|
94 The first configuration file found will be used. |
|
95 .\" ----------------------------------------------------------------------- |
|
96 .SH SECTION ACCOUNT |
|
97 The options in the section |
|
98 .B account |
|
99 are used to specify user account related settings. |
|
100 .SS account.delete_directory |
|
101 .BR delete_directory " (default: false) :" |
|
102 .I Boolean |
|
103 .PP |
|
104 Determines the behavior of |
|
105 .BR vmm (1) |
|
106 when an account is deleted (userdelete). |
|
107 If this option is set to |
|
108 .I true |
|
109 the user's home directory will be deleted recursively. |
|
110 .\" ------------------------------------ |
|
111 .SS account.directory_mode |
|
112 .BR directory_mode " (default: 448) :" |
|
113 .I Int |
|
114 .PP |
|
115 Access mode for a user's home directory and all directories inside. |
|
116 The value has to be specified in decimal (base 10) notation. |
|
117 .br |
|
118 For example: `drwx\-\-\-\-\-\-' \(-> octal 0700 \(-> decimal 448 |
|
119 .\" ------------------------------------ |
|
120 .SS account.disk_usage |
|
121 .BR disk_usage " (default: false) :" |
|
122 .I Boolean |
|
123 .PP |
|
124 Determines whether the disk usage of a user's mail directory always should |
|
125 be summarized, using |
|
126 .BR du (1), |
|
127 and displayed with the account information (userinfo). |
|
128 .PP |
|
129 This could be slow on large Maildirs. |
|
130 When you have enabled quotas, |
|
131 .BR vmm 's |
|
132 userinfo subcommand will also display the current quota usage of the |
|
133 account. |
|
134 You may also use userinfo's optional details\-argument |
|
135 .BR du " or " full , |
|
136 in order to display the current disk usage of an account's mail directory. |
|
137 .\" ------------------------------------ |
|
138 .SS account.password_length |
|
139 .BR password_length " (default: 8) :" |
|
140 .I Int |
|
141 .PP |
|
142 Determines how many characters and/or numbers should be used for randomly |
|
143 generated passwords. |
|
144 Any value less than 8 will be increased to 8. |
|
145 .\" ------------------------------------ |
|
146 .SS account.random_password |
|
147 .BR random_password " (default: false) :" |
|
148 .I Boolean |
|
149 .PP |
|
150 Determines whether |
|
151 .BR vmm (1) |
|
152 should generate a random password when no password was given for the |
|
153 useradd subcommand. |
|
154 If this option is set to |
|
155 .I false |
|
156 .B vmm |
|
157 will prompt you to enter a password for the new account. |
|
158 .PP |
|
159 You can specify the password length of generated passwords with the |
|
160 .I account.password_length |
|
161 option. |
|
162 .\" ----------------------------------------------------------------------- |
|
163 .SH SECTION BIN |
|
164 The |
|
165 .B bin |
|
166 section is used to specify some paths to some binaries required by |
|
167 .BR vmm (1). |
|
168 .SS bin.dovecotpw |
|
169 .BR dovecotpw " (default: /usr/sbin/dovecotpw) :" |
|
170 .I String |
|
171 .PP |
|
172 The absolute path to the |
|
173 .BR dovecotpw (1) |
|
174 binary. |
|
175 Use the absolute path to the |
|
176 .BR doveadm (1) |
|
177 binary, if you are using Dovecot v2.0. |
|
178 .PP |
|
179 This binary is used to generate a password hash, if |
|
180 .I misc.password_scheme |
|
181 is set to one of `CRAM\-MD5', `HMAC\-MD5', `LANMAN', `OTP', `RPA' or |
|
182 `SKEY'. |
|
183 This binary will be also required if your Python installation doesn't |
|
184 support the: |
|
185 .IP \(bu 4 |
|
186 md4 hash algorithm (hashlib + OpenSSL or PyCrypto) used for the password |
|
187 schemes: `PLAIN\-MD4' and `NTLM' |
|
188 .IP \(bu |
|
189 sha256 hash algorithm (hashlib or PyCrypto \(>= 2.1.0alpha1) used for the |
|
190 password schemes: `SHA256' and `SSHA256' |
|
191 .IP \(bu |
|
192 sha512 hash algorithm (hashlib) used for the password schemes: `SHA512' and |
|
193 `SSHA512' |
|
194 .PP |
|
195 The |
|
196 .BR doveadm (1) |
|
197 binary is also used to create a user's INBOX and additional mailboxes |
|
198 .RI ( mailbox.folders ), |
|
199 when the |
|
200 .I mailbox.format |
|
201 is set to |
|
202 .BR mdbox " or " sdbox . |
|
203 .\" ------------------------------------ |
|
204 .SS bin.du |
|
205 .BR du " (default: /usr/bin/du) :" |
|
206 .I String |
|
207 .PP |
|
208 The absolute path to |
|
209 .BR du (1). |
|
210 This binary is used to summarize the disk usage of a user's mail directory. |
|
211 .\" ------------------------------------ |
|
212 .SS bin.postconf |
|
213 .BR postconf " (default: /usr/sbin/postconf) :" |
|
214 .I String |
|
215 .PP |
|
216 The absolute path to Postfix' |
|
217 .BR postconf (1). |
|
218 This binary is required when |
|
219 .BR vmm (1) |
|
220 has to check for some Postfix settings, e.g. the |
|
221 .IR virtual_alias_expansion_limit . |
|
222 .\" ----------------------------------------------------------------------- |
|
223 .SH SECTION DATABASE |
|
224 The |
|
225 .B database |
|
226 section is used to specify some options required to connect to the |
|
227 database. |
|
228 .SS database.host |
|
229 .BR host " (default: localhost) :" |
|
230 .I String |
|
231 .PP |
|
232 Hostname or IP address of the database server. |
|
233 .\" ------------------------------------ |
|
234 .SS database.module |
|
235 .BR module " (default: psycopg2) :" |
|
236 .I String |
|
237 .PP |
|
238 The Python PostgreSQL database adapter module to be used. |
|
239 Supported modules are |
|
240 .BR psycopg2 " and " pyPgSQL . |
|
241 .\" ------------------------------------ |
|
242 .SS database.name |
|
243 .BR name " (default: mailsys) :" |
|
244 .I String |
|
245 .PP |
|
246 Name of the database. |
|
247 .\" ------------------------------------ |
|
248 .SS database.pass |
|
249 .BR pass " (default: " None ") :" |
|
250 .I String |
|
251 .PP |
|
252 Database password. |
|
253 .\" ------------------------------------ |
|
254 .SS database.port |
|
255 .BR port " (default: 5432) :" |
|
256 .I Int |
|
257 .PP |
|
258 The TCP port, on which the database server is listening for connections. |
|
259 .\" ------------------------------------ |
|
260 .SS database.sslmode |
|
261 .BR sslmode " (default: prefer) :" |
|
262 .I String |
|
263 .PP |
|
264 Determines whether and with what priority an SSL connection will be |
|
265 negotiated with the database server. |
|
266 Possible values are: |
|
267 .BR disabled ", " allow ", " prefer ", " require ", " verify\-ca " and " |
|
268 .BR verify\-full . |
|
269 The modes |
|
270 .BR verify\-ca " and " verify\-full |
|
271 are available since PostgreSQL 8.4 |
|
272 .PP |
|
273 This setting will be ignored when the |
|
274 .I database.module |
|
275 is set to |
|
276 .BR pyPgSQL . |
|
277 .\" ------------------------------------ |
|
278 .SS database.user |
|
279 .BR user " (default: " None ") :" |
|
280 .I String |
|
281 .PP |
|
282 Name of the database user. |
|
283 .\" ----------------------------------------------------------------------- |
|
284 .SH SECTION DOMAIN |
|
285 The |
|
286 .B domain |
|
287 section specifies some domain related settings. |
|
288 .PP |
|
289 The quota limit (quota_bytes and quota_messages), service settings (imap, |
|
290 pop3, sieve and smtp) and the transport setting will be applied when a |
|
291 domain is created. |
|
292 In order to modify those settings for an existing domain, use one of |
|
293 the following |
|
294 .BR vmm (1) |
|
295 subcommands: |
|
296 .PP |
|
297 .TP |
|
298 .B domainquota |
|
299 in order to update a domain's quota limit |
|
300 .TP |
|
301 .B domainservices |
|
302 in order to assign a different service set to a domain |
|
303 .TP |
|
304 .B domaintransport |
|
305 in order to set a new default domain transport |
|
306 .PP |
|
307 When an account is created, it inherits all the settings of the domain |
|
308 to which it is added. |
|
309 Different settings for an existing account can be set using the subcommands |
|
310 .BR userquota ", " userservices " and " usertransport . |
|
311 .\" ------------------------------------ |
|
312 .SS domain.auto_postmaster |
|
313 .BR auto_postmaster " (default: true) :" |
|
314 .I Boolean |
|
315 .PP |
|
316 Determines if |
|
317 .BR vmm (1) |
|
318 should create also a postmaster account when a new domain is created |
|
319 (domainadd). |
|
320 .\" ------------------------------------ |
|
321 .SS domain.delete_directory |
|
322 .BR delete_directory " (default: false) :" |
|
323 .I Boolean |
|
324 .PP |
|
325 Specifies whether the domain directory and all user directories inside |
|
326 should be deleted when a domain is deleted (domaindelete). |
|
327 .\" ------------------------------------ |
|
328 .SS domain.directory_mode |
|
329 .BR directory_mode " (default: 504) :" |
|
330 .I Int |
|
331 .PP |
|
332 Access mode for the domain directory in decimal (base 10) notation. |
|
333 .br |
|
334 For example: `drwxrwx\-\-\-' \(-> octal 0770 \(-> decimal 504 |
|
335 .\" ------------------------------------ |
|
336 .SS domain.force_deletion |
|
337 .BR force_deletion " (default: false) :" |
|
338 .I Boolean |
|
339 .PP |
|
340 Force the deletion of accounts and aliases when a domain is deleted |
|
341 (domaindelete). |
|
342 .\" ------------------------------------ |
|
343 .SS domain.imap |
|
344 .BR imap " (default: true) :" |
|
345 .I Boolean |
|
346 .PP |
|
347 Determines whether newly created users can log in via IMAP. |
|
348 .\" ------------------------------------ |
|
349 .SS domain.pop3 |
|
350 .BR pop3 " (default: true) :" |
|
351 .I Boolean |
|
352 .PP |
|
353 Determines whether newly created users can log in via POP3. |
|
354 .\" ------------------------------------ |
|
355 .SS domain.quota_bytes |
|
356 .BR quota_bytes " (default: 0) :" |
|
357 .I String |
|
358 .PP |
|
359 Quota limit in bytes. |
|
360 0 means unlimited. |
|
361 This limit will be applied to all newly created domains. |
|
362 .PP |
|
363 The option's value can be written as an integer value, e.g.: |
|
364 .BR 20480 . |
|
365 It's also possible to append one of the following prefixes to the limit: |
|
366 .BR b " (bytes), " k " (kilobytes), " M " (megabytes) or " G |
|
367 (gigabytes). |
|
368 .br |
|
369 1024 is the same as 1024b or 1k. |
|
370 .\" ------------------------------------ |
|
371 .SS domain.quota_messages |
|
372 .BR quota_messages " (default: 0) :" |
|
373 .I Int |
|
374 .PP |
|
375 Quota limit in number of messages. |
|
376 0 means unlimited. |
|
377 This limit will be applied to all newly created domains. |
|
378 .\" ------------------------------------ |
|
379 .SS domain.sieve |
|
380 .BR sieve " (default: true) :" |
|
381 .I Boolean |
|
382 .PP |
|
383 Determines whether newly created users can log in via SIEVE (ManageSieve). |
|
384 .\" ------------------------------------ |
|
385 .SS domain.smtp |
|
386 .BR smtp " (default: true) :" |
|
387 .I Boolean |
|
388 .PP |
|
389 Determines whether newly created users can log in via SMTP (SMTP AUTH). |
|
390 .\" ------------------------------------ |
|
391 .SS domain.transport |
|
392 .BR transport " (default: dovecot:) :" |
|
393 .I String |
|
394 .PP |
|
395 Default transport for domains and accounts. |
|
396 For details see |
|
397 .BR transport (5). |
|
398 .\" ----------------------------------------------------------------------- |
|
399 .SH SECTION MAILBOX |
|
400 The |
|
401 .B mailbox |
|
402 section is used to specify some options for new created mailboxes in the |
|
403 users home directories. |
|
404 The INBOX will be created always. |
|
405 .SS mailbox.folders |
|
406 .BR folders " (default: Drafts:Sent:Templates:Trash) :" |
|
407 .I String |
|
408 .PP |
|
409 A colon separated list of mailboxes that should be created. |
|
410 If no additionally mailboxes should be created, set the value of this |
|
411 option to a single colon |
|
412 .RB (` : '). |
|
413 .PP |
|
414 If you want to create folders containing one or more subfolders, separate |
|
415 them with a single dot |
|
416 .RB (` . '). |
|
417 .PP |
|
418 If you want to use internationalized mailbox names (e.g. `Wysłane' or |
|
419 `Gelöschte Objekte'), write their names UTF\-8 encoded. |
|
420 .BR vmm (1) |
|
421 will convert internationalized mailbox names to a modified version of the |
|
422 UTF\-7 encoding (see also: RFC 3501, section 5.1.3). |
|
423 .\" ------------------------------------ |
|
424 .SS mailbox.format |
|
425 .BR format " (default: maildir) :" |
|
426 .I String |
|
427 .PP |
|
428 The mailbox format to be used for a user's mailbox. |
|
429 Depending on the used Dovecot version |
|
430 .RI ( misc.dovecot_version ) |
|
431 .BR vmm (1) |
|
432 supports up to three formats: |
|
433 .TP 8 |
|
434 .B maildir |
|
435 Dovecot \(>= v1.0.0 |
|
436 .TP |
|
437 .B mdbox |
|
438 Dovecot \(>= v2.0.beta5 |
|
439 .TP |
|
440 .B sdbox |
|
441 Dovecot \(>= v2.0.rc3 |
|
442 .\" ------------------------------------ |
|
443 .SS mailbox.root |
|
444 .BR root " (default: Maildir) :" |
|
445 .I String |
|
446 .PP |
|
447 Name of the mailbox root directory in a user's home directory. |
|
448 Commonly used names, depending on the used |
|
449 .IR mailbox.format , |
|
450 are |
|
451 .BR Maildir ", " mdbox " or " sdbox . |
|
452 .\" ------------------------------------ |
|
453 .SS mailbox.subscribe |
|
454 .BR subscribe " (default: true) :" |
|
455 .I Boolean |
|
456 .PP |
|
457 When this option is set to |
|
458 .BR true , |
|
459 the mailboxes from the |
|
460 .I mailbox.folders |
|
461 option will be listed in the user's subscriptions file. |
|
462 If you don't want to subscribe the created mailboxes, set this option to |
|
463 .BR false . |
|
464 .\" ----------------------------------------------------------------------- |
|
465 .SH SECTION MISC |
|
466 The |
|
467 .I misc |
|
468 section is used to define miscellaneous settings. |
|
469 .SS misc.base_directory |
|
470 .BR base_directory " (default: /srv/mail) :" |
|
471 .I String |
|
472 .PP |
|
473 All domain directories will be created inside this directory. |
|
474 .\" ------------------------------------ |
|
475 .SS misc.crypt_blowfish_rounds |
|
476 .BR crypt_blowfish_rounds " (default: 5) :" |
|
477 .I Int |
|
478 .PP |
|
479 Number of encryption rounds for the |
|
480 .I password_scheme |
|
481 .BR BLF\-CRYPT . |
|
482 .PP |
|
483 The value must be in range |
|
484 .BR 4 " \- " 31 . |
|
485 .\" ------------------------------------ |
|
486 .SS misc.crypt_sha256_rounds |
|
487 .BR crypt_sha256_rounds " (default: 5000) :" |
|
488 .I Int |
|
489 .PP |
|
490 Number of encryption rounds for the |
|
491 .I password_scheme |
|
492 .BR SHA256\-CRYPT . |
|
493 .PP |
|
494 The value must be in range |
|
495 .BR 1000 " \- " 999999999 . |
|
496 .\" ------------------------------------ |
|
497 .SS misc.crypt_sha512_rounds |
|
498 .BR crypt_sha512_rounds " (default: 5000) :" |
|
499 .I Int |
|
500 .PP |
|
501 Number of encryption rounds for the |
|
502 .I password_scheme |
|
503 .BR SHA512\-CRYPT . |
|
504 .PP |
|
505 The value must be in range |
|
506 .BR 1000 " \- " 999999999 . |
|
507 .\" ------------------------------------ |
|
508 .SS misc.dovecot_version |
|
509 .BR dovecot_version " (default: " None ") :" |
|
510 .I String |
|
511 .PP |
|
512 The version number of the currently used Dovecot version. |
|
513 (see: |
|
514 .BR "dovecot \-\-version" ) |
|
515 .br |
|
516 When, for example, the command |
|
517 .B dovecot \-\-version |
|
518 prints |
|
519 .IR "2.0.beta4 (8818db00d347)" , |
|
520 set the value of this option to |
|
521 .BR 2.0.beta4 . |
|
522 .\" ------------------------------------ |
|
523 .SS misc.password_scheme |
|
524 .BR password_scheme " (default: CRAM\-MD5) :" |
|
525 .I String |
|
526 .PP |
|
527 Password scheme to use. |
|
528 To get a list of all usable password schemes execute the command |
|
529 .BR "vmm lp" . |
|
530 .PP |
|
531 With Dovecot \(>= v1.1.alpha1 it is also possible to append an encoding |
|
532 suffix to the password_scheme. |
|
533 Supported encoding suffixes are: |
|
534 .BR .b64 ", " .base64 " and " .hex . |
|
535 For example: PLAIN.BASE64 |
|
536 .IP Note: |
|
537 When setting another password scheme than |
|
538 .BR PLAIN " or " CRAM\-MD5 , |
|
539 you have to remove |
|
540 .B cram\-md5 |
|
541 from the |
|
542 .I auth_mechanisms |
|
543 setting in your |
|
544 .IR dovecot/conf.d/10\-auth.conf . |
|
545 .\" ----------------------------------------------------------------------- |
|
546 .SH EXAMPLE |
|
547 An example configuration. |
|
548 All options that are not listed in the configuration file will have their |
|
549 default values. |
|
550 .PP |
|
551 .nf |
|
552 [account] |
|
553 password_length = 10 |
|
554 random_password = true |
|
555 |
|
556 [bin] |
|
557 dovecotpw = /usr/bin/doveadm |
|
558 |
|
559 [database] |
|
560 host = dbsrv8.example.net |
|
561 pass = PY_SRJ}L/0p\-oOk |
|
562 port = 5433 |
|
563 sslmode = require |
|
564 user = vmm |
|
565 |
|
566 [domain] |
|
567 quota_bytes = 500M |
|
568 quota_messages = 10000 |
|
569 transport = lmtp:unix:private/dovecot\-lmtp |
|
570 |
|
571 [mailbox] |
|
572 folders = Drafts:Sent:Templates:Trash:Lists.Dovecot:Lists.Postfix |
|
573 |
|
574 [misc] |
|
575 crypt_sha512_rounds = 10000 |
|
576 dovecot_version = 2.0.beta4 |
|
577 password_scheme = SHA512\-CRYPT.hex |
|
578 .fi |
|
579 .\" ----------------------------------------------------------------------- |
|
580 .SH SEE ALSO |
|
581 .BR postconf (1), |
|
582 .BR vmm (1), |
|
583 .BR transport (5) |
|
584 .\" ----------------------------------------------------------------------- |
|
585 .SH INTERNET RESOURCES |
|
586 .TP |
|
587 Homepage |
|
588 http://vmm.localdomain.org/ |
|
589 .TP |
|
590 Project site |
|
591 http://sf.net/projects/vmm/ |
|
592 .TP |
|
593 Bug tracker |
|
594 https://bitbucket.org/pvo/vmm/issues |
|
595 .\" ----------------------------------------------------------------------- |
|
596 .SH COPYING |
|
597 vmm and its manual pages were written by Pascal Volk <user+vmm AT |
|
598 localhost.localdomain.org> and are licensed under the terms of the BSD |
|
599 License. |
|