VMM(1)

📦 version 0.7.0, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 VMM 💖

okay bestie, grab your iced coffee, we're doing the vmm page and it's a WHOLE thing ✨

🌸 NAME 🌸

vmm — command line tool to manage email domains/accounts/aliases

✨ SYNOPSIS ✨

vmm -h|-v|--help|--version
vmm subcommand -h|--help
vmm subcommand arguments [options]

🦋 DESCRIPTION 🦋

So vmm — that's short for virtual mail manager btw, iykyk — is the easy to use command line tool for admins and postmasters who need to manage (alias) domains, accounts, aliases and relocated users. Basically it lets you simply and quickly administer your mail server. iconic 💅

It's designed for Dovecot and Postfix with a PostgreSQL backend. yes, the holy trinity. periodt.

Every single subcommand has both a long and a short form. The short form shows up wrapped in parentheses. And listen — both forms are case sensitive, so don't get cute with the capitalisation bestie 😭

Also: most of the subcommands take one or more arguments. like, they need the tea before they can serve.

🎀 OPTIONS 🎀

These are the options vmm recognizes:

  • -h, --help — shows you a list of the available subcommands and dips. bye 💅
  • -v, --version — spills vmm's version and copyright info, then exits.

🫶 ARGUMENTS 🫶

  • address — the complete e-mail address (local-part@fqdn) of a user account, an alias address, or a relocated user. that's the whole thing, local-part AND fqdn, no shortcuts 🎀
  • destination — when it's used with ALIAS SUBCOMMANDS it's an e-mail address. When it's used with ALIASDOMAIN SUBCOMMANDS it's a fqdn. context is everything bestie ✨
  • fqdn — the fully qualified domain name of a domain or alias domain — without the trailing dot. so no sneaky little dot at the end, ok? 🌸
  • messages — an integer value specifying a quota limit in number of messages. 0 (zero) means unlimited — no quota limit for the number of messages. zero is giving ✨no limits✨
  • option — the name of a configuration option, prefixed with the section name and a dot. For example: misc.transport. All the configuration options are described in vmm.cfg(5). go read that one, i'll wait 🫶
  • service — the name of a service, commonly used with Dovecot. Supported services are: imap, pop3, sieve and smtp. those four, no others, don't try it 💀
  • storage — a quota limit in bytes. You can append one of these prefixes to the integer value: b (bytes), k (kilobytes), M (megabytes) or G (gigabytes). And 0 (zero) means unlimited — no quota limit in bytes. lowercase k but uppercase M and G, yes it's like that, i don't make the rules 😭
  • transport — a transport for Postfix, written as: transport: or transport:nexthop. See transport(5) for more details. ⭐

👑 GENERAL SUBCOMMANDS 👑

configget (cg)

vmm configget option

This one displays the actual value of the configuration option you asked about. like a lil mirror for your config 🪞

Example:

vmm configget misc.crypt_sha512_rounds
misc.crypt_sha512_rounds = 5000

configset (cs)

vmm configset option value

Use this to set or update a single configuration option's value. option is the configuration option, value is the option's new value. slay, one option at a time 💅

Note: This subcommand will create a new vmm.cfg without any comments. Your current configuration file will be backed as vmm.cfg.bak. so like, your comments are GONE gone. it keeps a backup tho, so breathe 🫶

Example:

vmm configget domain.transport
domain.transport = dovecot:
vmm configset domain.transport lmtp:unix:private/dovecot-lmtp
vmm cg domain.transport
domain.transport = lmtp:unix:private/dovecot-lmtp

configure (cf)

vmm configure [-s section]

Starts the interactive configuration for all configuration sections. it's giving ✨guided tour✨

During this process, the currently set value of each option gets displayed in square brackets. If no value is configured, the default value of each option is what shows up in square brackets. Press the return key to accept whatever's displayed. easy 💅

If you pass the optional argument section, only the configuration options from that given section will be displayed and configurable. The following sections are available:

  • account — Account settings
  • bin — Paths to external binaries
  • database — Database settings
  • domain — Domain settings
  • mailbox — Mailbox settings
  • misc — Miscellaneous settings

