diff -r 9480f2b15129 -r 3d09c657e9e5 man/man5/vmm.cfg.5.rst --- a/man/man5/vmm.cfg.5.rst Fri Jan 29 23:56:45 2010 +0000 +++ b/man/man5/vmm.cfg.5.rst Sat Jan 30 05:15:21 2010 +0000 @@ -7,22 +7,23 @@ -------------------------- :Author: Pascal Volk -:Date: 2010-01-26 +:Date: 2010-01-30 :Version: vmm-0.6.0 :Manual group: vmm Manual :Manual section: 5 .. contents:: - :backlinks: top - :class: htmlout + :backlinks: top + :class: htmlout SYNOPSIS ======== vmm.cfg + DESCRIPTION =========== -**vmm**\(1) reads its configuration data from *vmm.cfg*. +|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 @@ -54,261 +55,347 @@ A minimal *vmm.cfg* would be:: - [database] - user = me - pass = xxxxxxxx + [database] + user = me + pass = xxxxxxxx - [config] - done = true + [config] + done = true + SEARCH ORDER ------------- -By default **vmm**\(1) looks for *vmm.cfg* in the following directories in the +By default |vmm(1)|_ looks for *vmm.cfg* in the following directories in the order listed: - | */root* - | */usr/local/etc* - | */etc* + | */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. If - this option is set to *true* the user's home directory will be deleted - recursively. + 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. + 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 + | 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. + 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. + 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. + 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. + 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. + 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 - **password_length** option. + 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. + 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). + 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 + [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). +by |vmm(1)|_. + +.. _bin.dovecotpw: ``dovecotpw (default: /usr/sbin/dovecotpw)`` : *String* - The absolute path to the dovecotpw binary. This binary is used to - generate a password hash, if **misc.password_scheme** is set to one of - 'SMD5', 'SSHA', 'CRAM-MD5', 'HMAC-MD5', 'LANMAN', 'NTLM' or 'RPA'. + The absolute path to the dovecotpw binary. This binary is used to + generate a password hash, if |misc.password_scheme|_ is set to one of + 'SMD5', 'SSHA', 'CRAM-MD5', 'HMAC-MD5', 'LANMAN', 'NTLM' or 'RPA'. + +.. _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. + 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`. + 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 + [bin] + dovecotpw = /usr/sbin/dovecotpw + du = /usr/bin/du + postconf = /usr/sbin/postconf + CONFIG ------ The **config** section is an internal used control section. +.. _config.done: + ``done (default: false)`` : *Boolean* - This option is set to *false* when **vmm**\(1) is installed for the first - time. When you edit *vmm.cfg*, set this option to *true*. This option is - also set to *true* when you configure **vmm**\(1) with the command **vmm - configure**. + This option is set to *false* when |vmm(1)|_ is installed for the first + time. When you edit *vmm.cfg*, set this option to *true*. This option is + also set to *true* when you configure |vmm(1)|_ with the command |vmm + configure|_. - If this option is set to *false*, **vmm**\(1) will start in the - interactive configurations mode. + If this option is set to *false*, |vmm(1)|_ will start in the interactive + configurations mode. Example:: - [config] - done = true + [config] + done = true + 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. + Hostname or IP address of the database server. + +.. _database.name: ``name (default: mailsys)`` : *String* - Name of the database. + Name of the database. + +.. _database.pass: ``pass (default: None)`` : *String* - Database password. + Database password. + +.. _database.user: ``user (default: None)`` : *String* - Name of the database user. + Name of the database user. Example:: - [database] - host = localhost - user = vmm - pass = PY_SRJ}L/0p-oOk - name = mailsys + [database] + host = localhost + 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. + 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. + 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. + Access mode for the domain directory in decimal (base 10) notation. - | For example: 'drwxrwx---' -> octal 0770 -> decimal 504 + | 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. + 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 + [domain] + auto_postmaster = true + delete_directory = false + directory_mode = 504 + force_deletion = false + MAILDIR ------- The **maildir** section is used to specify some default options for new created Maildirs and folders inside. +.. _maildir.folders: + ``folders (default: Drafts:Sent:Templates:Trash)`` : *String* - A colon separated list of folder names, that should be created. If no - folders should be created inside the Maildir, set the value of this - option to a single colon ('**:**'). + A colon separated list of folder names, that should be created. If no + folders should be created inside the Maildir, 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 create folders containing one or more subfolders, separate + them with a single dot ('**.**'). + +.. _maildir.name: ``name (default: Maildir)`` : *String* - Default name of the Maildir folder in users home directories. + Default name of the Maildir folder in users home directories. Example:: - [maildir] - folders = Drafts:Sent:Templates:Trash:Lists.Dovecot:Lists.Postfix - name = Maildir + [maildir] + folders = Drafts:Sent:Templates:Trash:Lists.Dovecot:Lists.Postfix + name = Maildir + +.. _imap_uft7: + +.. note:: If you want to use internationalized mailbox names in the + **folders** setting, you have to specify them in a modified version of the + UTF-7 encoding (see :RFC:`3501`, section 5.1.3). + + Dovecot provides a useful utility for mUTF-7 <-> UTF-8 conversion: + **imap-utf7**, it's available since Dovecot version 1.2.0. +.. + +imap-utf7 example:: + + user@host:~$ /usr/local/libexec/dovecot/imap-utf7 -r Wysłane + Wys&AUI-ane + user@host:~$ /usr/local/libexec/dovecot/imap-utf7 "&AVo-mietnik" + Śmietnik + 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. + All domain directories will be created inside this directory. + +.. _misc.password_scheme: ``password_scheme (default: CRAM-MD5)`` : *String* - Password scheme to use (see also: **dovecotpw -l**). + Password scheme to use (see also: **dovecotpw -l**). + +.. _misc.gid_mail: ``gid_mail (default: 8)`` : *Int* - Numeric group ID of group mail (`mail_privileged_group` from - *dovecot.conf*) + Numeric group ID of group mail (`mail_privileged_group` from + *dovecot.conf*) + +.. _misc.transport: ``transport (default: dovecot:)`` : *String* - Default transport for domains and accounts. For details see - **transport**\(5). + Default transport for domains and accounts. For details see + |transport(5)|_. + +.. _misc.dovecot_version: ``dovecot_version (default: 12)`` : *Int* - The concatenated major and minor version number of the currently used - Dovecot version. (see: **dovecot --version**). + The concatenated major and minor version number of the currently used + Dovecot version. (see: **dovecot --version**). - When, for example, the command **dovecot --version** prints *1.1.18*, set - the value of this option to **11**. + When, for example, the command **dovecot --version** prints *1.1.18*, set + the value of this option to **11**. Example:: - [misc] - base_directory = /srv/mail - password_scheme = PLAIN - gid_mail = 8 - transport = dovecot: - dovecot_version = 11 + [misc] + base_directory = /srv/mail + password_scheme = PLAIN + gid_mail = 8 + transport = dovecot: + dovecot_version = 11 + FILES ===== */root/vmm.cfg* - | will be used when found. + | will be used when found. */usr/local/etc/vmm.cfg* - | will be used when the above file doesn't exist. + | 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. + | will be used when none of the both above mentioned files exists. + SEE ALSO ======== -vmm(1), command line tool to manage email domains/accounts/aliases +|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