--- name: "vmm" section: "1" platform: "linux" package: "vmm" version: "0.7.0-0.3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/vmm" --- # vmm(1) command line tool to manage email domains/accounts/aliases ## 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 **vmm** (a virtual mail manager) is the easy to use command line tool for administrators and postmasters to manage (alias) domains, accounts, aliases and relocated users. It allows you to simply and quickly administer your mail server.\ It's designed for Dovecot and Postfix with a PostgreSQL backend. Each *subcommand* has both a long and a short form. The short form is shown enclosed in parentheses. Both forms are case sensitive. Most of the *subcommand*s take one or more *argument*s. ## OPTIONS The following options are recognized by **vmm**. - **-h**, **--help** show a list of available subcommands and exit. - **-v**, **--version** show **vmm**'s version and copyright information and exit. ## ARGUMENTS - *address* The complete e-mail address (*local-part*@*fqdn*) of an user account, alias address or relocated user. - *destination* Is either an e-mail *address* when used with *ALIAS SUBCOMMANDS*. Or a *fqdn* when used with *ALIASDOMAIN SUBCOMMANDS*. - *fqdn* The fully qualified domain name - without the trailing dot - of a domain or alias domain. - *messages* An integer value which specifies a quota limit in number of messages. **0** (zero) means unlimited - no quota limit for the number of messages. - *option* is the name of a configuration option, prefixed with the section name and a dot. For example: *misc***.***transport*\ All configuration options are described in [**vmm.cfg**(5)](/vmm.cfg/5.md). - *service* The name of a service, commonly used with Dovecot. Supported services are: **imap**, **pop3**, **sieve** and **smtp**. - *storage* Specifies a quota limit in bytes. One of the following prefixes can be appended to the integer value: **b** (bytes), **k** (kilobytes), **M** (megabytes) or **G** (gigabytes). **0** (zero) means unlimited - no quota limit in bytes. - *transport* A transport for Postfix, written as: *transport***:** or *transport***:** *nexthop*. See [**transport**(5)](/transport/5.md) for more details. ## GENERAL SUBCOMMANDS ### configget (cg) **vmm configget** *option* This subcommand is used to display the actual value of the given configuration *option*. Example: ``` vmm configget misc.crypt_sha512_rounds misc.crypt_sha512_rounds = 5000 ``` ### configset (cs) **vmm configset** *option value* Use this subcommand to set or update a single configuration option's value. *option* is the configuration option, *value* is the *option*'s new value. - Note: This subcommand will create a new *vmm.cfg* without any comments. Your current configuration file will be backed as *vmm.cfg.bak*. 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. In this process the currently set value of each option will be displayed in square brackets. If no value is configured, the default value of each option will be displayed in square brackets. Press the return key, to accept the displayed value. If the optional argument *section* is given, only the configuration options from the given section will be displayed and will be 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 configuration options are described in [**vmm.cfg**(5)](/vmm.cfg/5.md). - Note: This subcommand will create a new *vmm.cfg* without any comments. Your current configuration file will be backed as *vmm.cfg.bak*. 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 only the *uid* is available, for example from process list, the subcommand **getuser** will show the user's address. Example: ``` vmm getuser 79876 Account information ------------------- UID............: 79876 GID............: 70704 Address........: a.user@example.com ``` ### listdomains (ld) **vmm listdomains** \[**-p** *pattern*\] This subcommand lists all available domains. All domain names will be prefixed either with \`\[+\]', if the domain is a primary domain, or with \`\[-\]', if it is an alias domain name. The output can be limited with an optional *pattern*. To perform a wild card search, the % character can be used at the start and/or the end of the *pattern*. 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*\] This command lists all defined addresses. Addresses belonging to alias-domains are prefixed with a '-', addresses of regular domains with a '+'. Additionally, the letters 'u', 'a', and 'r' indicate the type of each address: user, alias and relocated respectively. The output can be limited with an optional *pattern*. To perform a wild card search, the % character can be used at the start and/or the end of the *pattern*. If you do not 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 listaddresses -p example.com vmm listaddresses -p %master@% ``` ### listaliases (la) **vmm listaliases** \[**-p** *pattern*\] This command lists all defined aliases. Aliases belonging to alias-domains are prefixed with a '-', addresses of regular domains with a '+'. The output can be limited with an optional *pattern*. To perform a wild card search, the % character can be used at the start and/or the end of the *pattern*. If you do not 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*\] This command lists all defined relocated addresses. Relocated entries belonging to alias-domains are prefixed with a '-', addresses of regular domains with a '+'. The output can be limited with an optional *pattern*. To perform a wild card search, the % character can be used at the start and/or the end of the *pattern*. If you do not 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*\] This command lists all user accounts. User accounts belonging to alias-domains are prefixed with a '-', addresses of regular domains with a '+'. The output can be limited with an optional *pattern*. To perform a wild card search, the % character can be used at the start and/or the end of the *pattern*. If you do not 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 which could be used in the *vmm.cfg* as value of the *misc.password\_scheme* option. The output varies, depending on the used Dovecot version and the system's libc.\ 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 ``` ## DOMAIN SUBCOMMANDS ### domainadd (da) **vmm domainadd** *fqdn* \[**-n** *note*\] \[**-t** *transport*\] - **-n** *note* the note that should be set. - **-t** *transport* a Postfix transport (transport: or transport:nexthop). Adds the new domain into the database and creates the domain directory. If the optional argument *transport* is given, it will override the default transport (*domain.transport*) from *vmm.cfg*. The specified *transport* will be the default transport for all new accounts in this domain. Configuration-related behavior: - *domain.auto\_postmaster* When that option is set to **true** (default) **vmm** will automatically create the postmaster account for the new domain and prompt for **postmaster@***fqdn* 's password. - *account.random\_password* When the value of that option is also set to **true**, **vmm** will automatically create the postmaster account for the new domain and print the generated postmaster password to stdout. Examples: ``` 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 this option is given, **vmm** will delete the directory of the given domain. This overrides the *domain.delete\_directory* setting of *vmm.cfg*. - **--force** Use this option in oder to force the deletion of the domain, even if there are accounts, aliases, catch-all accounts and/or relocated users. This subcommand deletes the domain specified by *fqdn*. If there are accounts, aliases and/or relocated users assigned to the given domain, **vmm** will abort the requested operation and show an error message. If you know, what you are doing, you can specify the optional argument **--force**. If you really always know what you are doing, edit your *vmm.cfg* and set the option *domain.force\_deletion* to **true**. ### domaininfo (di) **vmm domaininfo** *fqdn* \[**-d** *details*\] This subcommand shows some information about the given domain. For a more detailed information about the domain the optional argument *details* can be specified. A possible *details* value can be one of the following 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 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**\] This subcommand is used to configure a new quota limit for the accounts of the domain - not for the domain itself. 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. If you want to restore the default to all accounts, you may pass the optional argument **--force**.\ When the argument *messages* 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 — with the given *fqdn* — use this subcommand. If you pass them after -e, each supplied *service* will be enabled/usable. If you pass them after -d, they will 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. 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. 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. In order to delete an existing note, 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 be also available in the alias domain.\ In the following 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. Postfix will immediately reject all e-mails addressed to nonexistent users.\ 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. 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. ``` ``` Example: **vmm aliasdomainswitch example.name example.org** ## ACCOUNT SUBCOMMANDS ### 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*. If the *password* is not provided, **vmm** will prompt for it interactively. 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. 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*. - **--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. 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*. 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 (**$**). 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. 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. 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)](/dsync/1.md) 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 ### 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. 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 *destination*s from the alias with the given *address*. When no *destination* address was specified the alias with all its destinations will be deleted. 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 ### 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 ### 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. 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 - */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)](/doveadm-pw/1.md), [**dsync**(1)](/dsync/1.md), [**transport**(5)](/transport/5.md), [**vmm.cfg**(5)](/vmm.cfg/5.md) ## INTERNET RESOURCES - Homepage http://vmm.localdomain.org/ - Project site http://sf.net/projects/vmm/ - Bug tracker https://bitbucket.org/pvo/vmm/issues ## COPYING vmm and its manual pages were written by Pascal Volk \ and are licensed under the terms of the BSD License.