All the configuration options are described in vmm.cfg(5). 🎀

Note: This subcommand will create a new vmm.cfg without any comments. Your current configuration file will be backed as vmm.cfg.bak. yeah same warning as before, the comments do NOT survive 🙈

Example:

vmm configure -s mailbox
Using configuration file: /usr/local/etc/vmm.cfg

* Configuration section: `mailbox'
Enter new value for option folders [Drafts:Sent:Templates:Trash]:
Enter new value for option format [maildir]: mdbox
Enter new value for option subscribe [True]:
Enter new value for option root [Maildir]: mdbox

getuser (gu)

vmm getuser uid

If all you've got is the uid — like, say, from a process list — the getuser subcommand will show you the user's address. little detective work, love that for us 🔍

Example:

vmm getuser 79876
Account information
-------------------
        UID............: 79876
        GID............: 70704
        Address........: a.user@example.com

listdomains (ld)

vmm listdomains [-p pattern]

Lists all available domains. Every domain name gets prefixed either with [+] if it's a primary domain, or with [-] if it's an alias domain name. The output can be limited with an optional pattern. ✨

For a wild card search, you can drop the % character at the start and/or the end of the pattern. she's flexible like that 💅

Example:

vmm listdomains -p %example%
Matching domains
----------------
        [+] example.com
        [-]     e.g.example.com
        [-]     example.name
        [+] example.net
        [+] example.org

listaddresses (ll)

vmm listaddresses [-p pattern]

Lists all defined addresses. Addresses belonging to alias-domains get prefixed with a '-', addresses of regular domains with a '+'. On top of that, the letters 'u', 'a', and 'r' tell you the type of each address: user, alias and relocated respectively. The output can be limited with an optional pattern. 🎀

For a wild card search, you can use the % character at the start and/or the end of the pattern. 🌸

If you don't include an '@'-character in your pattern, the command will only match your pattern agains the fqdn of the addresses. A pattern like %user%@%example% will match against any address that contains the term 'user' in its local-part AND 'example' in its fqdn. both conditions, bestie, no half measures 💅

Example:

vmm listaddresses -p example.com
vmm listaddresses -p %master@%

listaliases (la)

vmm listaliases [-p pattern]

Lists all defined aliases. Aliases belonging to alias-domains get prefixed with a '-', addresses of regular domains with a '+'. The output can be limited with an optional pattern. ✨

For a wild card search, the % character goes at the start and/or the end of the pattern. 🦋

If you don't include an '@'-character in your pattern, the command will only match your pattern agains the fqdn of the addresses. A pattern like %user%@%example% will match against any address that contains the term 'user' in its local-part AND 'example' in its fqdn. 🎀

Example:

vmm listaliases -p example.com
vmm listaliases -p %master@%

listrelocated (lr)

vmm listrelocated [-p pattern]

Lists all defined relocated addresses. Relocated entries belonging to alias-domains get prefixed with a '-', addresses of regular domains with a '+'. The output can be limited with an optional pattern. 🌈

For a wild card search, use the % character at the start and/or the end of the pattern. 💜

If you don't include an '@'-character in your pattern, the command will only match your pattern agains the fqdn of the addresses. A pattern like %user%@%example% will match against any address that contains the term 'user' in its local-part AND 'example' in its fqdn. ✨

Example:

vmm listrelocated -p example.com
vmm listrelocated -p %master@%

listusers (lu)

vmm listusers [-p pattern]

Lists all user accounts. User accounts belonging to alias-domains get prefixed with a '-', addresses of regular domains with a '+'. The output can be limited with an optional pattern. 🎀

For a wild card search, the % character can go at the start and/or the end of the pattern. 🌸

If you don't include an '@'-character in your pattern, the command will only match your pattern agains the fqdn of the addresses. A pattern like %user%@%example% will match against any address that contains the term 'user' in its local-part AND 'example' in its fqdn. 💅

Example:

vmm listusers -p example.com
vmm listusers -p %master@%

listpwschemes (lp)

vmm listpwschemes

This subcommand lists all password schemes that could be used in the vmm.cfg as the value of the misc.password_scheme option. The output varies, depending on the used Dovecot version and the system's libc. she's different on every system, main character behaviour honestly ✨

Additionally a few usable encoding suffixes will be displayed. One of them can be appended to the password scheme. 🎀

Example:

vmm listpwschemes
Usable password schemes
-----------------------
        CLEARTEXT CRAM-MD5 CRYPT DIGEST-MD5 HMAC-MD5 LANMAN LDAP-MD5 MD5
        MD5-CRYPT NTLM OTP PLAIN PLAIN-MD4 PLAIN-MD5 RPA SHA SHA1 SHA256
        SHA256-CRYPT SHA512 SHA512-CRYPT SKEY SMD5 SSHA SSHA256 SSHA512

Usable encoding suffixes
------------------------
        .B64 .BASE64 .HEX

and that's part 1 bestie, there's more coming, don't go anywhere 💖

🦋 DOMAIN SUBCOMMANDS 🦋

domainadd (da)

vmm domainadd fqdn [-n note] [-t transport]
  • -n note — the note that should be set, bestie. 💌
  • -t transport — a Postfix transport (transport: or transport:nexthop).

This one drops the brand new domain into the database and creates the domain directory. Two birds, one subcommand. ✨

If you hand it the optional transport argument, it overrides the default transport (domain.transport) from vmm.cfg. And that transport you specified? It becomes the default transport for every single new account in this domain. Slay.

  • domain.auto_postmaster — when this is set to true (which it is by default), vmm will automatically create the postmaster account for the new domain and prompt you for postmaster@fqdn's password. 🔐
  • account.random_password — when this one is also set to true, vmm will automatically create the postmaster account for the new domain and print the generated postmaster password to stdout. No typing required, iconic.

Examples, look at her go:

vmm domainadd support.example.com -t smtp:[mx1.example.com]:2025
Creating account for postmaster@support.example.com
Enter new password:
Retype new password:
vmm cs account.random_password true
vmm domainadd sales.example.com
Creating account for postmaster@sales.example.com
Generated password: pLJUQ6Xg_z

domaindelete (dd)

vmm domaindelete fqdn [--delete-directory] [--force]
  • --delete-directory — when you pass this, vmm will delete the directory of the given domain. It overrides the domain.delete_directory setting in vmm.cfg.
  • --force — use this to force the deletion of the domain, even if there are accounts, aliases, catch-all accounts and/or relocated users hanging around. 😳

This subcommand deletes the domain you named in fqdn.

If there are accounts, aliases and/or relocated users assigned to that domain, vmm will abort the whole operation and show you an error message. And if you genuinely know what you're doing, you can specify the optional --force. 🙈

And if you really always know what you're doing? Go edit your vmm.cfg and set the option domain.force_deletion to true. Living dangerously, we love that for you.

domaininfo (di)

vmm domaininfo fqdn [-d details]

This subcommand shows some information about the given domain. The tea. ☕

Want the more detailed version? Pass the optional details argument. A possible details value can be one of these six keywords:

  • accounts — to list the e-mail addresses of all existing user accounts
  • aliasdomains — to list all assigned alias domain names
  • aliases — to list all available alias e-mail addresses
  • catchall — to list all catch-all destinations
  • relocated — to list the e-mail addresses of all relocated users
  • full — to list all information mentioned above (the whole buffet 💅)

Example:

vmm domaininfo sales.example.com
Domain information
------------------
        Domain Name......: sales.example.com
        GID..............: 70708
        Domain Directory.: /srv/mail/c/70708
        Quota Limit/User.: Storage: 500.00 MiB; Messages: 10,000
        Active Services..: IMAP SIEVE
        Transport........: lmtp:unix:private/dovecot-lmtp
        Alias Domains....: 0
        Accounts.........: 1
        Aliases..........: 0
        Relocated........: 0
        Catch-All Dests..: 1

domainquota (dq)

vmm domainquota fqdn storage [-m messages] [--force]

Okay so this subcommand configures a new quota limit for the accounts of the domain — not for the domain itself. Important distinction, don't get it twisted. 👑

The default quota limit for accounts is defined in the vmm.cfg (domain.quota_bytes and domain.quota_messages).

The new quota limit will affect only those accounts for which the limit has not been overridden. And if you want to restore the default to all accounts, you may pass the optional --force. When the messages argument was omitted, the default number of messages 0 (zero) will be applied.

Example:

vmm domainquota example.com 1g --force

domainservices (ds)

vmm domainservices fqdn (-e service ...| -d service ...)  [--force]

To define which services could be used by the users of the domain — the one with the given fqdn — use this subcommand.

Pass them after -e and each supplied service gets enabled/usable. ✅ Pass them after -d and they become deactivated/unusable. ❌ Possible service names are: imap, pop3, sieve and smtp.

The new service set will affect only those accounts for which the set has not been overridden. And if you want to restore the default to all accounts, you may pass the option --force.

domaintransport (dt)

vmm domaintransport fqdn transport [--force]

A new transport for the indicated domain can be set with this subcommand. Simple as that.

The new transport will affect only those accounts for which the transport has not been overridden. If you want to restore the default to all accounts, you may give the option --force.

Example:

vmm domaintransport support.example.com dovecot:

domainnote (do)

vmm domainnote fqdn -d|-n note
  • -d — delete the domain's note. 🗑️
  • -n note — the note that should be set.

With this subcommand, it is possible to attach a note to the specified domain. And in order to delete an existing note, just pass the -d option.

Example:

vmm do example.com -n `Belongs to Robert'

