Provided by: vmm_0.6.2-2_all bug

NAME

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

SYNOPSIS

       vmm subcommand [argument ...]

DESCRIPTION

       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.
       It's designed for Dovecot and Postfix with a PostgreSQL backend.

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

       Most of the subcommands take one or more arguments.

ARGUMENTS

       address     The complete e-mail  address  (local-part@fqdn)  of  an  user  account,  alias
                   address or relocated user.

       destination Is  either an e-mail address when used with ALIAS SUBCOMMANDS.  Or a fqdn when
                   used with ALIASDOMAIN SUBCOMMANDS.

       fqdn        The fully qualified domain name - without the trailing dot - of  a  domain  or
                   alias domain.

       messages    An  integer  value  which  specifies  a  quota limit in number of messages.  0
                   (zero) means unlimited - no quota limit for the number of messages.

       option      is the name of a configuration option, prefixed with the section  name  and  a
                   dot.  For example: misc.transport
                   All configuration options are described in vmm.cfg(5).

       service     The  name  of  a service, commonly used with Dovecot.  Supported services are:
                   imap, pop3, sieve and smtp.

       storage     Specifies a quota limit in bytes.   One  of  the  following  prefixes  can  be
                   appended  to  the  integer value: b (bytes), k (kilobytes), M (megabytes) or G
                   (gigabytes).  0 (zero) means unlimited - no quota limit in bytes.

       transport   A transport for Postfix, written as:  transport:  or  transport:nexthop.   See
                   transport(5) for more details.

GENERAL SUBCOMMANDS

   configget (cg)
       vmm configget option

       This subcommand is used to display the actual value of the given configuration option.

       Example:

       vmm configget misc.crypt_sha512_rounds
       misc.crypt_sha512_rounds = 5000

   getuser (gu)
       vmm getuser uid

       If  only  the uid is available, for example from process list, the subcommand getuser will
       show the user's address.

       Example:

       vmm getuser 79876
       Account information
       -------------------
               UID............: 79876
               GID............: 70704
               Address........: a.user@example.com

   help (h)
       vmm help [subcommand]

       Prints a list of available subcommands  with  a  short  description  to  stdout.   When  a
       subcommand was given, help for that subcommand will be displayed.  After this vmm exits.

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

   listaddresses (ll)
       vmm listaddresses [pattern]

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

       To  perform a wild card search, the % character can be used at the start and/or the end of
       the pattern.

       Example:

       vmm listaddresses example.com
       vmm listaddresses %master@%

   listaliases (la)
       vmm listaliases [pattern]

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

       To perform a wild card search, the % character can be used at the start and/or the end  of
       the pattern.

       Example:

       vmm listaliases example.com
       vmm listaliases %master@%

   listrelocated (lr)
       vmm listrelocated [pattern]

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

       To  perform a wild card search, the % character can be used at the start and/or the end of
       the pattern.

       Example:

       vmm listrelocated example.com
       vmm listrelocated %master@%

   listusers (lu)
       vmm listusers [pattern]

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

       To perform a wild card search, the % character can be used at the start and/or the end  of
       the pattern.

       Example:

       vmm listusers example.com
       vmm listusers %master@%

   listpwschemes (lp)
       vmm listpwschemes

       This  subcommand lists all password schemes which could be used in the vmm.cfg as value of
       the misc.password_scheme option.  The output varies, depending on the used Dovecot version
       and the system's libc.
       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.

       Example:

       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

   version (v)
       vmm version

       Prints vmm's version and copyright information to stdout.  After this vmm exits.

DOMAIN SUBCOMMANDS

   domainadd (da)
       vmm domainadd fqdn [transport]

       Adds the new domain into the database and creates the domain directory.

       If the optional argument transport is  given,  it  will  override  the  default  transport
       (domain.transport)  from  vmm.cfg.   The specified transport will be the default transport
       for all new accounts in this domain.

       Configuration-related behavior:

              domain.auto_postmaster
                     When that option is set to true (default) vmm will automatically create  the
                     postmaster  account  for  the  new  domain  and prompt for postmaster@fqdn's
                     password.

              account.random_password
                     When the value of that option is also set to true,  vmm  will  automatically
                     create  the  postmaster  account  for the new domain and print the generated
                     postmaster password to stdout.

       Examples:

       vmm domainadd support.example.com smtp:[mx1.example.com]:2025
       Creating account for postmaster@support.example.com
       Enter new password:
       Retype new password:
       vmm cs account.random_password true
       vmm domainadd sales.example.com
       Creating account for postmaster@sales.example.com
       Generated password: pLJUQ6Xg_z

   domaindelete (dd)
       vmm domaindelete fqdn [force]

       This subcommand deletes the domain specified by fqdn.

       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 optional keyword force.

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

   domaininfo (di)
       vmm domaininfo fqdn [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 can be one of the following six keywords:

              accounts      to list the e-mail addresses of all existing user accounts

              aliasdomains  to list all assigned alias domain names

              aliases       to list all available alias e-mail addresses

              catchall      to list all catch-all destinations

              relocated     to list the e-mail addresses of all relocated users

              full          to list all information mentioned above

       Example:

       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

   domainquota (dq)
       vmm domainquota fqdn storage [messages] [force]

       This subcommand is used to configure a new quota limit for the accounts of  the  domain  -
       not for the domain itself.

       The  default  quota  limit  for accounts is defined in the vmm.cfg (domain.quota_bytes and
       domain.quota_messages).

       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
       force.
       When the argument messages was omitted the default number of messages  0  (zero)  will  be
       applied.

       Example:

       vmm domainquota example.com 1g force

   domainservices (ds)
       vmm domainservices fqdn [service ...]  [force]

       To  define which services could be used by the users of the domain — with the given fqdn —
       use this subcommand.

       Each  specified  service  will  be   enabled/usable.    All   other   services   will   be
       deactivated/unusable.  Possible service names are: imap, pop3, sieve and smtp.
       The  new  service  set  will  affect  only  those  accounts for which the set has not been
       overridden. If you want to restore the default to all accounts, you may pass  the  keyword
       force.

   domaintransport (dt)
       vmm domaintransport fqdn transport [force]

       A new transport for the indicated domain can be set with this subcommand.

       The  new  transport  will  affect only those accounts for which the transport has not been
       overridden. If you want to restore the default to all accounts, you may pass  the  keyword
       force.

       Example:

       vmm domaintransport support.example.com dovecot:

   domainnote (do)
       vmm domainnote fqdn [note]

       With  this subcommand, it is possible to attach a note to the specified domain. Without an
       argument, an existing note is removed.

       Example:

       vmm do example.com Belongs to Robert

ALIAS DOMAIN SUBCOMMANDS

       An alias domain is an alias for a domain that was previously  added  with  the  subcommand
       domainadd.   All  accounts,  aliases  and  relocated  users  from  the domain will be also
       available in the alias domain.
       In the following is to be assumed that example.net is an alias for example.com.

       Postfix will not accept erroneously e-mails for unknown.user@example.net and  bounce  them
       back  later  to  the  mostly  faked  sender.   Postfix will immediately reject all e-mails
       addressed to nonexistent users.
       This behavior is ensured as long as you use  the  recommended  database  queries  in  your
       $config_directory/pgsql-*.cf configuration files.

   aliasdomainadd (ada)
       vmm aliasdomainadd fqdn destination

       This  subcommand adds the new alias domain (fqdn) to the destination domain that should be
       aliased.

       Example:

       vmm aliasdomainadd example.net example.com

   aliasdomaindelete (add)
       vmm aliasdomaindelete fqdn

       Use this subcommand if the alias domain fqdn should be removed.

       Example:

       vmm aliasdomaindelete e.g.example.com

   aliasdomaininfo (adi)
       vmm aliasdomaininfo fqdn

       This subcommand shows to which domain the alias domain fqdn is assigned to.

       Example:

       vmm adi example.net
       Alias domain information
       ------------------------
               The alias domain example.net belongs to:
                   * example.com

   aliasdomainswitch (ads)
       vmm aliasdomainswitch fqdn destination

       If the destination of the existing  alias  domain  fqdn  should  be  switched  to  another
       destination use this subcommand.

       Example:

       vmm aliasdomainswitch example.name example.org

ACCOUNT SUBCOMMANDS

   useradd (ua)
       vmm useradd address [password]

       Use this subcommand to create a new e-mail 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 useradd e.user@example.com
       Enter new password:
       Retype new password:

   userdelete (ud)
       vmm userdelete 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.

   userinfo (ui)
       vmm userinfo 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  the  user's  mail  directory.   In  order  to
                      summarize   the   disk   usage   each  time  this  subcommand  is  executed
                      automatically, set account.disk_usage in your vmm.cfg to true.

              full    to list all information mentioned above

       Example:

       vmm ui d.user@example.com
       Account information
       -------------------
               Address..........: d.user@example.com
               Name.............: None
               UID..............: 79881
               GID..............: 70704
               Home.............: /srv/mail/2/70704/79881
               Mail_Location....: mdbox:~/mdbox
               Quota Storage....: [  0.00%] 0/500.00 MiB
               Quota Messages...: [  0.00%] 0/10,000
               Transport........: lmtp:unix:private/dovecot-lmtp
               SMTP.............: disabled
               POP3.............: disabled
               IMAP.............: enabled
               SIEVE............: enabled

   username (un)
       vmm username address [name]

       The user's real name can be set/updated with this subcommand.

       If no name is given, the value stored for the account is erased.

       Example:

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

   userpassword (up)
       vmm userpassword address [password]

       The password of an account can be updated with this subcommand.

       If no password was provided, vmm will prompt for it interactively.

       Example:

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

   usernote (uo)
       vmm usernote address [note]

       With this subcommand, it is possible to attach a note to the specified account. Without an
       argument, an existing note is removed.

       Example:

       vmm uo d.user@example.com Only needed until end of May 2012

   userquota (uq)
       vmm userquota address storage [messages]

       This subcommand is used to set a new quota limit for the given account.

       When  the  argument  messages  was omitted the default number of messages 0 (zero) will be
       applied.

       Instead of storage pass the  keyword  domain  to  remove  the  account-specific  override,
       causing the domain's value to be in effect.

       Example:

       vmm userquota d.user@example.com 750m

   userservices (us)
       vmm userservices address [service ...]

       To grant a user access to the specified services, use this command.

       All omitted services will be deactivated/unusable for the user with the given address.

       Instead  of  service  pass  'domain'  to remove the account-specific override, causing the
       domain's value to be in effect.

       Example:

       vmm userservices d.user@example.com SMTP IMAP

   usertransport (ut)
       vmm usertransport address transport

       A different transport for an account can be specified with this subcommand.

       Instead of transport pass 'domain' to remove the account-specific  override,  causing  the
       domain's value to be in effect.

       Example:
       Assumed you want to use Dovecot's dsync(1) to convert a user's mailbox from Maildir format
       to mdbox format, you can tell Postfix to retry later.

       vmm ut d.user@example.com "retry:4.0.0 Mailbox being migrated"
       # convert the mailbox ... then set the transport to Dovecot's lmtp
       vmm ut d.user@example.com lmtp:unix:private/dovecot-lmtp

ALIAS SUBCOMMANDS

   aliasadd (aa)
       vmm aliasadd address destination ...

       This subcommand is used to create a  new  alias  address  with  one  or  more  destination
       addresses.

       Within  the  destination  address, the placeholders %n, %d, and %= will be replaced by the
       local part, the domain, or the email address with '@' replaced  by  '='  respectively.  In
       combination with alias domains, this enables domain-specific destinations.

       Examples:

       vmm aliasadd john.doe@example.com d.user@example.com
       vmm aa support@example.com d.user@example.com e.user@example.com
       vmm aa postmaster@example.com postmaster+%d@example.org

   aliasdelete (ad)
       vmm aliasdelete address [destination ...]

       This  subcommand  is  used  to delete one or multiple destinations from the alias with the
       given address.

       When no destination address was specified the alias with  all  its  destinations  will  be
       deleted.

       Example:

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

   aliasinfo (ai)
       vmm aliasinfo address

       Information about the alias with the given address can be displayed with this subcommand.

       Example:

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

RELOCATED SUBCOMMANDS

   relocatedadd (ra)
       vmm relocatedadd address newaddress

       A new relocated user can be created with this subcommand.

       address  is  the  user's  ex-email address, for example b.user@example.com, and newaddress
       points to the new email address where the user can be reached.

       Example:

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

   relocatedinfo (ri)
       vmm relocatedinfo address

       This subcommand shows the new address of the relocated user with the given address.

       Example:

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

   relocateddelete (rd)
       vmm relocateddelete address

       Use this subcommand in order to delete the relocated user with the given address.

       Example:

       vmm relocateddelete b.user@example.com

CATCH-ALL SUBCOMMANDS

   catchalladd (caa)
       vmm catchalladd fqdn destination ...

       This subcommand allows to specify destination addresses for a domain, which shall  receive
       mail  addressed  to unknown local parts within that domain.  Those catch-all aliases hence
       "catch all" mail to any address in the domain (unless a more specific  alias,  mailbox  or
       relocated entry exists).

       WARNING:  Catch-all  addresses  can  cause  mail  server flooding because spammers like to
       deliver mail to all possible  combinations  of  names,  e.g.   to  all  addresses  between
       abba@example.org and zztop@example.org.

       Example:

       vmm catchalladd example.com user@example.org

   catchallinfo (cai)
       vmm catchallinfo fqdn

       This subcommand displays information about catch-all aliases defined for a domain.

       Example:

       vmm catchallinfo example.com
       Catch-all information
       ---------------------
         Mail to unknown localparts in domain example.com will be sent to:
                * user@example.org

   catchalldelete (cad)
       vmm catchalldelete fqdn [destination ...]

       With this subcommand, catch-all aliases defined for a domain can be removed, either all of
       them, or those destinations which were specified explicitly.

       Example:

       vmm catchalldelete example.com 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

       dsync(1), transport(5), vmm.cfg(5)

INTERNET RESOURCES

       Homepage
              http://vmm.localdomain.org/

       Project site
              http://sf.net/projects/vmm/

       Bug tracker
              https://bitbucket.org/pvo/vmm/issues

COPYING

       vmm   and   its   manual   pages   were   written   by   Pascal    Volk    <user+vmm    AT
       localhost.localdomain.org> and are licensed under the terms of the BSD License.