NAME¶
vmm - command line tool to manage email domains/accounts/aliases
SYNOPSIS¶
vmm subcommand [
argument ...]
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.
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
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
help (h)¶
vmm help [
subcommand]
Prints a list of available subcommands with a short description to stdout. When
a
subcommand was given, help for that
subcommand will be
displayed. After this
vmm exits.
listdomains (ld)¶
vmm listdomains [
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 %example%
Matching domains
----------------
[+] example.com
[-] e.g.example.com
[-] example.name
[+] example.net
[+] example.org
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.
When your Dovecot installation isn't too old, you will see additionally a few
usable encoding suffixes. One of them can be appended to the password scheme.
Example:
vmm listpwschemes
Usable password schemes
-----------------------
CRYPT SHA512-CRYPT LDAP-MD5 DIGEST-MD5 SHA256 SHA512 SSHA512
SKEY SSHA NTLM RPA MD5-CRYPT HMAC-MD5 SHA1 PLAIN SHA CRAM-MD5
SSHA256 MD5 LANMAN CLEARTEXT PLAIN-MD5 PLAIN-MD4 OTP SMD5
SHA256-CRYPT
Usable encoding suffixes
------------------------
.B64 .BASE64 .HEX
version (v)¶
vmm version
Prints
vmm's version and copyright information to stdout. After this
vmm exits.
DOMAIN SUBCOMMANDS¶
domainadd (da)¶
vmm domainadd fqdn [
transport]
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 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 [
force]
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 keyword
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 [
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 five 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
- relocated
- to list the e-mail addresses of all relocated users
- catchall
- to list all catch-all destinations
- 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 [
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 keyword
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 [
service ...] [
force]
To define which services could be used by the users of the domain — with
the given
fqdn — use this subcommand.
Each specified
service will be enabled/usable. All other services will be
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 keyword
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 pass the keyword
force.
Example:
vmm domaintransport support.example.com dovecot:
domainnote (do)¶
vmm domainnote fqdn [
note]
With this subcommand, it is possible to attach a note to the specified domain.
Without an argument, an existing note is removed.
Example:
vmm do example.com 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 [
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 "A 5ecR3t P4s5\/\/0rd"
vmm useradd e.user@example.com
Enter new password:
Retype new password:
userdelete (ud)¶
vmm userdelete address [
force]
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, specify the optional keyword
force.
userinfo (ui)¶
vmm userinfo address [
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 the 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 [
name]
The user's real
name can be set/updated with this subcommand.
If no
name is given, the value stored for the account is erased.
Example:
vmm un d.user@example.com "John Doe"
userpassword (up)¶
vmm userpassword address [
password]
The password of an account can be updated with this subcommand.
If no
password was provided,
vmm will prompt for it interactively.
Example:
vmm up d.user@example.com "A |\/|0r3 5ecur3 P4s5\/\/0rd?"
usernote (uo)¶
vmm usernote address [
note]
With this subcommand, it is possible to attach a note to the specified account.
Without an argument, an existing note is removed.
Example:
vmm uo d.user@example.com Only needed until end of May 2012
userquota (uq)¶
vmm userquota address storage [
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
transport pass '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 [
service ...]
To grant a user access to the specified services, use this command.
All omitted services will be deactivated/unusable for the user with the given
address.
Instead of
transport pass 'domain' to remove the account-specific
override, causing the domain's value to be in effect.
Example:
vmm userservices d.user@example.com 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]
Use this subcommand to delete the alias with the given
address.
If the optional
destination address is given, only this destination will
be removed from the alias.
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 localparts 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 a single one if 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¶
dsync(1),
transport(5),
vmm.cfg(5)
INTERNET RESOURCES¶
- Wiki
- 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.