🌈 ALIAS DOMAIN SUBCOMMANDS 🌈

An alias domain is an alias for a domain that was previously added with the subcommand domainadd. All accounts, aliases and relocated users from the domain will also be available in the alias domain. So it's giving… the same energy, twice. ✨

In the following, it is to be assumed that example.net is an alias for example.com.

Postfix will not accept erroneously e-mails for unknown.user@example.net and bounce them back later to the mostly faked sender. Nope. Postfix will immediately reject all e-mails addressed to nonexistent users. And this behavior is ensured as long as you use the recommended database queries in your $config_directory/pgsql-*.cf configuration files. 🫶

aliasdomainadd (ada)

vmm aliasdomainadd fqdn destination

This subcommand adds the new alias domain (fqdn) to the destination domain that should be aliased.

Example:

vmm aliasdomainadd example.net example.com

aliasdomaindelete (add)

vmm aliasdomaindelete fqdn

Use this subcommand if the alias domain fqdn should be removed. Bye bestie 👋

Example:

vmm aliasdomaindelete e.g.example.com

aliasdomaininfo (adi)

vmm aliasdomaininfo fqdn

This subcommand shows to which domain the alias domain fqdn is assigned to.

Example:

vmm adi example.net
Alias domain information
------------------------
        The alias domain example.net belongs to:
            * example.com

