man/man5/vmm.cfg.5.rst
branchv0.6.x
changeset 412 65687300ba19
parent 411 1ca025a5ce0c
child 413 e5b3b225bd5b
equal deleted inserted replaced
411:1ca025a5ce0c 412:65687300ba19
     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