VMM/{,cli/}handler: Moved the 'address-in-use check' (introduced
with changeset ef99be5b7ec0) to {alias,relocated,user}_add().
=====
vmm
=====
----------------------------------------------------------
command line tool to manage email domains/accounts/aliases
----------------------------------------------------------
:Author: Pascal Volk <neverseen@users.sourceforge.net>
:Date: |today|
: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
-------------------
.. _configget:
``configget (cg) option``
This subcommand is used to display the actual value of the given
configuration *option*. The option has to be written as
*section*\ **.**\ *option*, e.g. **misc.transport**.
.. _configset:
``configset (cs) option value``
Use this subcommand to set/update a single configuration option. *option*
is the configuration option, written as *section*\ **.**\ *option*. *value*
is the *option*'s new value.
Example::
vmm configget misc.transport
misc.transport = dovecot:
vmm configset misc.transport lmtp:unix:private/dovecot-lmtp
vmm cg misc.transport
misc.transport = lmtp:unix:private/dovecot-lmtp
.. _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.
When |domain.auto_postmaster|_ is set to **true**, **vmm** will also create
an account for **postmaster@**\ *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 [ force ]``
This subcommand deletes the specified *domain*.
If there are accounts, aliases and/or relocated users 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 the keyword
**force**.
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. When no *password* is provided and |account.random_password|_
is set to **true**, **vmm** will generate a random password and print it to
stdout after the account has been created.
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 more services you can restrict
the access with this subcommand.
If no *service* was given all services (**smtp**, **pop3**, **imap**, and
**sieve**) will be disabled for the account with the specified *address*.
Otherwise only the specified *service*/s will be restricted.
Examples::
vmm u0 b.user@example.com imap pop3
vmm userdisable c.user@example.com
.. _userenable:
``userenable (u1) address [ service ... ]``
To allow access to one or more restricted services use this subcommand.
If no *service* was given all services (**smtp**, **pop3**, **imap**, and
**sieve**) will be enabled for the account with the specified *address*.
Otherwise only the specified *service*/s will be enabled.
.. _userdelete:
``userdelete (ud) address [ force ]``
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 **force**.
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