.TH "VMM" "1" "2012-09-02" "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 six 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 catchall

to list all catch\-all destinations

.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

        Catch-All Dests..: 1

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

.PP

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

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