.TH "VMM" "1" "2011-02-24" "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 misc.transport

misc.transport = dovecot:

.B vmm configset misc.transport lmtp:unix:private/dovecot\-lmtp

.B vmm cg misc.transport

misc.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 70772

Account information

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

        UID............: 70772

        GID............: 70312

        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 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 ( misc.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

Enter new password:

Retype new password:

.B vmm cs account.random_password true

.B vmm domainadd sales.example.com

Generated password: hHu8DeTC

.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

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

        Domainname.....: sales.example.com

        GID............: 70698

        Transport......: dovecot:

        Domaindir......: /srv/mail/k/70698

        Quota Limit....: Storage: 0; Messages: 0

        Aliasdomains...: 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 " (" misc.quota_bytes " and " misc.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 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.name is an alias for

example.com.

.PP

Postfix will not accept erroneously e\-mails for unknown.user@example.name

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: