Ignore build files related to Debian packaging
During Debian packaging, the package is built in ./debian/vmm/, and quilt is
used (./.pc/). Both directories contain only generated files and should hence
be ignored from the perspective of Mercurial.
.TH "VMM" "1" "2011-11-13" "vmm 0.6" "vmm"
.SH NAME
vmm \- command line tool to manage email domains/accounts/aliases
.\" -----------------------------------------------------------------------
.SH SYNOPSIS
.B vmm
.IR subcommand " [" "argument ..." ]
.\" -----------------------------------------------------------------------
.SH DESCRIPTION
.B 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.
.br
It's designed for Dovecot and Postfix with a PostgreSQL backend.
.PP
Each
.I subcommand
has both a long and a short form.
The short form is shown enclosed in parentheses.
Both forms are case sensitive.
.PP
Most of the
.IR subcommand s
take one or more
.IR argument s.
.\" -----------------------------------------------------------------------
.SH ARGUMENTS
.TP 12
.I address
The complete e\-mail address
.RI ( local\-part @ fqdn )
of an user account, alias address or relocated user.
.\" --------------------------
.TP
.I destination
Is either an e\-mail
.I address
when used with
.IR "ALIAS SUBCOMMANDS" .
Or a
.I fqdn
when used with
.IR "ALIASDOMAIN SUBCOMMANDS" .
.\" --------------------------
.TP
.I fqdn
The fully qualified domain name \- without the trailing dot \- of a domain
or alias domain.
.\" --------------------------
.TP
.I messages
An integer value which specifies a quota limit in number of messages.
.B 0
(zero) means unlimited \- no quota limit for the number of messages.
.\" --------------------------
.TP
.I option
is the name of a configuration option, prefixed with the section name and a
dot.
For example:
.IB misc . transport
.br
All configuration options are described in
.BR vmm.cfg (5).
.\" --------------------------
.TP
.I service
The name of a service, commonly used with Dovecot.
Supported services are:
.BR imap ", " pop3 ", " sieve " and " smtp .
.\" --------------------------
.TP
.I storage
Specifies a quota limit in bytes.
One of the following prefixes can be appended to the integer value:
.BR b " (bytes), " k " (kilobytes), " M " (megabytes) or " G
(gigabytes).
.B 0
(zero) means unlimited \- no quota limit in bytes.
.\" --------------------------
.TP
.I transport
A transport for Postfix, written as:
.IB transport :
or
.IB transport :\c
.IR nexthop .
See
.BR transport (5)
for more details.
.\" -----------------------------------------------------------------------
.SH GENERAL SUBCOMMANDS
.SS configget (cg)
.BI "vmm configget" " option"
.PP
This subcommand is used to display the actual value of the given
configuration
.IR option .
.PP
Example:
.PP
.nf
.B vmm configget misc.crypt_sha512_rounds
misc.crypt_sha512_rounds = 5000
.fi
.\" ------------------------------------
.SS configset (cs)
.B vmm configset
.I option value
.PP
Use this subcommand to set or update a single configuration option's value.
.I option
is the configuration option,
.I value
is the
.IR option 's
new value.
.IP Note:
This subcommand will create a new
.I vmm.cfg
without any comments.
Your current configuration file will be backed as
.IR vmm.cfg.bak .
.PP
Example:
.PP
.nf
.B vmm configget domain.transport
domain.transport = dovecot:
.B vmm configset domain.transport lmtp:unix:private/dovecot\-lmtp
.B vmm cg domain.transport
domain.transport = lmtp:unix:private/dovecot\-lmtp
.fi
.\" ------------------------------------
.SS configure (cf)
.B vmm configure
.RI [ section ]
.PP
Starts the interactive configuration for all configuration sections.
.PP
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.
.PP
If the optional argument
.I section
is given, only the configuration options from the given section will be
displayed and will be configurable.
The following sections are available:
.RS
.TP 10
.B account
Account settings
.TP
.B bin
Paths to external binaries
.TP
.B database
Database settings
.TP
.B domain
Domain settings
.TP
.B mailbox
Mailbox settings
.TP
.B misc
Miscellaneous settings
.RE
.PP
All configuration options are described in
.BR vmm.cfg (5).
.IP Note:
This subcommand will create a new
.I vmm.cfg
without any comments.
Your current configuration file will be backed as
.IR vmm.cfg.bak .
.PP
Example:
.PP
.nf
.B vmm configure 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
.fi
.\" ------------------------------------
.SS getuser (gu)
.BI "vmm getuser" " uid"
.PP
If only the
.I uid
is available, for example from process list, the subcommand
.B getuser
will show the user's address.
.PP
Example:
.PP
.nf
.B vmm getuser 79876
Account information
-------------------
UID............: 79876
GID............: 70704
Address........: a.user@example.com
.fi
.\" ------------------------------------
.SS help (h)
.B vmm help
.RI [ subcommand ]
.PP
Prints a list of available subcommands with a short description to stdout.
When a
.I subcommand
was given, help for that
.I subcommand
will be displayed.
After this
.B vmm
exits.
.\" ------------------------------------
.SS listdomains (ld)
.B vmm listdomains
.RI [ pattern ]
.PP
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
.IR pattern .
.PP
To perform a wild card search, the % character can be used at the start
and/or the end of the
.IR pattern .
.PP
Example:
.PP
.nf
.B vmm listdomains %example%
Matching domains
----------------
[+] example.com
[\-] e.g.example.com
[\-] example.name
[+] example.net
[+] example.org
.fi
.\" ------------------------------------
.SS listpwschemes (lp)
.B vmm listpwschemes
.PP
This subcommand lists all password schemes which could be used in the
.I vmm.cfg
as value of the
.I misc.password_scheme
option.
The output varies, depending on the used Dovecot version and the system's
libc.
.br
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.
.PP
Example:
.PP
.nf
.B 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
.fi
.\" ------------------------------------
.SS version (v)
.B vmm version
.PP
Prints
.BR vmm 's
version and copyright information to stdout.
After this
.B vmm
exits.
.\" -----------------------------------------------------------------------
.SH DOMAIN SUBCOMMANDS
.SS domainadd (da)
.B vmm domainadd
.IR fqdn " [" transport ]
.PP
Adds the new domain into the database and creates the domain directory.
.PP
If the optional argument
.I transport
is given, it will override the default transport
.RI ( domain.transport ") from " vmm.cfg .
The specified
.I transport
will be the default transport for all new accounts in this domain.
.PP
Configuration\-related behavior:
.RS
.TP
.I domain.auto_postmaster
When that option is set to
.BR true " (default) " vmm
will automatically create the postmaster account for the new domain and
prompt for
.BI postmaster@ fqdn\c
\(aqs password.
.TP
.I account.random_password
When the value of that option is also set to
.BR true ", " vmm
will automatically create the postmaster account for the new domain and
print the generated postmaster password to stdout.
.RE
.PP
Examples:
.PP
.nf
.B vmm domainadd support.example.com smtp:[mx1.example.com]:2025
Creating account for postmaster@support.example.com
Enter new password:
Retype new password:
.B vmm cs account.random_password true
.B vmm domainadd sales.example.com
Creating account for postmaster@sales.example.com
Generated password: pLJUQ6Xg_z
.fi
.\" ------------------------------------
.SS domaindelete (dd)
.BI "vmm domaindelete " fqdn
.RB [ force ]
.PP
This subcommand deletes the domain specified by
.IR fqdn .
.PP
If there are accounts, aliases and/or relocated users assigned to the given
domain,
.B vmm
will abort the requested operation and show an error message.
If you know, what you are doing, you can specify the optional keyword
.BR force .
.PP
If you really always know what you are doing, edit your
.I vmm.cfg
and set the option
.I domain.force_deletion
to
.BR true .
.\" ------------------------------------
.SS domaininfo (di)
.B vmm domaininfo
.IR fqdn \ [ details ]
.PP
This subcommand shows some information about the given domain.
.PP
For a more detailed information about the domain the optional argument
.I details
can be specified.
A possible
.I details
value can be one of the following five keywords:
.RS
.TP 14
.B accounts
to list the e\-mail addresses of all existing user accounts
.TP
.B aliasdomains
to list all assigned alias domain names
.TP
.B aliases
to list all available alias e\-mail addresses
.TP
.B relocated
to list the e\-mail addresses of all relocated users
.TP
.B full
to list all information mentioned above
.RE
.PP
Example:
.PP
.nf
.B 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
.fi
.\" ------------------------------------
.SS domainquota (dq)
.B vmm domainquota
.IR "fqdn storage" " [" messages ]
.RB [ force ]
.PP
This subcommand is used to configure a new quota limit for the accounts of
the domain - not for the domain itself.
.PP
The default quota limit for accounts is defined in the
.IR vmm.cfg " (" domain.quota_bytes " and " domain.quota_messages ).
The new quota limit will be applied to all newly created accounts.
If you want to apply the new quota limit also to existing accounts, you
have to give the optional keyword
.BR force .
.br
When the argument
.I messages
was omitted the default number of messages
.B 0
(zero) will be applied.
.PP
Example:
.PP
.nf
.B vmm domainquota example.com 1g force
.fi
.\" ------------------------------------
.SS domainservices (ds)
.B vmm domainservices
.IR fqdn " [" "service ..." ]
.RB [ force ]
.PP
To define which services could be used by the users of the domain \(em with
the given
.I fqdn
\(em use this subcommand.
.PP
Each specified
.I service
will be enabled/usable.
All other services will be deactivated/unusable.
Possible service names are:
.BR imap ", " pop3 ", " sieve " and " smtp .
.br
When the keyword
.B force
was omitted, the service setting will be the default for new created
accounts.
Otherwise it will additionally apply the settings to all existing accounts
of the domain.
.\" ------------------------------------
.SS domaintransport (dt)
.BI "vmm domaintransport" " fqdn transport"
.RB [ force ]
.PP
A new transport for the indicated domain can be set with this subcommand.
.PP
If the optional keyword
.B force
is given all account specific transport settings will be also updated.
Otherwise this setting will affect only new created accounts.
.PP
Example:
.PP
.nf
.B vmm domaintransport support.example.com dovecot:
.fi
.\" -----------------------------------------------------------------------
.SH ALIAS DOMAIN SUBCOMMANDS
An alias domain is an alias for a domain that was previously added with the
subcommand
.BR domainadd .
All accounts, aliases and relocated users from the domain will be also
available in the alias domain.
.br
In the following is to be assumed that example.net is an alias for
example.com.
.PP
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.
.br
This behavior is ensured as long as you use the recommended database
queries in your
.I $config_directory/pgsql\-*.cf
configuration files.
.\" ------------------------------------
.SS aliasdomainadd (ada)
.BI "vmm aliasdomainadd" " fqdn destination"
.PP
This subcommand adds the new alias domain
.RI ( fqdn )
to the
.I destination
domain that should be aliased.
.PP
Example:
.PP
.nf
.B vmm aliasdomainadd example.net example.com
.fi
.\" ------------------------------------
.SS aliasdomaindelete (add)
.BI "vmm aliasdomaindelete" " fqdn"
.PP
Use this subcommand if the alias domain
.I fqdn
should be removed.
.PP
Example:
.PP
.nf
.B vmm aliasdomaindelete e.g.example.com
.fi
.\" ------------------------------------
.SS aliasdomaininfo (adi)
.BI "vmm aliasdomaininfo" " fqdn"
.PP
This subcommand shows to which domain the alias domain
.I fqdn
is assigned to.
.PP
Example:
.PP
.nf
.B vmm adi example.net
Alias domain information
------------------------
The alias domain example.net belongs to:
* example.com
.fi
.\" ------------------------------------
.SS aliasdomainswitch (ads)
.BI "vmm aliasdomainswitch" " fqdn destination"
.PP
If the destination of the existing alias domain
.I fqdn
should be switched to another
.I destination
use this subcommand.
.nf
.PP
Example:
.PP
.B vmm aliasdomainswitch example.name example.org
.fi
.\" -----------------------------------------------------------------------
.SH ACCOUNT SUBCOMMANDS
.SS useradd (ua)
.B vmm useradd
.IR address " [" password ]
.PP
Use this subcommand to create a new e\-mail account for the given
.IR address .
.PP
If the
.I password
is not provided,
.B vmm
will prompt for it interactively.
When no
.I password
is provided and
.I account.random_password
is set to
.BR true ", " vmm
will generate a random password and print it to stdout after the account
has been created.
.PP
Examples:
.PP
.nf
.B vmm ua d.user@example.com \(dqA 5ecR3t P4s5\(rs/\(rs/0rd\(dq
.B vmm useradd e.user@example.com
Enter new password:
Retype new password:
.fi
.\" ------------------------------------
.SS userdelete (ud)
.BI "vmm userdelete" " address"
.RB [ force ]
.PP
Use this subcommand to delete the account with the given
.IR address .
.PP
If there are one or more aliases with an identical destination address,
.B vmm
will abort the requested operation and show an error message.
To prevent this, specify the optional keyword
.BR force .
.\" ------------------------------------
.SS userinfo (ui)
.B "vmm userinfo"
.IR address " [" details ]
.PP
This subcommand displays some information about the account specified by
.IR address .
.PP
If the optional argument
.I details
is given some more information will be displayed.
Possible values for
.I details
are:
.RS
.TP 8
.B aliases
to list all alias addresses with the destination
.I address
.TP
.B 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
.I account.disk_usage
in your
.I vmm.cfg
to
.BR true .
.TP
.B full
to list all information mentioned above
.RE
.PP
Example:
.PP
.nf
.B 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
.fi
.\" ------------------------------------
.SS username (un)
.BI "vmm username" " address name"
.PP
The user's real
.I name
can be set/updated with this subcommand.
.PP
Example:
.PP
.nf
.B vmm un d.user@example.com \(dqJohn Doe\(dq
.fi
.\" ------------------------------------
.SS userpassword (up)
.BI "vmm userpassword" " address"
.RI [ password ]
.PP
The password of an account can be updated with this subcommand.
.PP
If no
.I password
was provided,
.B vmm
will prompt for it interactively.
.PP
Example:
.PP
.nf
.B vmm up d.user@example.com \(dqA |\(rs/|0r3 5ecur3 P4s5\(rs/\(rs/0rd?\(dq
.fi
.\" ------------------------------------
.SS userquota (uq)
.BI "vmm userquota" " address storage"
.RI [ messages ]
.PP
This subcommand is used to set a new quota limit for the given account.
.PP
When the argument
.I messages
was omitted the default number of messages
.B 0
(zero) will be applied.
.PP
Example:
.PP
.nf
.B vmm userquota d.user@example.com 750m
.fi
.\" ------------------------------------
.SS userservices (us)
.B vmm userservices
.IR address " [" "service ..." ]
.PP
To grant a user access to the specified services, use this command.
.PP
All omitted services will be deactivated/unusable for the user with the
given
.IR address .
.\" ------------------------------------
.SS usertransport (ut)
.BI "vmm usertransport" " address transport"
.PP
A different
.I transport
for an account can be specified with this subcommand.
.PP
Example:
.br
Assumed you want to use Dovecot's
.BR dsync (1)
to convert a user's mailbox from Maildir format to mdbox format, you
can tell Postfix to retry later.
.PP
.nf
.B vmm ut d.user@example.com \(dqretry:4.0.0 Mailbox being migrated\(dq
# convert the mailbox ... then set the transport to Dovecot's lmtp
.B vmm ut d.user@example.com lmtp:unix:private/dovecot\-lmtp
.fi
.\" -----------------------------------------------------------------------
.SH ALIAS SUBCOMMANDS
.SS aliasadd (aa)
.BI "vmm aliasadd" " address destination ..."
.PP
This subcommand is used to create a new alias
.I address
with one or more
.I destination
addresses.
.PP
Examples:
.PP
.nf
.B vmm aliasadd john.doe@example.com d.user@example.com
.B vmm aa support@example.com d.user@example.com e.user@example.com
.fi
.\" ------------------------------------
.SS aliasdelete (ad)
.BI "vmm aliasdelete" " address"
.RI [ destination ]
.PP
Use this subcommand to delete the alias with the given
.IR address .
.PP
If the optional
.I destination
address is given, only this
destination will be removed from the alias.
.PP
Example:
.PP
.nf
.B vmm ad support@example.com d.user@example.com
.fi
.\" ------------------------------------
.SS aliasinfo (ai)
.BI "vmm aliasinfo" " address"
.PP
Information about the alias with the given
.I address
can be displayed with this subcommand.
.PP
Example:
.PP
.nf
.B vmm aliasinfo support@example.com
Alias information
-----------------
Mail for support@example.com will be redirected to:
* e.user@example.com
.fi
.\" -----------------------------------------------------------------------
.SH RELOCATED SUBCOMMANDS
.SS relocatedadd (ra)
.BI "vmm relocatedadd" " address newaddress"
.PP
A new relocated user can be created with this subcommand.
.PP
.I address
is the user's ex\-email address, for example b.user@example.com, and
.I newaddress
points to the new email address where the user can be reached.
.PP
Example:
.PP
.nf
.B vmm relocatedadd b.user@example.com b\-user@company.tld
.fi
.\" ------------------------------------
.SS relocatedinfo (ri)
.BI "vmm relocatedinfo " address
.PP
This subcommand shows the new address of the relocated user with the given
.IR address .
.PP
Example:
.PP
.nf
.B vmm relocatedinfo b.user@example.com
Relocated information
---------------------
User `b.user@example.com' has moved to `b\-user@company.tld'
.fi
.\" ------------------------------------
.SS relocateddelete (rd)
.BI "vmm relocateddelete " address
.PP
Use this subcommand in order to delete the relocated user with the given
.IR address .
.PP
Example:
.PP
.nf
.B vmm relocateddelete b.user@example.com
.fi
.\" -----------------------------------------------------------------------
.SH FILES
.TP
.I /root/vmm.cfg
will be used when found.
.TP
.I /usr/local/etc/vmm.cfg
will be used when the above file doesn't exist.
.TP
.I /etc/vmm.cfg
will be used when none of the both above mentioned files exists.
.\" -----------------------------------------------------------------------
.SH SEE ALSO
.BR dsync (1),
.BR transport (5),
.BR vmm.cfg (5)
.\" -----------------------------------------------------------------------
.SH INTERNET RESOURCES
.TP
Wiki
http://vmm.localdomain.org/
.TP
Project site
http://sf.net/projects/vmm/
.TP
Bug tracker
https://bitbucket.org/pvo/vmm/issues
.\" -----------------------------------------------------------------------
.SH 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.