aliasdomainswitch (ads)

vmm aliasdomainswitch fqdn destination

If the destination of the existing alias domain fqdn should be switched to another destination, use this subcommand. Glow-up moment for your alias. 🦋

Example:

vmm aliasdomainswitch example.name example.org

💖 ACCOUNT SUBCOMMANDS 💖

okay bestie, this is the section where we handle actual people — their accounts, their passwords, their quotas, their whole little mail existence. let's get into it 🫶

🌸 useradd (ua) 🌸

vmm useradd address [-n note] [-p password]
  • -n note — the note that should be set. 💌
  • -p password — the new user's password. 🤫

Use this subcommand to create a new e-mail account for the given address. iconic, we love a fresh account ✨

If the password is not provided, vmm will prompt for it interactively. And when no password is provided and account.random_password is set to true, vmm will generate a random password and print it to stdout after the account has been created. surprise! 🎁

Examples:

vmm ua d.user@example.com -p "A 5ecR3t P4s5\/\/0rd"
vmm useradd e.user@example.com
Enter new password:
Retype new password:

🦋 userdelete (ud) 🦋

vmm userdelete address [--delete-directory] [--force]
  • --delete-directory — when this option is present, vmm will also delete the account's home directory. This overrides the account.delete_directory setting of vmm.cfg. bye bye files 😭
  • --force — when this option is given, vmm will delete the account, even if there are aliases with the account's address as their destination. Those aliases will be deleted too. no mercy, periodt 💅

