.SH NAME

vmm \- command line tool to manage email domains/accounts/aliases

.\" -----------------------------------------------------------------------

.SH SYNOPSIS

.B vmm

.BR   \-h | \-v | \-\-help | \-\-version

.\" --------------------------

.br

.BI vmm " subcommand " \-h \c

.RB | \-\-help

.\" --------------------------

.br

.BI vmm " subcommand"

.IR arguments " [" options ]

.\" -----------------------------------------------------------------------

.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 OPTIONS

The following options are recognized by

.BR vmm .

.TP

.BR \-h ", " \-\-help

show a list of available subcommands and exit.

.\" --------------------------

.TP

.BR \-v ", " \-\-version

show

.BR vmm \(aqs

version and copyright information and exit.

.\" -----------------------------------------------------------------------

.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

.RB [ \-s

.IR 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 \-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

.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 listdomains (ld)

.B vmm listdomains

.RB [ \-p

.IR 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 \-p %example%

Matching domains

----------------

        [+] example.com

        [\-]     e.g.example.com

        [\-]     example.name

        [+] example.net

        [+] example.org

.fi

.\" ------------------------------------

.SS listaddresses (ll)

.B vmm listaddresses

.RB [ \-p

.IR pattern ]

.PP

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

.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 listaddresses \-p example.com

.B vmm listaddresses \-p %master@%

.\" ------------------------------------

.SS listaliases (la)

.B vmm listaliases

.RB [ \-p

.IR pattern ]

.PP

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

.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 listaliases \-p example.com

.B vmm listaliases \-p %master@%

.\" ------------------------------------

.SS listrelocated (lr)

.B vmm listrelocated

.RB [ \-p

.IR pattern ]

.PP

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

.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 listrelocated \-p example.com

.B vmm listrelocated \-p %master@%

.\" ------------------------------------

.SS listusers (lu)

.B vmm listusers

.RB [ \-p

.IR pattern ]

.PP

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

.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 listusers \-p example.com

.B vmm listusers \-p %master@%

.\" ------------------------------------

.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

-----------------------

        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

.fi

.\" -----------------------------------------------------------------------

.SH DOMAIN SUBCOMMANDS

.SS domainadd (da)

.B vmm domainadd

.I fqdn

.RB [ \-t

.IR 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 \-t 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 argument

.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