=========

 vmm.cfg

=========

--------------------------

configuration file for vmm

--------------------------

:Author:         Pascal Volk <neverseen@users.sourceforge.net>

:Date:           |today|

:Version:        vmm-0.6.0

:Manual group:   vmm Manual

:Manual section: 5

.. contents::

  :backlinks: top

  :class: htmlout

SYNOPSIS

========

vmm.cfg

DESCRIPTION

===========

|vmm(1)|_ reads its configuration data from *vmm.cfg*.

The configuration file is split into multiple sections. A section starts with

the section name, enclosed in square brackets '**[**' and '**]**', followed

by '*option* = *value*' pairs.

Whitespace around the '=' and at the end of a value is ignored.

Empty lines and lines starting with '#' or ';' will be ignored.

Each value uses one of the following data types:

* *Boolean* to indicate if something is enabled/activated (true) or

  disabled/deactivated (false).

  | Accepted values for *true* are: **1**, **yes**, **true** and **on**.

  | Accepted values for *false* are: **0**, **no**, **false** and **off**.

* *Int* an integer number, written without a fractional or decimal component.

  | For example **1**, **50** or **321** are integers.

* *String* a sequence of characters and numbers.

  | For example '**word**', '**hello world**' or '**/usr/bin/strings**'

Most options have a default value, shown in parentheses after the option's

name. In order to use a option's default setting, comment out the line,

either with a **#** or **;** or simply remove the setting from *vmm.cfg*.

A minimal *vmm.cfg* would be::

  [database]

  user = me

  pass = xxxxxxxx

  [misc]

  dovecot_version = 1.2.11

SEARCH ORDER

-------------

By default |vmm(1)|_ looks for *vmm.cfg* in the following directories in the

order listed:

  | */root*

  | */usr/local/etc*

  | */etc*

The first configuration file found will be used.

SECTIONS

========

This section describes all sections and their options of the *vmm.cfg*.

ACCOUNT

-------

The options in the section **account** are used to specify user account

related settings.

.. _account.delete_directory:

``delete_directory (default: false)`` : *Boolean*

  Determines the behavior of |vmm(1)|_ when an account is deleted

  (|userdelete|_). If this option is set to *true* the user's home directory

  will be deleted  recursively.

.. _account.directory_mode:

``directory_mode (default: 448)`` : *Int*

  Access mode for a user's home directory and all directories inside. The

  value has to be specified in decimal (base 10) notation.

  | For example: 'drwx------' -> octal 0700 -> decimal 448

.. _account.disk_usage:

``disk_usage (default: false)`` : *Boolean*

  Determines whether the disk usage of a user's Maildir always should be

  summarized, using **du**\(1), and displayed with account information.

  This could be slow on large Maildirs. When you have enabled quotas,

  **vmm**'s |userinfo|_ subcomammand will also display the current quota

  usage of the account. You may also use |userinfo|_'s optional argument

  **du** or **full**, in order to display the current disk usage of an

  account's Maildir.

.. _account.imap:

``imap (default: true)`` : *Boolean*

  Determines whether a newly created user can log in via IMAP.

.. _account.password_length:

``password_length (default: 8)`` : *Int*

  Determines how many characters and/or numbers should be used for randomly

  generated passwords. Any value less than 8 will be increased to 8.

.. _account.pop3:

``pop3 (default: true)`` : *Boolean*

    Determines whether a newly created user can log in via POP3.

.. _account.random_password:

``random_password (default: false)`` : *Boolean*

  Determines whether **vmm** should generate a random password when no

  password was given for the |useradd|_ subcommand. If this option is set to

  *false* **vmm** will prompt you to enter a password for the new account.

  You can specify the password length of generated passwords with the

  |account.password_length|_ option.

.. _account.sieve:

``sieve (default: true)`` : *Boolean*

  Determines whether a newly created user can log in via ManageSieve.

.. _account.smtp:

``smtp (default: true)`` : *Boolean*

  Determines whether a newly created user can log in via SMTP (SMTP AUTH).

Example::

  [account]

  delete_directory = false

  directory_mode = 448

  disk_usage = false

  random_password = true

  password_length = 10

  smtp = true

  pop3 = true

  imap = true

  sieve = true

BIN

---

The **bin** section is used to specify some paths to some binaries required

by |vmm(1)|_.

.. _bin.dovecotpw:

