xenial (1) vmm.1.gz

Provided by: vmm_0.6.2-1_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.