Use this subcommand to delete the account with the given address.

⚠️ If there are one or more aliases with an identical destination address, vmm will abort the requested operation and show an error message. To prevent this, give the optional argument --force.

🌈 userinfo (ui) 🌈

vmm userinfo address [-d details]

This subcommand displays some information about the account specified by address. it's giving stalker but make it sysadmin 🔍

If the optional argument details is given, some more information will be displayed. Possible values for details are:

  • aliases — to list all alias addresses with the destination address
  • du — to display the disk usage of the user's mail directory. In order to summarize the disk usage each time this subcommand is executed automatically, set account.disk_usage in your vmm.cfg to true.
  • full — to list all information mentioned above

Example:

vmm ui d.user@example.com
Account information
-------------------
        Address..........: d.user@example.com
        Name.............: None
        UID..............: 79881
        GID..............: 70704
        Home.............: /srv/mail/2/70704/79881
        Mail_Location....: mdbox:~/mdbox
        Quota Storage....: [  0.00%] 0/500.00 MiB
        Quota Messages...: [  0.00%] 0/10,000
        Transport........: lmtp:unix:private/dovecot-lmtp
        SMTP.............: disabled
        POP3.............: disabled
        IMAP.............: enabled
        SIEVE............: enabled

💜 username (un) 💜

vmm username address -d|-n name
  • -d — delete the user's name. 🗑️
  • -n name — a user's real name. ✍️

The user's real name can be set/updated with this subcommand.

In order to delete the value stored for the account, pass the -d option.

Example:

vmm un d.user@example.com -n "John Doe"

🔥 userpassword (up) 🔥