``dovecotpw (default: /usr/sbin/dovecotpw)`` : *String*

  The absolute path to the dovecotpw binary. Use the absolute path to the

  **doveadm**\(1) binary, if you are using Dovecot v2.0. This binary is used

  to generate a password hash, if |misc.password_scheme|_ is set to one of

  'CRAM-MD5', 'HMAC-MD5', 'LANMAN', 'OTP', 'RPA' or 'SKEY'. This binary will

  be also required if your Python installation doesn't support the:

  * md4 hash algorithm (hashlib + OpenSSL or PyCrypto) used for the password

    schemes: 'PLAIN-MD4' and 'NTLM'

  * sha256 hash algorithm (hashlib or PyCrypto >= 2.1.0alpha1) used for the

    password schemes: 'SHA256' and 'SSHA256'

  * sha512 hash algorithm (hashlib) used for the password schemes 'SHA512'

    and 'SSHA512'

.. _bin.du:

``du (default: /usr/bin/du)`` : *String*

  The absolute path to **du**\(1). This binary is used to summarize the disk

  usage of a user's Maildir.

.. _bin.postconf:

``postconf (default: /usr/sbin/postconf)`` : *String*

  The absolute path to Postfix' |postconf(1)|_. This binary is required when

  |vmm(1)|_ has to check for some Postfix settings, e.g.

  |virtual_alias_expansion_limit|_.

Example::

  [bin]

  dovecotpw = /usr/sbin/dovecotpw

  du = /usr/bin/du

  postconf = /usr/sbin/postconf

DATABASE

--------

The **database** section is used to specify some options required to

connect to the database.

.. _database.host:

``host (default: localhost)`` : *String*

  Hostname or IP address of the database server.

.. _database.module:

``module (default: psycopg2)`` : *String*

  The Python PostgreSQL database adapter module to be used. Supported modules

  are **psycopg2** and **pyPgSQL**.

.. _database.name:

``name (default: mailsys)`` : *String*

  Name of the database.

.. _database.pass:

``pass (default: None)`` : *String*

  Database password.

.. _database.port:

``port (default: 5432)`` : *Int*

  The TCP port, on which the database server is listening for connections.

.. _database.sslmode:

``sslmode (default: prefer)`` : *String*

  Determines whether and with what priority an SSL connection will be

  negotiated with the database server. Possible values are: **disabled**,

  **allow**, **prefer**, **require**, **verify-ca**, and **verify-full**.

  The modes **verify-ca** and **verify-full** are available since PostgreSQL

  8.4.

  This setting will be ignored when the pyPgSQL *module* is used.

.. _database.user:

``user (default: None)`` : *String*

  Name of the database user.

Example::

  [database]

  host = dbsrv8.example.net

  port 5433

  sslmode = require

  user = vmm

  pass = PY_SRJ}L/0p-oOk

  name = mailsys

DOMAIN

------

The **domain** section specifies some domain related settings.

.. _domain.auto_postmaster:

``auto_postmaster (default: true)`` : *Boolean*

  Determines if |vmm(1)|_ should create also a postmaster account when a new

  domain is created (|domainadd|_).

.. _domain.delete_directory:

``delete_directory (default: false)`` : *Boolean*

  Specifies whether the domain directory and all user directories inside

  should be deleted when a domain is deleted (|domaindelete|_).

.. _domain.directory_mode:

``directory_mode (default: 504)`` : *Int*

  Access mode for the domain directory in decimal (base 10) notation.

  | For example: 'drwxrwx---' -> octal 0770 -> decimal 504

.. _domain.force_deletion:

``force_deletion (default: false)`` : *Boolean*

  Force deletion of accounts and aliases when a domain is deleted

  (|domaindelete|_).

Example::

  [domain]

  auto_postmaster = true

  delete_directory = false

  directory_mode = 504

  force_deletion = false

MAILBOX

-------

The **mailbox** section is used to specify some options for new created

mailboxes in the users home directories. The INBOX will be created always.

.. _mailbox.folders:

``folders (default: Drafts:Sent:Templates:Trash)`` : *String*

  A colon separated list of mailboxes that should be created. If no

  additionally mailboxes should be created, set the value of this option to a

  single colon ('**:**').

  If you want to create folders containing one or more subfolders, separate

  them with a single dot ('**.**').

  If you want to use internationalized mailbox names (e.g. 'Wysłane' or

  'Gelöschte Objekte'), write their names UTF-8 encoded. |vmm(1)|_ will convert

  internationalized mailbox names to a modified  version of the UTF-7 encoding

  (see also: :RFC:`3501`, section 5.1.3).

