Provided by: vmm_0.7.0-0.2_all bug

NAME

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

SYNOPSIS

       vmm -h|-v|--help|--version
       vmm subcommand -h|--help
       vmm subcommand arguments [options]

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.

OPTIONS

       The following options are recognized by vmm.

       -h, --help
              show a list of available subcommands and exit.

       -v, --version
              show vmm's version and copyright information and exit.

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

   configset (cs)
       vmm configset option value

       Use this subcommand to set or update a single configuration option's value.  option is the
       configuration option, value is the option's new value.

       Note:  This subcommand will create a new  vmm.cfg  without  any  comments.   Your  current
              configuration file will be backed as vmm.cfg.bak.

       Example:

       vmm configget domain.transport
       domain.transport = dovecot:
       vmm configset domain.transport lmtp:unix:private/dovecot-lmtp
       vmm cg domain.transport
       domain.transport = lmtp:unix:private/dovecot-lmtp

   configure (cf)
       vmm configure [-s section]

       Starts the interactive configuration for all configuration sections.

       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.

       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   Account settings

              bin       Paths to external binaries

              database  Database settings

              domain    Domain settings

              mailbox   Mailbox settings

              misc      Miscellaneous settings

       All configuration options are described in vmm.cfg(5).

       Note:  This subcommand will create a new  vmm.cfg  without  any  comments.   Your  current
              configuration file will be backed as vmm.cfg.bak.

       Example:

       vmm configure -s 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

   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

   listdomains (ld)
       vmm listdomains [-p 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 -p %example%
       Matching domains
       ----------------
               [+] example.com
               [-]     e.g.example.com
               [-]     example.name
               [+] example.net
               [+] example.org

   listaddresses (ll)
       vmm listaddresses [-p 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.

       If  you  do not include an '@'-character in your pattern, the command will only match your
       pattern agains the fqdn of the addresses.  A  pattern  like  %user%@%example%  will  match
       against  any  address that contains the term 'user' in its local-part AND 'example' in its
       fqdn.

       Example:

       vmm listaddresses -p example.com
       vmm listaddresses -p %master@%

   listaliases (la)
       vmm listaliases [-p 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.

       If  you  do not include an '@'-character in your pattern, the command will only match your
       pattern agains the fqdn of the addresses.  A  pattern  like  %user%@%example%  will  match
       against  any  address that contains the term 'user' in its local-part AND 'example' in its
       fqdn.

       Example:

       vmm listaliases -p example.com
       vmm listaliases -p %master@%

   listrelocated (lr)
       vmm listrelocated [-p 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.

       If  you  do not include an '@'-character in your pattern, the command will only match your
       pattern agains the fqdn of the addresses.  A  pattern  like  %user%@%example%  will  match
       against  any  address that contains the term 'user' in its local-part AND 'example' in its
       fqdn.

       Example:

       vmm listrelocated -p example.com
       vmm listrelocated -p %master@%

   listusers (lu)
       vmm listusers [-p 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.

       If  you  do not include an '@'-character in your pattern, the command will only match your
       pattern agains the fqdn of the addresses.  A  pattern  like  %user%@%example%  will  match
       against  any  address that contains the term 'user' in its local-part AND 'example' in its
       fqdn.

       Example:

       vmm listusers -p example.com
       vmm listusers -p %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.
       Additionally a few usable encoding suffixes  will  be  displayed.   One  of  them  can  be
       appended to the password scheme.

       Example:

       vmm listpwschemes
       Usable password schemes
       -----------------------
               CLEARTEXT CRAM-MD5 CRYPT DIGEST-MD5 HMAC-MD5 LANMAN LDAP-MD5 MD5
               MD5-CRYPT NTLM OTP PLAIN PLAIN-MD4 PLAIN-MD5 RPA SHA SHA1 SHA256
               SHA256-CRYPT SHA512 SHA512-CRYPT SKEY SMD5 SSHA SSHA256 SSHA512

       Usable encoding suffixes
       ------------------------
               .B64 .BASE64 .HEX

DOMAIN SUBCOMMANDS

   domainadd (da)
       vmm domainadd fqdn [-n note] [-t transport]

       -n note
              the note that should be set.

       -t transport
              a Postfix transport (transport: or transport:nexthop).

       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 -t 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 [--delete-directory] [--force]

       --delete-directory
              When this option is given, vmm will delete the directory of the given domain.  This
              overrides the domain.delete_directory setting of vmm.cfg.

       --force
              Use this option in oder to force the deletion of the  domain,  even  if  there  are
              accounts, aliases, catch-all accounts and/or relocated users.

       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 argument --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 [-d 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 [-m 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  optional
       argument --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 (-e service ...| -d service ...)  [--force]

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

       If  you pass them after -e, each supplied service will be enabled/usable. If you pass them
       after -d, they will become 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  option
       --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  give  the  option
       --force.

       Example:

       vmm domaintransport support.example.com dovecot:

   domainnote (do)
       vmm domainnote fqdn -d|-n note

       -d     delete the domain's note.

       -n note
              the note that should be set.

       With  this  subcommand, it is possible to attach a note to the specified domain.  In order
       to delete an existing note, pass the -d option.

       Example:

       vmm do example.com -n `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 [-n note] [-p password]

       -n note
              the note that should be set.

       -p password
              the new user's 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 -p "A 5ecR3t P4s5\/\/0rd"
       vmm useradd e.user@example.com
       Enter new password:
       Retype new password:

   userdelete (ud)
       vmm userdelete address [--delete-directory] [--force]

       --delete-directory
              When  this  option  is  present, vmm will also delete the account's home directory.
              This overrides the account.delete_directory setting of vmm.cfg.

       --force
              When this option is given, vmm will delete the account, even if there  are  aliases
              with  the  account's  address  as their destination.  Those aliases will be deleted
              too.

       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, give the optional
       argument --force.

   userinfo (ui)
       vmm userinfo address [-d 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 -d|-n name

       -d     delete the user's name.

       -n name
              a user's real name.

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

       In order to delete the value stored for the account, pass the -d option.

       Example:

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

   userpassword (up)
       vmm userpassword address ([-p password] [-s scheme] | --hash pwhash])

       -p password
              The user's new password.

       -s scheme
              When  a  scheme  was  specified,  it  overrides  the  misc.password_scheme setting,
              configured in the vmm.cfg file.

       --hash pwhash
              A hashed password, prefixed with {SCHEME}; as generated by doveadm pw.  You  should
              enclose  the  hashed  password in single quotes, if it contains one ore more dollar
              signs ($).

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

       If no password or pwhash was provided, vmm will prompt for a password interactively.

       Note:  When passing a hashed password, vmm checks only if the included SCHEME is supported
              by your Dovecot installation.  No further checks are done.

       Example:

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

   usernote (uo)
       vmm usernote address -d|-n note

       -d     delete the user's note.

       -n note
              the note that should be set.

       With  this subcommand, it is possible to attach a note to the specified account.  In order
       to delete an existing note, pass the -d option.

       Example:

       vmm uo d.user@example.com -n `Only needed until end of May 2013'

   userquota (uq)
       vmm userquota address storage [-m 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 limit 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 (-e service ...| -d service ...| -r)

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

       If you pass services after -e, each service will be enabled/usable. If you pass them after
       -d they will be disabled/unusable. in order to restore the domain defaults on the address,
       pass -r without any more parameters.

       Example:

       vmm userservices d.user@example.com -d 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 local-parts 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

       doveadm-pw(1), 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.