vmm userpassword address ([-p password] [-s scheme] | --hash pwhash])
  • -p password — the user's new password. 🤐
  • -s scheme — when a scheme was specified, it overrides the misc.password_scheme setting, configured in the vmm.cfg file.
  • --hash pwhash — a hashed password, prefixed with {SCHEME}; as generated by doveadm pw. You should enclose the hashed password in single quotes, if it contains one ore more dollar signs ($). 💵 (yes, "ore" — that's what the page says, bestie, we keep the lore)

The password of an account can be updated with this subcommand.

If no password or pwhash was provided, vmm will prompt for a password interactively.

📝 Note: When passing a hashed password, vmm checks only if the included SCHEME is supported by your Dovecot installation. No further checks are done. that's it, that's the whole vibe check.

Example:

vmm up d.user@example.com -p "A |\/|0r3 5ecur3 P4s5\/\/0rd?"

🎀 usernote (uo) 🎀

vmm usernote address -d|-n note
  • -d — delete the user's note. 🗑️
  • -n note — the note that should be set. 📝

With this subcommand, it is possible to attach a note to the specified account. In order to delete an existing note, pass the -d option.

Example:

vmm uo d.user@example.com -n `Only needed until end of May 2013'

⭐ userquota (uq) ⭐

vmm userquota address storage [-m messages]

This subcommand is used to set a new quota limit for the given account.

When the argument messages was omitted the default number of messages 0 (zero) will be applied.

Instead of storage limit pass the keyword domain to remove the account-specific override, causing the domain's value to be in effect. we love an inheritance moment 👑

Example:

vmm userquota d.user@example.com 750m

🧚 userservices (us) 🧚

vmm userservices address (-e service ...| -d service ...| -r)

To grant a user access to the specified services, use this command.

If you pass services after -e, each service will be enabled/usable. If you pass them after -d they will be disabled/unusable. in order to restore the domain defaults on the address, pass -r without any more parameters.

Example:

vmm userservices d.user@example.com -d smtp imap

🚚 usertransport (ut) 🚚

vmm usertransport address transport

A different transport for an account can be specified with this subcommand.

Instead of transport pass 'domain' to remove the account-specific override, causing the domain's value to be in effect.

Example: Assumed you want to use Dovecot's dsync(1) to convert a user's mailbox from Maildir format to mdbox format, you can tell Postfix to retry later.

vmm ut d.user@example.com "retry:4.0.0 Mailbox being migrated"
# convert the mailbox ... then set the transport to Dovecot's lmtp
vmm ut d.user@example.com lmtp:unix:private/dovecot-lmtp

🦄 ALIAS SUBCOMMANDS 🦄

aliases: the little redirect goblins that make one address magically become another. obsessed 💫

✨ aliasadd (aa) ✨

vmm aliasadd address destination ...

This subcommand is used to create a new alias address with one or more destination addresses.

Within the destination address, the placeholders %n, %d, and %= will be replaced by the local part, the domain, or the email address with '@' replaced by '=' respectively. In combination with alias domains, this enables domain-specific destinations. fancy fr fr 🎩

Examples:

vmm aliasadd john.doe@example.com d.user@example.com
vmm aa support@example.com d.user@example.com e.user@example.com
vmm aa postmaster@example.com postmaster+%d@example.org

💫 aliasdelete (ad) 💫

vmm aliasdelete address [destination ...]

This subcommand is used to delete one or multiple destinations from the alias with the given address.

When no destination address was specified the alias with all its destinations will be deleted. gone. poof. 💨

Example:

vmm ad support@example.com d.user@example.com

👑 aliasinfo (ai) 👑

vmm aliasinfo address

Information about the alias with the given address can be displayed with this subcommand.

Example:

vmm aliasinfo support@example.com
Alias information
-----------------
        Mail for support@example.com will be redirected to:
             * e.user@example.com

🛫 RELOCATED SUBCOMMANDS 🛫

for the girlies who moved on and left a forwarding address behind 💅

🌸 relocatedadd (ra) 🌸

vmm relocatedadd address newaddress

A new relocated user can be created with this subcommand.

address is the user's ex-email address, for example b.user@example.com, and newaddress points to the new email address where the user can be reached.

Example:

vmm relocatedadd b.user@example.com b-user@company.tld

🦋 relocatedinfo (ri) 🦋

vmm relocatedinfo address

This subcommand shows the new address of the relocated user with the given address.

Example:

vmm relocatedinfo b.user@example.com
Relocated information
---------------------
        User `b.user@example.com' has moved to `b-user@company.tld'

🗑️ relocateddelete (rd) 🗑️

vmm relocateddelete address

Use this subcommand in order to delete the relocated user with the given address.

Example:

vmm relocateddelete b.user@example.com

🎣 CATCH-ALL SUBCOMMANDS 🎣

the "if in doubt, just give it to this person" squad. powerful, but lowkey dangerous, we'll get to that 🌊

🌈 catchalladd (caa) 🌈

vmm catchalladd fqdn destination ...

This subcommand allows to specify destination addresses for a domain, which shall receive mail addressed to unknown local parts within that domain. Those catch-all aliases hence "catch all" mail to any address in the domain (unless a more specific alias, mailbox or relocated entry exists).

🚨 WARNING: Catch-all addresses can cause mail server flooding because spammers like to deliver mail to all possible combinations of names, e.g. to all addresses between abba@example.org and zztop@example.org. not the spammer behavior we're rooting for, bestie 😭

Example:

vmm catchalladd example.com user@example.org

🔍 catchallinfo (cai) 🔍

vmm catchallinfo fqdn

This subcommand displays information about catch-all aliases defined for a domain.

Example:

vmm catchallinfo example.com
Catch-all information
---------------------
  Mail to unknown local-parts in domain example.com will be sent to:
         * user@example.org

🧹 catchalldelete (cad) 🧹

vmm catchalldelete fqdn [destination ...]

With this subcommand, catch-all aliases defined for a domain can be removed, either all of them, or those *destination*s which were specified explicitly.

Example:

vmm catchalldelete example.com user@example.com

📂 FILES 📂

the config hunt goes in this exact order, no skipping 🕵️‍♀️

  • /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 👀

doveadm-pw(1), dsync(1), transport(5), vmm.cfg(5)

go read those too, i'm not kidding, they're part of the lore 📚

🌐 INTERNET RESOURCES 🌐

📜 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 author, bestie 🫶

and that's a wrap on the whole page!! this beauty is from vmm 0.7, dated 2014-06-09, and it's VMM(1) — literally iconic, no notes, go configure your mail server 💖✨🎀

📦 where this page comes from