.. _mailbox.format:

``format (default: maildir)`` : *String*

  The mailbox format to be used for a user's mailbox. Depending on the used

  Dovecot version there are up to three supported formats:

    ``maildir``

      since Dovecot v1.0.0

    ``mdbox``

      since Dovecot v2.0.beta5

    ``sdbox``

      since Dovecot v2.0.rc3

.. _mailbox.root:

``root (default: Maildir)`` : *String*

  Name of the mailbox root directory in a user's home directory. Commonly used

  names, depending on the used |mailbox.format|_, are **Maildir**, **mdbox**

  or **sdbox**.

.. _mailbox.subscribe:

``subscribe (default: true)`` : *Boolean*

  When this option is set to **true**, the mailboxes from the

  |mailbox.folders|_ option will be listed in the user's subscriptions file.

  If you don't want to subscribe the created mailboxes, set this option to

  **false**.

Example::

  [mailbox]

  folders = Drafts:Sent:Templates:Trash:Lists.Dovecot:Lists.Postfix

  format = maildir

  root = Maildir

  subscribe = false

MISC

----

The **misc** section is used to define miscellaneous settings.

.. _misc.base_directory:

``base_directory (default: /srv/mail)`` : *String*

  All domain directories will be created inside this directory.

.. _misc.crypt_blowfish_rounds:

``crypt_blowfish_rounds (default: 5)`` : *Int*

  Number of encryption rounds for the *password_scheme* **BLF-CRYPT**.

  The value must be in range **4** - **31**.

.. _misc.crypt_sha256_rounds:

``crypt_sha256_rounds (default: 5000)`` : *Int*

  Number of encryption rounds for the *password_scheme* **SHA256-CRYPT**.

  The value must be in range **1000** - **999999999**.

.. _misc.crypt_sha512_rounds:

``crypt_sha512_rounds (default: 5000)`` : *Int*

  Number of encryption rounds for the *password_scheme* **SHA512-CRYPT**.

  The value must be in range **1000** - **999999999**.

.. _misc.password_scheme:

``password_scheme (default: CRAM-MD5)`` : *String*

  Password scheme to use. To get a list of all available password schemes

  execute the command **dovecotpw -l** (Dovecot v1.x) or **doveadm pw -l**

  (Dovecot v2.0).

.. _misc.quota_bytes:

``quota_bytes (default: 0)`` : *String*

  Quota limit in bytes. 0 means unlimited. This limit will be applied to

  all newly created domains.

  The option's value can be written as an integer value, e.g.: **20480**.

  Its also possible to append one of the following suffixes to the limit:

  **b** (bytes), **k** (kilobytes), **M** (megabytes) or **G** (gigabytes).

  **1024** is the same as **1024b** or **1k**.

.. _misc.quota_messages:

``quota_messages (default: 0)`` : *Int*

  Quota limit in number of messages. 0 means unlimited. This limit will be

  applied to all newly created domains.

.. _misc.transport:

``transport (default: dovecot:)`` : *String*

  Default transport for domains and accounts. For details see

  |transport(5)|_.

.. _misc.dovecot_version:

``dovecot_version (default: None)`` : *String*

  The version number of the currently used Dovecot version.

  (see: **dovecot --version**).

  When, for example, the command **dovecot --version** prints

  *2.0.beta4 (8818db00d347)*, set the value of this option to **2.0.beta4**.

Example::

  [misc]

  base_directory = /srv/mail

  crypt_sha512_rounds = 10000

  password_scheme = SHA512-CRYPT

  transport = dovecot:

  dovecot_version = 2.0.beta4

  quota_bytes = 100M

  quota_messages = 10000

FILES

=====

*/root/vmm.cfg*

  | will be used when found.

*/usr/local/etc/vmm.cfg*

  | will be used when the above file doesn't exist.

*/etc/vmm.cfg*

  | will be used when none of the both above mentioned files exists.

SEE ALSO

========

|vmm(1)|_

COPYING

=======

vmm and its manual pages were written by Pascal Volk and are licensed under

the terms of the BSD License.

.. include:: ../substitute_links.rst

.. include:: ../substitute_links_5.rst