Provided by: vmm_0.7.0-0.2_all 
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 subcommands take one or more arguments.
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).
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) 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).
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) 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 destinations 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 destinations 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), dsync(1), transport(5), vmm.cfg(5)
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 <user+vmm AT
localhost.localdomain.org> and are licensed under the terms of the BSD License.