1 ========= |
|
2 vmm.cfg |
|
3 ========= |
|
4 |
|
5 -------------------------- |
|
6 configuration file for vmm |
|
7 -------------------------- |
|
8 |
|
9 :Author: Pascal Volk <neverseen@users.sourceforge.net> |
|
10 :Date: |today| |
|
11 :Version: vmm-0.6.0 |
|
12 :Manual group: vmm Manual |
|
13 :Manual section: 5 |
|
14 |
|
15 .. contents:: |
|
16 :backlinks: top |
|
17 :class: htmlout |
|
18 |
|
19 SYNOPSIS |
|
20 ======== |
|
21 vmm.cfg |
|
22 |
|
23 |
|
24 DESCRIPTION |
|
25 =========== |
|
26 |vmm(1)|_ reads its configuration data from *vmm.cfg*. |
|
27 |
|
28 The configuration file is split into multiple sections. A section starts with |
|
29 the section name, enclosed in square brackets '**[**' and '**]**', followed |
|
30 by '*option* = *value*' pairs. |
|
31 |
|
32 Whitespace around the '=' and at the end of a value is ignored. |
|
33 |
|
34 Empty lines and lines starting with '#' or ';' will be ignored. |
|
35 |
|
36 Each value uses one of the following data types: |
|
37 |
|
38 * *Boolean* to indicate if something is enabled/activated (true) or |
|
39 disabled/deactivated (false). |
|
40 |
|
41 | Accepted values for *true* are: **1**, **yes**, **true** and **on**. |
|
42 | Accepted values for *false* are: **0**, **no**, **false** and **off**. |
|
43 |
|
44 * *Int* an integer number, written without a fractional or decimal component. |
|
45 |
|
46 | For example **1**, **50** or **321** are integers. |
|
47 |
|
48 * *String* a sequence of characters and numbers. |
|
49 |
|
50 | For example '**word**', '**hello world**' or '**/usr/bin/strings**' |
|
51 |
|
52 Most options have a default value, shown in parentheses after the option's |
|
53 name. In order to use a option's default setting, comment out the line, |
|
54 either with a **#** or **;** or simply remove the setting from *vmm.cfg*. |
|
55 |
|
56 A minimal *vmm.cfg* would be:: |
|
57 |
|
58 [database] |
|
59 user = me |
|
60 pass = xxxxxxxx |
|
61 |
|
62 [misc] |
|
63 dovecot_version = 1.2.11 |
|
64 |
|
65 |
|
66 SEARCH ORDER |
|
67 ------------- |
|
68 By default |vmm(1)|_ looks for *vmm.cfg* in the following directories in the |
|
69 order listed: |
|
70 |
|
71 | */root* |
|
72 | */usr/local/etc* |
|
73 | */etc* |
|
74 |
|
75 The first configuration file found will be used. |
|
76 |
|
77 |
|
78 SECTIONS |
|
79 ======== |
|
80 This section describes all sections and their options of the *vmm.cfg*. |
|
81 |
|
82 |
|
83 ACCOUNT |
|
84 ------- |
|
85 The options in the section **account** are used to specify user account |
|
86 related settings. |
|
87 |
|
88 .. _account.delete_directory: |
|
89 |
|
90 ``delete_directory (default: false)`` : *Boolean* |
|
91 Determines the behavior of |vmm(1)|_ when an account is deleted |
|
92 (|userdelete|_). If this option is set to *true* the user's home directory |
|
93 will be deleted recursively. |
|
94 |
|
95 .. _account.directory_mode: |
|
96 |
|
97 ``directory_mode (default: 448)`` : *Int* |
|
98 Access mode for a user's home directory and all directories inside. The |
|
99 value has to be specified in decimal (base 10) notation. |
|
100 |
|
101 | For example: 'drwx------' -> octal 0700 -> decimal 448 |
|
102 |
|
103 .. _account.disk_usage: |
|
104 |
|
105 ``disk_usage (default: false)`` : *Boolean* |
|
106 Determines whether the disk usage of a user's Maildir always should be |
|
107 summarized, using **du**\(1), and displayed with account information. |
|
108 |
|
109 This could be slow on large Maildirs. When you have enabled quotas, |
|
110 **vmm**'s |userinfo|_ subcomammand will also display the current quota |
|
111 usage of the account. You may also use |userinfo|_'s optional argument |
|
112 **du** or **full**, in order to display the current disk usage of an |
|
113 account's Maildir. |
|
114 |
|
115 .. _account.imap: |
|
116 |
|
117 ``imap (default: true)`` : *Boolean* |
|
118 Determines whether a newly created user can log in via IMAP. |
|
119 |
|
120 .. _account.password_length: |
|
121 |
|
122 ``password_length (default: 8)`` : *Int* |
|
123 Determines how many characters and/or numbers should be used for randomly |
|
124 generated passwords. Any value less than 8 will be increased to 8. |
|
125 |
|
126 .. _account.pop3: |
|
127 |
|
128 ``pop3 (default: true)`` : *Boolean* |
|
129 Determines whether a newly created user can log in via POP3. |
|
130 |
|
131 .. _account.random_password: |
|
132 |
|
133 ``random_password (default: false)`` : *Boolean* |
|
134 Determines whether **vmm** should generate a random password when no |
|
135 password was given for the |useradd|_ subcommand. If this option is set to |
|
136 *false* **vmm** will prompt you to enter a password for the new account. |
|
137 |
|
138 You can specify the password length of generated passwords with the |
|
139 |account.password_length|_ option. |
|
140 |
|
141 .. _account.sieve: |
|
142 |
|
143 ``sieve (default: true)`` : *Boolean* |
|
144 Determines whether a newly created user can log in via ManageSieve. |
|
145 |
|
146 .. _account.smtp: |
|
147 |
|
148 ``smtp (default: true)`` : *Boolean* |
|
149 Determines whether a newly created user can log in via SMTP (SMTP AUTH). |
|
150 |
|
151 Example:: |
|
152 |
|
153 [account] |
|
154 delete_directory = false |
|
155 directory_mode = 448 |
|
156 disk_usage = false |
|
157 random_password = true |
|
158 password_length = 10 |
|
159 smtp = true |
|
160 pop3 = true |
|
161 imap = true |
|
162 sieve = true |
|
163 |
|
164 |
|
165 BIN |
|
166 --- |
|
167 The **bin** section is used to specify some paths to some binaries required |
|
168 by |vmm(1)|_. |
|
169 |
|
170 .. _bin.dovecotpw: |
|
171 |
|
172 ``dovecotpw (default: /usr/sbin/dovecotpw)`` : *String* |
|
173 The absolute path to the dovecotpw binary. Use the absolute path to the |
|
174 **doveadm**\(1) binary, if you are using Dovecot v2.0. This binary is used |
|
175 to generate a password hash, if |misc.password_scheme|_ is set to one of |
|
176 'CRAM-MD5', 'HMAC-MD5', 'LANMAN', 'OTP', 'RPA' or 'SKEY'. This binary will |
|
177 be also required if your Python installation doesn't support the: |
|
178 |
|
179 * md4 hash algorithm (hashlib + OpenSSL or PyCrypto) used for the password |
|
180 schemes: 'PLAIN-MD4' and 'NTLM' |
|
181 * sha256 hash algorithm (hashlib or PyCrypto >= 2.1.0alpha1) used for the |
|
182 password schemes: 'SHA256' and 'SSHA256' |
|
183 * sha512 hash algorithm (hashlib) used for the password schemes 'SHA512' |
|
184 and 'SSHA512' |
|
185 |
|
186 .. _bin.du: |
|
187 |
|
188 ``du (default: /usr/bin/du)`` : *String* |
|
189 The absolute path to **du**\(1). This binary is used to summarize the disk |
|
190 usage of a user's Maildir. |
|
191 |
|
192 .. _bin.postconf: |
|
193 |
|
194 ``postconf (default: /usr/sbin/postconf)`` : *String* |
|
195 The absolute path to Postfix' |postconf(1)|_. This binary is required when |
|
196 |vmm(1)|_ has to check for some Postfix settings, e.g. |
|
197 |virtual_alias_expansion_limit|_. |
|
198 |
|
199 Example:: |
|
200 |
|
201 [bin] |
|
202 dovecotpw = /usr/sbin/dovecotpw |
|
203 du = /usr/bin/du |
|
204 postconf = /usr/sbin/postconf |
|
205 |
|
206 |
|
207 DATABASE |
|
208 -------- |
|
209 The **database** section is used to specify some options required to |
|
210 connect to the database. |
|
211 |
|
212 .. _database.host: |
|
213 |
|
214 ``host (default: localhost)`` : *String* |
|
215 Hostname or IP address of the database server. |
|
216 |
|
217 .. _database.module: |
|
218 |
|
219 ``module (default: psycopg2)`` : *String* |
|
220 The Python PostgreSQL database adapter module to be used. Supported modules |
|
221 are **psycopg2** and **pyPgSQL**. |
|
222 |
|
223 .. _database.name: |
|
224 |
|
225 ``name (default: mailsys)`` : *String* |
|
226 Name of the database. |
|
227 |
|
228 .. _database.pass: |
|
229 |
|
230 ``pass (default: None)`` : *String* |
|
231 Database password. |
|
232 |
|
233 .. _database.port: |
|
234 |
|
235 ``port (default: 5432)`` : *Int* |
|
236 The TCP port, on which the database server is listening for connections. |
|
237 |
|
238 .. _database.sslmode: |
|
239 |
|
240 ``sslmode (default: prefer)`` : *String* |
|
241 Determines whether and with what priority an SSL connection will be |
|
242 negotiated with the database server. Possible values are: **disabled**, |
|
243 **allow**, **prefer**, **require**, **verify-ca**, and **verify-full**. |
|
244 The modes **verify-ca** and **verify-full** are available since PostgreSQL |
|
245 8.4. |
|
246 |
|
247 This setting will be ignored when the pyPgSQL *module* is used. |
|
248 |
|
249 .. _database.user: |
|
250 |
|
251 ``user (default: None)`` : *String* |
|
252 Name of the database user. |
|
253 |
|
254 Example:: |
|
255 |
|
256 [database] |
|
257 host = dbsrv8.example.net |
|
258 port 5433 |
|
259 sslmode = require |
|
260 user = vmm |
|
261 pass = PY_SRJ}L/0p-oOk |
|
262 name = mailsys |
|
263 |
|
264 |
|
265 DOMAIN |
|
266 ------ |
|
267 The **domain** section specifies some domain related settings. |
|
268 |
|
269 .. _domain.auto_postmaster: |
|
270 |
|
271 ``auto_postmaster (default: true)`` : *Boolean* |
|
272 Determines if |vmm(1)|_ should create also a postmaster account when a new |
|
273 domain is created (|domainadd|_). |
|
274 |
|
275 .. _domain.delete_directory: |
|
276 |
|
277 ``delete_directory (default: false)`` : *Boolean* |
|
278 Specifies whether the domain directory and all user directories inside |
|
279 should be deleted when a domain is deleted (|domaindelete|_). |
|
280 |
|
281 .. _domain.directory_mode: |
|
282 |
|
283 ``directory_mode (default: 504)`` : *Int* |
|
284 Access mode for the domain directory in decimal (base 10) notation. |
|
285 |
|
286 | For example: 'drwxrwx---' -> octal 0770 -> decimal 504 |
|
287 |
|
288 .. _domain.force_deletion: |
|
289 |
|
290 ``force_deletion (default: false)`` : *Boolean* |
|
291 Force deletion of accounts and aliases when a domain is deleted |
|
292 (|domaindelete|_). |
|
293 |
|
294 Example:: |
|
295 |
|
296 [domain] |
|
297 auto_postmaster = true |
|
298 delete_directory = false |
|
299 directory_mode = 504 |
|
300 force_deletion = false |
|
301 |
|
302 |
|
303 MAILBOX |
|
304 ------- |
|
305 The **mailbox** section is used to specify some options for new created |
|
306 mailboxes in the users home directories. The INBOX will be created always. |
|
307 |
|
308 .. _mailbox.folders: |
|
309 |
|
310 ``folders (default: Drafts:Sent:Templates:Trash)`` : *String* |
|
311 A colon separated list of mailboxes that should be created. If no |
|
312 additionally mailboxes should be created, set the value of this option to a |
|
313 single colon ('**:**'). |
|
314 |
|
315 If you want to create folders containing one or more subfolders, separate |
|
316 them with a single dot ('**.**'). |
|
317 |
|
318 If you want to use internationalized mailbox names (e.g. 'Wysłane' or |
|
319 'Gelöschte Objekte'), write their names UTF-8 encoded. |vmm(1)|_ will convert |
|
320 internationalized mailbox names to a modified version of the UTF-7 encoding |
|
321 (see also: :RFC:`3501`, section 5.1.3). |
|
322 |
|
323 .. _mailbox.format: |
|
324 |
|
325 ``format (default: maildir)`` : *String* |
|
326 The mailbox format to be used for a user's mailbox. Depending on the used |
|
327 Dovecot version there are up to three supported formats: |
|
328 |
|
329 ``maildir`` |
|
330 since Dovecot v1.0.0 |
|
331 ``mdbox`` |
|
332 since Dovecot v2.0.beta5 |
|
333 ``sdbox`` |
|
334 since Dovecot v2.0.rc3 |
|
335 |
|
336 .. _mailbox.root: |
|
337 |
|
338 ``root (default: Maildir)`` : *String* |
|
339 Name of the mailbox root directory in a user's home directory. Commonly used |
|
340 names, depending on the used |mailbox.format|_, are **Maildir**, **mdbox** |
|
341 or **sdbox**. |
|
342 |
|
343 .. _mailbox.subscribe: |
|
344 |
|
345 ``subscribe (default: true)`` : *Boolean* |
|
346 When this option is set to **true**, the mailboxes from the |
|
347 |mailbox.folders|_ option will be listed in the user's subscriptions file. |
|
348 If you don't want to subscribe the created mailboxes, set this option to |
|
349 **false**. |
|
350 |
|
351 Example:: |
|
352 |
|
353 [mailbox] |
|
354 folders = Drafts:Sent:Templates:Trash:Lists.Dovecot:Lists.Postfix |
|
355 format = maildir |
|
356 root = Maildir |
|
357 subscribe = false |
|
358 |
|
359 |
|
360 MISC |
|
361 ---- |
|
362 The **misc** section is used to define miscellaneous settings. |
|
363 |
|
364 .. _misc.base_directory: |
|
365 |
|
366 ``base_directory (default: /srv/mail)`` : *String* |
|
367 All domain directories will be created inside this directory. |
|
368 |
|
369 .. _misc.crypt_blowfish_rounds: |
|
370 |
|
371 ``crypt_blowfish_rounds (default: 5)`` : *Int* |
|
372 Number of encryption rounds for the *password_scheme* **BLF-CRYPT**. |
|
373 |
|
374 The value must be in range **4** - **31**. |
|
375 |
|
376 .. _misc.crypt_sha256_rounds: |
|
377 |
|
378 ``crypt_sha256_rounds (default: 5000)`` : *Int* |
|
379 Number of encryption rounds for the *password_scheme* **SHA256-CRYPT**. |
|
380 |
|
381 The value must be in range **1000** - **999999999**. |
|
382 |
|
383 .. _misc.crypt_sha512_rounds: |
|
384 |
|
385 ``crypt_sha512_rounds (default: 5000)`` : *Int* |
|
386 Number of encryption rounds for the *password_scheme* **SHA512-CRYPT**. |
|
387 |
|
388 The value must be in range **1000** - **999999999**. |
|
389 |
|
390 .. _misc.password_scheme: |
|
391 |
|
392 ``password_scheme (default: CRAM-MD5)`` : *String* |
|
393 Password scheme to use. To get a list of all available password schemes |
|
394 execute the command **dovecotpw -l** (Dovecot v1.x) or **doveadm pw -l** |
|
395 (Dovecot v2.0). |
|
396 |
|
397 .. _misc.quota_bytes: |
|
398 |
|
399 ``quota_bytes (default: 0)`` : *String* |
|
400 Quota limit in bytes. 0 means unlimited. This limit will be applied to |
|
401 all newly created domains. |
|
402 |
|
403 The option's value can be written as an integer value, e.g.: **20480**. |
|
404 Its also possible to append one of the following suffixes to the limit: |
|
405 **b** (bytes), **k** (kilobytes), **M** (megabytes) or **G** (gigabytes). |
|
406 **1024** is the same as **1024b** or **1k**. |
|
407 |
|
408 .. _misc.quota_messages: |
|
409 |
|
410 ``quota_messages (default: 0)`` : *Int* |
|
411 Quota limit in number of messages. 0 means unlimited. This limit will be |
|
412 applied to all newly created domains. |
|
413 |
|
414 .. _misc.transport: |
|
415 |
|
416 ``transport (default: dovecot:)`` : *String* |
|
417 Default transport for domains and accounts. For details see |
|
418 |transport(5)|_. |
|
419 |
|
420 .. _misc.dovecot_version: |
|
421 |
|
422 ``dovecot_version (default: None)`` : *String* |
|
423 The version number of the currently used Dovecot version. |
|
424 (see: **dovecot --version**). |
|
425 |
|
426 When, for example, the command **dovecot --version** prints |
|
427 *2.0.beta4 (8818db00d347)*, set the value of this option to **2.0.beta4**. |
|
428 |
|
429 Example:: |
|
430 |
|
431 [misc] |
|
432 base_directory = /srv/mail |
|
433 crypt_sha512_rounds = 10000 |
|
434 password_scheme = SHA512-CRYPT |
|
435 transport = dovecot: |
|
436 dovecot_version = 2.0.beta4 |
|
437 quota_bytes = 100M |
|
438 quota_messages = 10000 |
|
439 |
|
440 |
|
441 FILES |
|
442 ===== |
|
443 */root/vmm.cfg* |
|
444 | will be used when found. |
|
445 */usr/local/etc/vmm.cfg* |
|
446 | will be used when the above file doesn't exist. |
|
447 */etc/vmm.cfg* |
|
448 | will be used when none of the both above mentioned files exists. |
|
449 |
|
450 |
|
451 SEE ALSO |
|
452 ======== |
|
453 |vmm(1)|_ |
|
454 |
|
455 |
|
456 COPYING |
|
457 ======= |
|
458 vmm and its manual pages were written by Pascal Volk and are licensed under |
|
459 the terms of the BSD License. |
|
460 |
|
461 .. include:: ../substitute_links.rst |
|
462 .. include:: ../substitute_links_5.rst |
|