diff -r 1ca025a5ce0c -r 65687300ba19 man/man5/vmm.cfg.5.rst --- a/man/man5/vmm.cfg.5.rst Tue Feb 22 15:43:25 2011 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,462 +0,0 @@ -========= - vmm.cfg -========= - --------------------------- -configuration file for vmm --------------------------- - -:Author: Pascal Volk -: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