VMM.CFG(5)

✨ NAME ✨

vmm.cfg — it's the configuration file for vmm(1), bestie. Like, the main character of config files. 💅

🌸 SYNOPSIS 🌸

vmm.cfg

💖 DESCRIPTION 💖

Okay so vmm(1) reads all its config data from vmm.cfg. No cap.

The config file is split into multiple sections. A section starts with the section name, wrapped 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 ;? They get ignored too. Bye. 🫶

Each value uses one of these data types:

• Boolean — tells you 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. Simple.
• Int — an integer number, written without a fractional or decimal component. For example 1, 50 or 321 are integers. Math is mathing. ✨
• String — a sequence of characters and/or numbers. For example word, hello world or /usr/bin/strings are strings. Iconic.

Most options have a default value, shown in parentheses after the option's name. To use an option's default setting, just comment out the line, either with a # or ;, or simply remove the setting from vmm.cfg. Easy.

A minimal vmm.cfg would be:

[database]
user = me
pass = xxxxxxxx

[misc]
dovecot_version = 2.2.11

🔍 SEARCH ORDER 🔍

By default vmm(1) looks for the vmm.cfg file in these directories, in the order listed:

• /root
• /usr/local/etc
• /etc

The first configuration file found will be used. First come, first served. 💅

🎀 SECTION ACCOUNT 🎀

The options in the account section are used to specify user account related settings. Like, the vibe of your users' accounts.

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. So like, poof, gone. 💀

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. Math queen. 👑

account.disk_usage

disk_usage (default: false) : Boolean

Determines whether the disk usage of a user's mail directory always should be summarized, using du(1), and displayed with the account information (userinfo). This could be slow on large Maildirs. When you have enabled quotas, vmm's userinfo subcommand will also display the current quota usage of the account. You may also use userinfo's optional details-argument du or full, in order to display the current disk usage of an account's mail directory. So many details, but we love that. ✨

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. So like, don't even try to make it shorter, bestie. 🙅‍♀️

account.random_password

random_password (default: false) : Boolean

Determines whether vmm(1) 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. Random passwords? Slay. 🎲

🛠️ SECTION BIN 🛠️

The bin section is used to specify some paths to some binaries required by vmm(1). Like, where the tools live.

bin.doveadm

doveadm (default: /usr/bin/doveadm) : String

The absolute path to the doveadm(1) binary. 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, SCRAM-SHA-1 or SKEY. This binary will be also required if your Python installation doesn't support the md4 hash algorithm (hashlib + OpenSSL) used for the password schemes PLAIN-MD4 and NTLM. The doveadm(1) binary is also used to create a user's INBOX and additional mailboxes (mailbox.folders), when the mailbox.format is set to mdbox or sdbox. So many jobs, but it's got this. 💪

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 mail directory. Disk space? We're watching. 👀

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. the virtual_alias_expansion_limit. Gotta check those settings, fr fr.

🗄️ SECTION DATABASE 🗄️

The database section is used to specify some options required to connect to the database. Like, the plug to the database. 🔌

database.host

host (default: localhost) : String

Hostname or IP address of the database server.

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. SSL? We love a secure queen. 🔒

database.user

user (default: None) : String

Name of the database user.

👑 SECTION DOMAIN 👑

The domain section specifies some domain related settings.

The quota limit (quota_bytes and quota_messages), service settings (imap, pop3, sieve and smtp) and the transport setting will be applied when a domain is created. In order to modify those settings for an existing domain, use one of the following vmm(1) subcommands:

• domainquota — in order to update a domain's quota limit
• domainservices — in order to assign a different service set to a domain
• domaintransport — in order to set a new default domain transport

When an account is created, it inherits all the settings of the domain to which it is added. Different settings for an existing account can be set using the subcommands userquota, userservices and usertransport. Inheritance? It's giving family drama. 💅

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). Automatic postmaster? Yes please. ✨

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). So like, delete everything? Only if you say so. 🗑️

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. Math again, but make it domain. 🔢

domain.force_deletion

force_deletion (default: false) : Boolean

Force the deletion of accounts and aliases when a domain is deleted (domaindelete). Force? Like a boss. 💥

domain.imap

imap (default: true) : Boolean

Determines whether newly created users can log in via IMAP.

domain.pop3

pop3 (default: true) : Boolean

Determines whether newly created users can log in via POP3.

domain.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. It's also possible to append one of the following prefixes to the limit: b (bytes), k (kilobytes), M (megabytes) or G (gigabytes). 1024 is the same as 1024b or 1k. Quota queen. 👑

domain.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. Messages? We count them. 💌

domain.sieve

sieve (default: true) : Boolean

Determines whether newly created users can log in via SIEVE (ManageSieve). Sieve? Fancy. 🧺

