=====
 vmm
=====

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

:Author:         Pascal Volk <neverseen@users.sourceforge.net>
:Date:           2010-01-30
:Version:        vmm-0.6.0
:Manual group:   vmm Manual
:Manual section: 1

.. contents::
  :backlinks: top
  :class: htmlout

SYNOPSIS
========
**vmm** *subcommand* *object* [ *arguments* ]


DESCRIPTION
===========
**vmm** (a virtual mail manager) is a command line tool for
administrators/postmasters to manage (alias) domains, accounts and alias
addresses. It's designed for Dovecot and Postfix with a PostgreSQL backend.


SUBCOMMANDS
===========
Each subcommand has both a long and a short form. The short form is shown
enclosed in parentheses. Both forms are case sensitive.


GENERAL SUBCOMMANDS
-------------------
.. _configure:

``configure (cf) [ section ]``
  Starts the interactive configuration for all configuration sections.

  In this process the currently set value of each option will be shown in
  square brackets. If no value is configured, the default value of each
  option will be displayed in square brackets. Pres the enter key, to accept
  the displayed value.

  If the optional argument *section* is given, only the configuration
  options from the given section will be displayed and will be
  configurable. The following sections are available:

  | - **account**
  | - **bin**
  | - **database**
  | - **domain**
  | - **maildir**
  | - **misc**

  Example::

    vmm configure domain
    Using configuration file: /usr/local/etc/vmm.cfg

    * Configuration section: “domain”
    Enter new value for option directory_mode [504]:
    Enter new value for option delete_directory [True]: no
    Enter new value for option auto_postmaster [True]:
    Enter new value for option force_deletion [True]: off

.. _getuser:

``getuser (gu) userid``
  If only the *userid* is available, for example from process list, the
  subcommand **getuser** will show the user's address.

  Example::

    vmm getuser 70004
    Account information
    -------------------
            UID............: 70004
            GID............: 70000
            Address........: c.user@example.com

.. _listdomains:

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

.. _help:

``help (h)``
  Prints all available subcommands to stdout. After this **vmm** exits.

.. _version:

``version (v)``
  Prints the version information from **vmm**.


DOMAIN SUBCOMMANDS
------------------
.. _domainadd:

``domainadd (da) domain [ transport ]``
  Adds the new *domain* into the database and creates the domain directory.

  If the optional argument *transport* is given, it will overwrite the
  default transport (|misc.transport|_) from |vmm.cfg(5)|_. The specified
  *transport* will be the default transport for all new accounts in this
  domain.

  Examples::

    vmm domainadd support.example.com smtp:mx1.example.com
    vmm domainadd sales.example.com

.. _domaininfo:

``domaininfo (di) domain [ 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 may be one of the
  following five keywords:

  ``accounts``
    to list all existing accounts
  ``aliasdomains``
    to list all assigned alias domains
  ``aliases``
    to list all available aliases addresses
  ``relocated``
    to list all relocated users
  ``full``
    to list all information mentioned above

  Example::

    vmm domaininfo sales.example.com
    Domain information
    ------------------
            Domainname.....: sales.example.com
            GID............: 70002
            Transport......: dovecot:
            Domaindir......: /home/mail/5/70002
            Aliasdomains...: 0
            Accounts.......: 0
            Aliases........: 0
            Relocated......: 0

.. _domaintransport:

``domaintransport (dt) domain transport [ force ]``
  A new *transport* for the indicated *domain* can be set with this
  subcommand.

  If the additional keyword **force** is given all account specific
  transport settings will be overwritten. Otherwise this setting will affect
  only new created accounts.

  Example::

    vmm domaintransport support.example.com dovecot:

.. _domaindelete:

``domaindelete (dd) domain [ delalias | deluser | delall ]``
  This subcommand deletes the specified *domain*.

  If there are accounts and/or aliases 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 one of the following keywords:
  **delalias**, **deluser** or **delall**.

  If you really always know what you are doing, edit your *vmm.cfg* and set
  the option |domain.force_deletion|_ to true.


ALIAS DOMAIN SUBCOMMANDS
------------------------
.. _aliasdomainadd:

``aliasdomainadd (ada) aliasdomain targetdomain``
  This subcommand adds the new *aliasdomain* to the *targetdomain* that
  should be aliased.

  Example::

    vmm aliasdomainadd example.name example.com

.. _aliasdomaininfo:

``aliasdomaininfo (adi) aliasdomain``
  This subcommand shows to which domain the *aliasdomain* is assigned to.

  Example::

    vmm aliasdomaininfo example.name
    Alias domain information
    ------------------------
            The alias domain example.name belongs to:
                * example.com

.. _aliasdomainswitch:

``aliasdomainswitch (ads) aliasdomain targetdomain``
  If the target of the existing *aliasdomain* should be switched to another
  *targetdomain* use this subcommand.

  Example::

    vmm aliasdomainswitch example.name example.org

.. _aliasdomaindelete:

``aliasdomaindelete (add) aliasdomain``
  Use this subcommand if the alias domain *aliasdomain* should be removed.

  Example::

    vmm aliasdomaindelete e.g.example.com


ACCOUNT SUBCOMMANDS
-------------------
.. _useradd:

``useradd (ua) address [ password ]``
  Use this subcommand to create a new email account for the given *address*.

  If the *password* is not provided, **vmm** will prompt for it
  interactively.

  Examples::

    vmm ua d.user@example.com 'A 5ecR3t P4s5\\/\\/0rd'
    vmm ua e.user@example.com
    Enter new password:
    Retype new password:

.. _userinfo:

``userinfo (ui) 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 a user's Maildir. In order to summarize the
    disk usage each time the this subcommand is executed automatically, set
    |account.disk_usage|_ in the *vmm.cfg* to true.
  ``full``
    to list all information mentioned above

.. _username:

``username (un) address "User's Name"``
  The user's real name can be set/updated with this subcommand.

  Example::

    vmm un d.user@example.com 'John Doe'

.. _userpassword:

``userpassword (up) address [ password ]``
  The *password* from an account can be updated with this subcommand.

  If the *password* is not provided, **vmm** will prompt for it
  interactively.

  Example::

    vmm up d.user@example.com 'A |\\/|0r3 5ecur3 P4s5\\/\\/0rd?'

.. _usertransport:

``usertransport (ut) address transport``
  A different *transport* for an account can be specified with this
  subcommand.

  Example::

    vmm ut d.user@example.com smtp:pc105.it.example.com

.. _userdisable:

``userdisable (u0) address [ service ]``
  If a user shouldn't have access to one or all services you can restrict
  the access with this subcommand.

  If neither a *service* nor the keyword **all** is given all services
  (**smtp**, **pop3**, **imap**, and **sieve**) will be disabled for the
  account with the specified *address*. Otherwise only the specified
  *service* will be restricted.

  Examples::

    vmm u0 b.user@example.com imap
    vmm userdisable c.user@example.com

.. _userenable:

``userenable (u1) address [ service ]``
  To allow access to one or all restricted services use this subcommand.

  If neither a *service* nor the keyword **all** is given all services
  (**smtp**, **pop3**, **imap**, and **sieve**) will be enabled for the
  account with the specified *address*. Otherwise only the specified
  *service* will be enabled.

.. _userdelete:

``userdelete (ud) address [ delalias ]``
  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 **delalias**.


ALIAS SUBCOMMANDS
-----------------
.. _aliasadd:

``aliasadd (aa) alias target``
  This subcommand is used to create a new alias.

  Examples::

    vmm aliasadd john.doe@example.com d.user@example.com
    vmm aa support@example.com d.user@example.com
    vmm aa support@example.com e.user@example.com

.. _aliasinfo:

``aliasinfo (ai) alias``
  Information about an alias can be displayed with this subcommand.

  Example::

    vmm aliasinfo support@example.com
    Alias information
    -----------------
            Mail for support@example.com will be redirected to:
                 * d.user@example.com
                 * e.user@example.com

.. _aliasdelete:

``aliasdelete (ad) alias [ target ]``
  Use this subcommand to delete the *alias*.

  If the optional destination address *target* is given, only this
  destination will be removed from the *alias*.

  Example::

    vmm ad support@example.com d.user@example.com


RELOCATED SUBCOMMANDS
---------------------
.. _relocatedadd:

``relocatedadd (ra) old_address new_address``
  A new relocated user can be created with this subcommand.

  *old_address* is the users ex-email address, for example
  b.user@example.com, and *new_address* points to the new email address
  where the user can be reached.

  Example::

    vmm relocatedadd b.user@example.com b-user@company.tld

.. _relocatedinfo:

``relocatedinfo (ri) old_address``
  This subcommand shows the new address of the relocated user with the
  *old_address*.

  Example::

    vmm relocatedinfo b.user@example.com
    Relocated information
    ---------------------
            User “b.user@example.com” has moved to “b-user@company.tld”

.. _relocateddelete:

``relocateddelete (rd) old_address``
  Use this subcommand in order to delete the relocated user with the
  *old_address*.

  Example::

    vmm relocateddelete b.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
========
|vmm.cfg(5)|_


COPYING
=======
vmm and its manual pages were written by Pascal Volk and are licensed under
the terms of the BSD License.

.. include:: ../substitute_links.rst
.. include:: ../substitute_links_1.rst