domain.smtp

smtp (default: true) : Boolean

Determines whether newly created users can log in via SMTP (SMTP AUTH). Sending mail? Iconic. 📧

domain.transport

transport (default: lmtp:unix:private/dovecot-lmtp) : String

Default transport for new domains. For details see transport(5). Transport? Like a glow-up for your mail. 🚚

📬 SECTION 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. Like, always. No exceptions. 💖

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). Internationalization? We love to see it. 🌍

mailbox.format

format (default: maildir) : String

The mailbox format to be used for a user's mailbox. Depending on the used Dovecot version (misc.dovecot_version) vmm(1) supports up to three formats:

• maildir — Dovecot ≥ v1.0.0
• mdbox — Dovecot ≥ v2.0.beta5
• sdbox — Dovecot ≥ v2.0.rc3

Choose your fighter. 🥊

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. Root directory? It's giving foundation. 🌳

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. Subscribe? Like and subscribe, bestie. 🔔

🎀 SECTION MISC 🎀

The misc section is where all the miscellaneous settings live, bestie. The little odds and ends. The ✨extras✨. Let's get into it.

---

🦋 misc.base_directory

• base_directory (default: /srv/mail) : String

Every single domain directory gets created inside this one. That's the vibe. 🏠

---

🦋 misc.crypt_blowfish_rounds

• crypt_blowfish_rounds (default: 5) : Int

How many encryption rounds you want for the password_scheme BLF-CRYPT. 🔐

The value has to be in range 4 - 31. Stay in the lines, okay?

---

🦋 misc.crypt_sha256_rounds

• crypt_sha256_rounds (default: 5000) : Int

Number of encryption rounds for the password_scheme SHA256-CRYPT.

The value has to be in range 1000 - 999999999. That's a whole lotta zeros and we love her for it. 💜

---

🦋 misc.crypt_sha512_rounds

• crypt_sha512_rounds (default: 5000) : Int

Number of encryption rounds for the password_scheme SHA512-CRYPT.

The value has to be in range 1000 - 999999999. Same energy, stronger hash, slay. 🔥

---

🦋 misc.dovecot_version

• dovecot_version (default: None) : String

This is the version number of the Dovecot version you're currently running (see: dovecot --version).

So, say your dovecot --version command prints out:

2.0.beta4 (8818db00d347)

Then you'd set this option's value to 2.0.beta4. Just the number, not the hash in parens, bestie. 🕊️

---

🦋 misc.password_scheme

• password_scheme (default: CRAM-MD5) : String

The password scheme you want to use. Want the full menu of all usable password schemes? Run this:

vmm lp

and it'll show you the whole lineup. 👑

With Dovecot ≥ v1.1.alpha1 you can also append an encoding suffix to the password_scheme. The supported encoding suffixes are: .b64, .base64 and .hex. So for example: PLAIN.BASE64 — cute, right? 🌸

Note: When you set another password scheme than PLAIN or CRAM-MD5, you have to remove cram-md5 from the auth_mechanisms setting in your dovecot/conf.d/10-auth.conf. Do not skip this. It WILL be a problem. 😭

---

✨ EXAMPLE ✨

Here's an example configuration. Just so you know the rules: all options that are not listed in the configuration file will have their default values. No cap.

[account]
password_length = 10
random_password = true

[database]
host = dbsrv8.example.net
pass = PY_SRJ}L/0p-oOk
port = 5433
sslmode = require
user = vmm

[domain]
quota_bytes = 500M
quota_messages = 10000

[mailbox]
folders = Drafts:Sent:Templates:Trash:Lists.Dovecot:Lists.Postfix

[misc]
crypt_sha512_rounds = 10000
dovecot_version = 2.2.11
password_scheme = SHA512-CRYPT.hex

Look at her. Gorgeous. Every section, every setting, all living their best life together. 💅

---

👀 SEE ALSO 👀

postconf(1), vmm(1), transport(5)

Go read those too, bestie, they're part of the lore. 📚

---

🌈 INTERNET RESOURCES 🌈

• Homepage — http://vmm.localdomain.org/
• Project site — http://sf.net/projects/vmm/
• Bug tracker — https://bitbucket.org/pvo/vmm/issues

Found a bug? Report it, don't just suffer in silence. 🫶

---

💜 COPYING 💜

vmm and its manual pages were written by Pascal Volk <user+vmm AT localhost.localdomain.org> and are licensed under the terms of the BSD License. Respect the license, it's iconic.

---

And that's a wrap, bestie!! 🎀 This is vmm version 0.7, dated 2014-02-17, and you just finished reading VMM.CFG(5) — the config file page, part two of two. Go forth and configure responsibly. Mwah. 💖✨🦋