man/man1: Reworked/updated vmm.1.
Removed vmm.1.rst. reStructuredText was nice to edit but the generated output …
--- a/man/man1/vmm.1 Fri Feb 18 16:14:07 2011 +0000
+++ b/man/man1/vmm.1 Mon Feb 21 18:19:14 2011 +0000
@@ -1,423 +1,839 @@
-.TH "VMM" "1" "17 Aug 2009" "Pascal Volk"
+.TH "VMM" "1" "2011-02-21" "vmm 0.6" "vmm"
.SH NAME
vmm \- command line tool to manage email domains/accounts/aliases
+.\" -----------------------------------------------------------------------
.SH SYNOPSIS
.B vmm
-\fIsubcommand\fP \fIobject\fP [ \fIargs\fP ]
+.IR subcommand " [" "argument ..." ]
+.\" -----------------------------------------------------------------------
.SH DESCRIPTION
-\fBvmm\fP (Virtual Mail Manager) is a command line tool for
-administrators/postmasters to manage domains, accounts and aliases. It's
-designed for Dovecot and Postfix with a PostgreSQL backend.
-.SH SUBCOMMANDS
-Each subcommand has both a long and a short form. Both forms are case sensitive.
-.SS GENERAL SUBCOMMANDS
+.B 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.
+.br
+It\(aqs designed for Dovecot and Postfix with a PostgreSQL backend.
+.PP
+Each
+.I subcommand
+has both a long and a short form.
+The short form is shown enclosed in parentheses.
+Both forms are case sensitive.
+.PP
+Most of the
+.IR subcommand s
+take one or more
+.IR argument s.
+.\" -----------------------------------------------------------------------
+.SH ARGUMENTS
+.TP 12
+.I address
+The complete e\-mail address
+.RI ( local\-part @ fqdn )
+of an user account, alias address or relocated user.
+.\" --------------------------
.TP
-\fBconfigure\fP (\fBcf\fP) [ \fIsection\fP ]
-Starts the interactive configuration for all configuration sections.
-.br
-If the optional argument \fIsection\fP is given, only the configuration options
-from the given section will be displayed and will be configurable. The following
-sections are available:
-.RS
-.PD 0
+.I destination
+Is either an e\-mail
+.I address
+when used with
+.IR "ALIAS SUBCOMMANDS" .
+Or a
+.I fqdn
+when used with
+.IR "ALIASDOMAIN SUBCOMMANDS" .
+.\" --------------------------
.TP
--
-.B
-database
+.I fqdn
+The fully qualified domain name \- without the trailing dot \- of a domain
+or alias domain.
+.\" --------------------------
.TP
--
-.B
-maildir
+.I messages
+An integer value which specifies a quota limit in number of messages.
+.B 0
+(zero) means unlimited \- no quota limit for the number of messages.
+.\" --------------------------
.TP
--
-.B
-services
+.I option
+is the name of a configuration option, prefixed with the section name and a
+dot.
+For example:
+.IB misc . transport
+.br
+All configuration options are described in
+.BR vmm.cfg (5).
+.\" --------------------------
+.TP
+.I service
+The name of a service, commonly used with Dovecot.
+Supported services are:
+.BR imap ", " pop3 ", " sieve " and " smtp .
+.\" --------------------------
.TP
--
-.B
-domdir
+.I storage
+Specifies a quota limit in bytes.
+One of the following prefixes can be appended to the integer value:
+.BR b " (bytes), " k " (kilobytes), " M " (megabytes) or " G
+(gigabytes).
+.B 0
+(zero) means unlimited \- no quota limit in bytes.
+.\" --------------------------
.TP
--
-.B
-bin
-.TP
--
-.B
-misc
-.PD
-.RE
-.LP
+.I transport
+A transport for Postfix, written as:
+.IB transport :
+or
+.IB transport :\c
+.IR nexthop .
+See
+.BR transport (5)
+for more details.
+.\" -----------------------------------------------------------------------
+.SH GENERAL SUBCOMMANDS
+.SS configget (cg)
+.BI "vmm configget" " option"
+.PP
+This subcommand is used to display the actual value of the given
+configuration
+.IR option .
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm configure services\fP
- Using configuration file: /usr/local/etc/vmm.cfg
-
- * Config section: “services”
- Enter new value for option pop3 [True]:
- Enter new value for option smtp [True]:
- Enter new value for option imap [True]:
- Enter new value for option sieve [True]: false
+.B vmm configget misc.crypt_sha512_rounds
+misc.crypt_sha512_rounds = 5000
.fi
+.\" ------------------------------------
+.SS configset (cs)
+.B vmm configset
+.I option value
.PP
-.TP
-\fBgetuser\fP (\fBgu\fP) \fIuserid\fP
-If only the userid is available, for example from process list, the subcommand
-\fBgetuser\fP will show the user's address.
+Use this subcommand to set or update a single configuration option\(aqs
+value.
+.I option
+is the configuration option,
+.I value
+is the
+.IR option \(aqs
+new value.
+.IP Note:
+This subcommand will create a new
+.I vmm.cfg
+without any comments.
+Your current configuration file will be backed as
+.IR vmm.cfg.bak .
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm getuser 70004\fP
- Account information
- -------------------
- UID............: 70004
- GID............: 70000
- Address........: c.user@example.com
+.B vmm configget misc.transport
+misc.transport = dovecot:
+.B vmm configset misc.transport lmtp:unix:private/dovecot\-lmtp
+.B vmm cg misc.transport
+misc.transport = lmtp:unix:private/dovecot\-lmtp
.fi
-.\"
+.\" ------------------------------------
+.SS configure (cf)
+.B vmm configure
+.RI [ section ]
+.PP
+Starts the interactive configuration for all configuration sections.
+.PP
+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.
+.PP
+If the optional argument
+.I section
+is given, only the configuration options from the given section will be
+displayed and will be configurable.
+The following sections are available:
+.RS
+.TP 10
+.B account
+Account settings
+.TP
+.B bin
+Paths to external binaries
+.TP
+.B database
+Database settings
+.TP
+.B domain
+Domain settings
+.TP
+.B mailbox
+Mailbox settings
.TP
-\fBlistdomains\fP (\fBld\fP) [ \fIpattern\fP ]
-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 \fIpattern\fP.
-.br
-To perform a wild card search, the % character can be used at the start and/or
-the end of the \fIpattern\fP.
+.B misc
+Miscellaneous settings
+.RE
+.PP
+All configuration options are described in
+.BR vmm.cfg (5).
+.IP Note:
+This subcommand will create a new
+.I vmm.cfg
+without any comments.
+Your current configuration file will be backed as
+.IR vmm.cfg.bak .
+.PP
+Example:
+.PP
+.nf
+.B vmm configure mailbox
+Using configuration file: /usr/local/etc/vmm.cfg
+
+* Configuration section: \(aqmailbox\(aq
+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
+.fi
+.\" ------------------------------------
+.SS getuser (gu)
+.BI "vmm getuser" " uid"
+.PP
+If only the
+.I uid
+is available, for example from process list, the subcommand
+.B getuser
+will show the user\(aqs address.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm listdomains %example%\fP
- Matching domains
- ----------------
- [+] example.com
- [-] e.g.example.com
- [-] example.name
- [+] example.net
- [+] example.org
+.B vmm getuser 70772
+Account information
+-------------------
+ UID............: 70772
+ GID............: 70312
+ Address........: a.user@example.com
.fi
-.\"
-.TP
-\fBhelp\fP (\fBh\fP)
-Prints all available commands to stdout. After this \fBvmm\fP exits.
-.TP
-\fBversion\fP (\fBv\fP)
-Prints the version information from \fBvmm\fP.
-.\"
-.SS DOMAIN SUBCOMMANDS
-.TP
-\fBdomainadd\fP (\fBda\fP) \fIdomain\fP [ \fItransport\fP ]
-Adds the new \fIdomain\fP into the database.
-.br
-If the optional argument \fItransport\fP is given, it will overwrite the
-default transport from \fBvmm.cfg\fP (misc/transport). The specified transport
+.\" ------------------------------------
+.SS help (h)
+.B vmm help
+.RI [ subcommand ]
+.PP
+Prints a list of available subcommands with a short description to stdout.
+When a
+.I subcommand
+was given, help for that
+.I subcommand
+will be displayed.
+After this
+.B vmm
+exits.
+.\" ------------------------------------
+.SS listdomains (ld)
+.B vmm listdomains
+.RI [ pattern ]
+.PP
+This subcommand lists all available domains.
+All domain names will be prefixed either with `[+]\(aq, if the domain is a
+primary domain, or with `[-]\(aq, if it is an alias domain name.
+The output can be limited with an optional
+.IR pattern .
+.PP
+To perform a wild card search, the % character can be used at the start
+and/or the end of the
+.IR pattern .
+.PP
+Example:
+.PP
+.nf
+.B vmm listdomains %example%
+Matching domains
+----------------
+ [+] example.com
+ [\-] e.g.example.com
+ [\-] example.name
+ [+] example.net
+ [+] example.org
+.fi
+.\" ------------------------------------
+.SS version (v)
+.B vmm version
+.PP
+Prints
+.BR vmm \(aqs
+version and copyright information to stdout.
+After this
+.B vmm
+exits.
+.\" -----------------------------------------------------------------------
+.SH DOMAIN SUBCOMMANDS
+.SS domainadd (da)
+.B vmm domainadd
+.IR fqdn " [" transport ]
+.PP
+Adds the new domain into the database and creates the domain directory.
+.PP
+If the optional argument
+.I transport
+is given, it will override the default transport
+.RI ( misc.transport ") from " vmm.cfg .
+The specified
+.I transport
will be the default transport for all new accounts in this domain.
.PP
-.nf
- Examples:
-
- \fBvmm domainadd support.example.com smtp:mx1.example.com
- vmm domainadd sales.example.com\fP
-.fi
+Configuration\-related behavior:
+.RS
+.TP
+.I domain.auto_postmaster
+When that option is set to
+.BR true " (default) " vmm
+will automatically create the postmaster account for the new domain and
+prompt for
+.BI postmaster@ fqdn\c
+\(aqs password.
.TP
-\fBdomaininfo\fP (\fBdi\fP) \fIdomain\fP [ \fIdetails\fP ]
-This subcommand shows some information about the given \fIdomain\fP.
-.br
-For a more detailed information about the \fIdomain\fP the optional argument
-\fIdetails\fP can be specified. A possible \fIdetails\fP value may be one of
-the following five keywords:
+.I account.random_password
+When the value of that option is also set to
+.BR true ", " vmm
+will automatically create the postmaster account for the new domain and
+print the generated postmaster password to stdout.
+.RE
+.PP
+Examples:
+.PP
+.nf
+.B vmm domainadd support.example.com smtp:[mx1.example.com]:2025
+Enter new password:
+Retype new password:
+.B vmm cs account.random_password true
+.B vmm domainadd sales.example.com
+Generated password: hHu8DeTC
+.fi
+.\" ------------------------------------
+.SS domaindelete (dd)
+.BI "vmm domaindelete " fqdn
+.RB [ force ]
+.PP
+This subcommand deletes the domain specified by
+.IR fqdn .
+.PP
+If there are accounts, aliases and/or relocated users assigned to the given
+domain,
+.B vmm
+will abort the requested operation and show an error message.
+If you know, what you are doing, you can specify the optional keyword
+.BR force .
+.PP
+If you really always know what you are doing, edit your
+.I vmm.cfg
+and set the option
+.I domain.force_deletion
+to
+.BR true .
+.\" ------------------------------------
+.SS domaininfo (di)
+.B vmm domaininfo
+.IR fqdn \ [ details ]
+.PP
+This subcommand shows some information about the given domain.
+.PP
+For a more detailed information about the domain the optional argument
+.I details
+can be specified.
+A possible
+.I details
+value can be one of the following five keywords:
.RS
-.PD 0
-.TP
+.TP 14
.B accounts
-to list all existing accounts
+to list the e\-mail addresses of all existing user accounts
.TP
.B aliasdomains
-to list all assigned alias domains
+to list all assigned alias domain names
.TP
.B aliases
-to list all available aliases addresses
+to list all available alias e\-mail addresses
.TP
.B relocated
-to list all relocated users
+to list the e\-mail addresses of all relocated users
.TP
.B full
to list all information mentioned above
-.PD
.RE
-.LP
+.PP
+Example:
+.PP
.nf
- Example:
-
- \fBvmm domaininfo sales.example.com\fP
- Domain information
- ------------------
- Domainname.....: sales.example.com
- GID............: 70002
- Transport......: dovecot:
- Domaindir......: /home/mail/5/70002
- Aliasdomains...: 0
- Accounts.......: 0
- Aliases........: 0
- Relocated......: 0
-
+.B vmm domaininfo sales.example.com
+Domain information
+------------------
+ Domainname.....: sales.example.com
+ GID............: 70693
+ Transport......: dovecot:
+ Domaindir......: /home/mail/v/70693
+ Quota Limit....: Storage: 0 Messages 0
+ Aliasdomains...: 0
+ Accounts.......: 1
+ Aliases........: 0
+ Relocated......: 0
.fi
-.TP
-\fBdomaintransport\fP (\fBdt\fP) \fIdomain\fP \fItransport\fP [ \fIforce\fP ]
-A new transport for the indicated domain can be set with this subcommand.
+.\" ------------------------------------
+.SS domainquota (dq)
+.B vmm domainquota
+.IR "fqdn storage" " [" messages ]
+.RB [ force ]
+.PP
+This subcommand is used to configure a new quota limit for the accounts of
+the domain - not for the domain itself.
+.PP
+The default quota limit for accounts is defined in the
+.IR vmm.cfg " (" misc.quota_bytes " and " misc.quota_messages ).
+The new quota limit will be applied to all newly created accounts.
+If you want to apply the new quota limit also to existing accounts, you
+have to give the optional keyword
+.BR force .
.br
-If the additional keyword '\fBforce\fP' is given all account specific transport
-settings will be overwritten.
-.br
+When the argument
+.I messages
+was omitted the default number of messages
+.B 0
+(zero) will be applied.
+.PP
+Example:
+.PP
+.nf
+.B vmm domainquota example.com 1g force
+.fi
+.\" ------------------------------------
+.SS domaintransport (dt)
+.BI "vmm domaintransport" " fqdn transport"
+.RB [ force ]
+.PP
+A new transport for the indicated domain can be set with this subcommand.
+.PP
+If the optional keyword
+.B force
+is given all account specific transport settings will be also updated.
Otherwise this setting will affect only new created accounts.
.PP
+Example:
+.PP
.nf
- Example:
-
- \fBvmm domaintransport support.example.com dovecot:\fP
+.B vmm domaintransport support.example.com dovecot:
.fi
-.TP
-\fBdomaindelete\fP (\fBdd\fP) \fIdomain\fP [ \fIdelalias\fP | \fIdeluser\fP | \fIdelall\fP ]
-This subcommand deletes the specified \fIdomain\fP.
+.\" -----------------------------------------------------------------------
+.SH ALIAS DOMAIN SUBCOMMANDS
+An alias domain is an alias for a domain that was previously added with the
+subcommand
+.BR domainadd .
+All accounts, aliases and relocated users from the domain will be also
+available in the alias domain.
.br
-If there are accounts and/or aliases assigned to the given domain, \fBvmm\fP
-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: '\fBdelalias\fP', '\fBdeluser\fP' or '\fBdelall\fP'.
+In the following is to be assumed that example.name is an alias for
+example.com.
+.PP
+Postfix will not accept erroneously e\-mails for unknown.user@example.name
+and bounce them back later to the mostly faked sender.
+Postfix will immediately reject all e\-mails addressed to nonexistent
+users.
.br
-
-If you really always know what you are doing, edit your \fBvmm.cfg\fP and set
-the option \fIforcedel\fP, in section \fImisc\fP, to true.
-.\"
-.SS ALIAS DOMAIN SUBCOMMANDS
-.TP
-\fBaliasdomainaddd\fP (\fBada\fP) \fIaliasdomain\fP \fItargetdomain\fP
-This subcommand adds the new \fIaliasdomain\fP to the \fItargetdomain\fP that
-should be aliased.
+This behavior is ensured as long as you use the recommended database
+queries in your
+.I $config_directory/pgsql\-*.cf
+configuration files.
+.\" ------------------------------------
+.SS aliasdomainadd (ada)
+.BI "vmm aliasdomainadd" " fqdn destination"
+.PP
+This subcommand adds the new alias domain
+.RI ( fqdn )
+to the
+.I destination
+domain that should be aliased.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm aliasdomainadd example.name example.com\fP
+.B vmm aliasdomainadd example.name example.com
.fi
-.TP
-\fBaliasdomaininfo (\fBadi\fP) \fIaliasdomain\fP
-This subcommand shows to which domain the \fIaliasdomain\fP is assigned to.
+.\" ------------------------------------
+.SS aliasdomaindelete (add)
+.BI "vmm aliasdomaindelete" " fqdn"
+.PP
+Use this subcommand if the alias domain
+.I fqdn
+should be removed.
+.PP
+Example:
+.PP
+.nf
+.B vmm aliasdomaindelete e.g.example.com
+.fi
+.\" ------------------------------------
+.SS aliasdomaininfo (adi)
+.BI "vmm aliasdomaininfo" " fqdn"
+.PP
+This subcommand shows to which domain the alias domain
+.I fqdn
+is assigned to.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm aliasdomaininfo example.name\fP
- Alias domain information
- ------------------------
- The alias domain example.name belongs to:
- * example.com
+.B vmm adi example.name
+Alias domain information
+------------------------
+ The alias domain example.name belongs to:
+ * example.com
+.fi
+.\" ------------------------------------
+.SS aliasdomainswitch (ads)
+.BI "vmm aliasdomainswitch" " fqdn destination"
+.PP
+If the destination of the existing alias domain
+.I fqdn
+should be switched to another
+.I destination
+use this subcommand.
+.nf
+.PP
+Example:
+.PP
+.B vmm aliasdomainswitch example.name example.org
.fi
-.TP
-\fBaliasdomainswitch\fP (\fBads\fP) \fIaliasdomain\fP \fItargetdomain\fP
-If the target of the existing \fIaliasdomain\fP should be switched to another
-\fItargetdomain\fP use this subcommand.
+.\" -----------------------------------------------------------------------
+.SH ACCOUNT SUBCOMMANDS
+.SS useradd (ua)
+.B vmm useradd
+.IR address " [" password ]
+.PP
+Use this subcommand to create a new e\-mail account for the given
+.IR address .
.PP
-.nf
- Example:
-
- \fBvmm aliasdomainswitch example.name example.org\fP
-.fi
-.TP
-\fBaliasdomaindelete\fP (\fBadd\fP) \fIaliasdomain\fP
-Use this subcommand if the alias domain \fIaliasdomain\fP should be removed.
+If the
+.I password
+is not provided,
+.B vmm
+will prompt for it interactively.
+When no
+.I password
+is provided and
+.I account.random_password
+is set to
+.BR true ", " vmm
+will generate a random password and print it to stdout after the account
+has been created.
+.PP
+Examples:
.PP
.nf
- Example:
-
- \fBvmm aliasdomaindelete e.g.example.com\fP
+.B vmm ua d.user@example.com \(aqA 5ecR3t P4s5\(rs/\(rs/0rd\(aq
+.B vmm useradd e.user@example.com
+Enter new password:
+Retype new password:
.fi
-.\"
-.SS ACCOUNT SUBCOMMANDS
-.TP
-\fBuseradd\fP (\fBua\fP) \fIaddress\fP [ \fIpassword\fP ]
-Use this subcommand to create a new email account for the given \fIaddress\fP.
-.br
-If the \fIpassword\fP is not provided, \fBvmm\fP will prompt for it
-interactively.
+.\" ------------------------------------
+.SS userdelete (ud)
+.BI "vmm userdelete" " address"
+.RB [ force ]
+.PP
+Use this subcommand to delete the account with the given
+.IR address .
+.PP
+If there are one or more aliases with an identical destination address,
+.B vmm
+will abort the requested operation and show an error message.
+To prevent this, specify the optional keyword
+.BR force .
+.\" ------------------------------------
+.SS userdisable (u0)
+.BI "vmm userdisable" " address"
+.RI [ "service ..." ]
+.PP
+If a user should not be able to access one or more services you can
+restrict the user\(aqs access with this subcommand.
+.PP
+If no
+.I service
+was given all services
+.RB ( imap ", " pop3 ", " sieve " and " smtp )
+will be disabled for the account with the specified
+.IR address .
+Otherwise only the specified
+.IR service (s)
+will be restricted.
+.PP
+Examples:
.PP
.nf
- Examples:
-
- \fBvmm ua d.user@example.com 'A 5ecR3t P4s5\\/\\/0rd'\fP
- \fBvmm ua e.user@example.com\fP
- Enter new password:
- Retype new password:
+.B vmm u0 b.user@example.com imap pop3
+.B vmm userdisable c.user@example.com
.fi
-.TP
-\fBuserinfo\fP (\fBui\fP) \fIaddress\fP [ \fIdetails\fP ]
+.\" ------------------------------------
+.SS userenable (u1)
+.BI "vmm userenable" " address"
+.RI [ "service ..." ]
+.PP
+To allow access to one or more restricted
+.IR service (s)
+use this subcommand.
+.PP
+If no
+.I service
+was given all services
+.RB ( imap ", " pop3 ", " sieve " and " smtp )
+will be enabled for the account with the specified
+.IR address .
+Otherwise only the specified
+.IR service (s)
+will be enabled.
+.\" ------------------------------------
+.SS userinfo (ui)
+.B "vmm userinfo"
+.IR address " [" details ]
+.PP
This subcommand displays some information about the account specified by
-\fIaddress\fP.
-.br
-If the optional argument \fIdetails\fP is given some more information will be
-displayed.
-.br
-Possible values for \fIdetails\fP are:
+.IR address .
+.PP
+If the optional argument
+.I details
+is given some more information will be displayed.
+Possible values for
+.I details
+are:
.RS
-.PD 0
-.TP
+.TP 8
.B aliases
-to list all alias addresses with the destination \fIaddress\fP
+to list all alias addresses with the destination
+.I address
.TP
.B du
-to display the disk usage of users maildir
+to display the disk usage of the user\(aqs mail directory.
+In order to summarize the disk usage each time the this subcommand is
+executed automatically, set
+.I account.disk_usage
+in your
+.I vmm.cfg
+to
+.BR true .
.TP
.B full
to list all information mentioned above
-.PD
-.RE
-.LP
-.TP
-\fBusername\fP (\fBun\fP) \fIaddress\fP \fI'Users Name'\fP
-The user's real name can be set/updated with this subcommand.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm un d.user@example.com 'John Doe'\fP
+.B vmm ui d.user@example.com
+Account information
+-------------------
+ Address........: d.user@example.com
+ Name...........: None
+ UID............: 79839
+ GID............: 70312
+ Home...........: /srv/mail/8/70312/79839
+ Mail_Location..: mdbox:~/mdbox
+ Quota Storage..: [ 0.00%] 0/1.00 GiB
+ Quota Messages.: [ 0.00%] 0/0
+ Transport......: dovecot:
+ SMTP...........: enabled
+ POP3...........: enabled
+ IMAP...........: enabled
+ SIEVE..........: enabled
.fi
-.TP
-\fBuserpassword\fP (\fBup\fP) \fIaddress\fP [ \fIpassword\fP ]
-The \fIpassword\fP from an account can be updated with this subcommand.
-.br
-If the \fIpassword\fP is not provided, \fBvmm\fP will prompt for it
-interactively.
+.\" ------------------------------------
+.SS username (un)
+.BI "vmm username" " address name"
+.PP
+The user\(aqs real
+.I name
+can be set/updated with this subcommand.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm up d.user@example.com 'A |\\/|0r3 5ecur3 P4s5\\/\\/0rd?'\fP
+.B vmm un d.user@example.com \(dqJohn Doe\(dq
.fi
-.TP
-\fBusertransport\fP (\fBut\fP) \fIaddress\fP \fItransport\fP
-A different transport for an account can be specified with this subcommand.
+.\" ------------------------------------
+.SS userpassword (up)
+.BI "vmm userpassword" " address"
+.RI [ password ]
+.PP
+The password of an account can be updated with this subcommand.
+.PP
+If no
+.I password
+was provided,
+.B vmm
+will prompt for it interactively.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm ut d.user@example.com smtp:pc105.it.example.com\fP
+.B vmm up d.user@example.com \(aqA |\(rs/|0r3 5ecur3 P4s5\(rs/\(rs/0rd?\(aq
.fi
-.TP
-\fBuserdisable\fP (\fBu0\fP) \fIaddress\fP [ \fIservice\fP ]
-If a user shouldn't have access to one or all services you can restrict the
-access with this subcommand.
-.br
-If neither a \fIservice\fP nor the keyword '\fIall\fP' is given all services
-(\fIsmtp\fP, \fIpop3\fP, \fIimap\fP, and \fIsieve\fP) will be disabled for the
-account with the specified \fIaddress\fP. Otherwise only the specified
-\fIservice\fP will be restricted.
+.\" ------------------------------------
+.SS userquota (uq)
+.BI "vmm userquota" " address storage"
+.RI [ messages ]
+.PP
+This subcommand is used to set a new quota limit for the given account.
+.PP
+When the argument
+.I messages
+was omitted the default number of messages
+.B 0
+(zero) will be applied.
+.PP
+Example:
.PP
.nf
- Examples:
-
- \fBvmm u0 b.user@example.com imap\fP
- \fBvmm userdisable c.user@example.com\fP
+.B vmm userquota d.user@example.com 750m
.fi
-.TP
-\fBuserenable\fP (\fBu1\fP) \fIaddress\fP [ \fIservice\fP ]
-To allow access to one or all restricted services use this subcommand.
+.\" ------------------------------------
+.SS usertransport (ut)
+.BI "vmm usertransport" " address transport"
+.PP
+A different
+.I transport
+for an account can be specified with this subcommand.
+.PP
+Example:
.br
-If neither a \fIservice\fP nor the keyword '\fIall\fP' is given all services
-(\fIsmtp\fP, \fIpop3\fP, \fIimap\fP, and \fIsieve\fP) will be enabled for the
-account with the specified \fIaddress\fP. Otherwise only the specified
-\fIservice\fP will be enabled.
+Assumed you want to use Dovecot\(aqs
+.BR dsync (1)
+to convert a user\(aqs mailbox from Maildir format to mdbox format, you
+can tell Postfix to retry later.
.PP
-.TP
-\fBuserdelete\fP (\fBud\fP) \fIaddress\fP [ \fIdelalias\fP ]
-Use this subcommand to delete the account with the given \fIaddress\fP.
-.br
-If there are one or more aliases with an identical destination address,
-\fBvmm\fP will abort the requested operation and show an error message. To
-prevent this, specify the optional keyword '\fIdelalias\fP'.
-.\"
-.SS ALIAS SUBCOMMANDS
-.TP
-\fBaliasadd\fP (\fBaa\fP) \fIalias\fP \fItarget\fP
-This subcommand is used to create a new alias.
+.nf
+.B vmm ut d.user@example.com \(dqretry:4.0.0 Mailbox being migrated\(dq
+# convert the mailbox ... then set the transport to Dovecot\(aqs lmtp
+.B vmm ut d.user@example.com lmtp:unix:private/dovecot\-lmtp
+.fi
+.\" -----------------------------------------------------------------------
+.SH ALIAS SUBCOMMANDS
+.SS aliasadd (aa)
+.BI "vmm aliasadd" " address destination ..."
+.PP
+This subcommand is used to create a new alias
+.I address
+with one or more
+.I destination
+addresses.
+.PP
+Examples:
.PP
.nf
- Examples:
-
- \fBvmm aliasadd john.doe@example.com d.user@example.com\fP
- \fBvmm aa support@example.com d.user@example.com\fP
- \fBvmm aa support@example.com e.user@example.com\fP
+.B vmm aliasadd john.doe@example.com d.user@example.com
+.B vmm aa support@example.com d.user@example.com e.user@example.com
.fi
-.TP
-\fBaliasinfo\fP (\fBai\fP) \fIalias\fP
-Information about an alias can be displayed with this subcommand.
+.\" ------------------------------------
+.SS aliasdelete (ad)
+.BI "vmm aliasdelete" " address"
+.RI [ destination ]
+.PP
+Use this subcommand to delete the alias with the given
+.IR address .
+.PP
+If the optional
+.I destination
+address is given, only this
+destination will be removed from the alias.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm aliasinfo support@example.com\fP
- Alias information
- -----------------
- Mail for support@example.com will be redirected to:
- * d.user@example.com
- * e.user@example.com
+.B vmm ad support@example.com d.user@example.com
.fi
-.TP
-\fBaliasdelete\fP (\fBad\fP) \fIalias\fP [ \fItarget\fP ]
-Use this subcommand to delete the \fIalias\fP.
-.br
-If the optional destination address \fItarget\fP is given, only this
-destination will be removed from the \fIalias\fP.
+.\" ------------------------------------
+.SS aliasinfo (ai)
+.BI "vmm aliasinfo" " address"
+.PP
+Information about the alias with the given
+.I address
+can be displayed with this subcommand.
+.PP
+Example:
+.PP
+.nf
+.B vmm aliasinfo support@example.com
+Alias information
+-----------------
+ Mail for support@example.com will be redirected to:
+ * e.user@example.com
+.fi
+.\" -----------------------------------------------------------------------
+.SH RELOCATED SUBCOMMANDS
+.SS relocatedadd (ra)
+.BI "vmm relocatedadd" " address newaddress"
+.PP
+A new relocated user can be created with this subcommand.
+.PP
+.I address
+is the user\(aqs ex\-email address, for example b.user@example.com, and
+.I newaddress
+points to the new email address where the user can be reached.
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm ad support@example.com d.user@example.com\fP
+.B vmm relocatedadd b.user@example.com b\-user@company.tld
.fi
-.\"
-.SS RELOCATED SUBCOMMANDS
-.TP
-\fBrelocatedadd\fP (\fBra\fP) \fIold_address\fP \fInew_address\fP
-A new relocated user can be created with this subcommand.
-.br
-\fIold_address\fP is the users ex-email address, for example b.user@example.com,
-and \fInew_address\fP points to the new email address where the user can be
-reached.
+.\" ------------------------------------
+.SS relocatedinfo (ri)
+.BI "vmm relocatedinfo " address
+.PP
+This subcommand shows the new address of the relocated user with the given
+.IR address .
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm relocatedadd b.user@example.com b-user@company.tld\fP
+.B vmm relocatedinfo b.user@example.com
+Relocated information
+---------------------
+ User \(aqb.user@example.com\(aq has moved to \(aqb\-user@company.tld\(aq
.fi
-.TP
-\fBrelocatedinfo\fP (\fBri\fP) \fIold_address\fP
-This subcommand shows the new address of the relocated user with the
-\fIold_address\fP.
+.\" ------------------------------------
+.SS relocateddelete (rd)
+.BI "vmm relocateddelete " address
+.PP
+Use this subcommand in order to delete the relocated user with the given
+.IR address .
+.PP
+Example:
.PP
.nf
- Example:
-
- \fBvmm relocatedinfo b.user@example.com\fP
- Relocated information
- ---------------------
- User “b.user@example.com” has moved to “b-user@company.tld”
+.B vmm relocateddelete b.user@example.com
.fi
+.\" -----------------------------------------------------------------------
+.SH FILES
+.TP
+.I /root/vmm.cfg
+will be used when found.
+.TP
+.I /usr/local/etc/vmm.cfg
+will be used when the above file doesn\(aqt exist.
.TP
-\fBrelocateddelete\fP (\fBrd\fP) \fIold_address\fP
-Use this subcommand in order to delete the relocated user with the
-\fIold_address\fP.
-.PP
-.nf
- Example:
-
- \fBvmm relocateddelete b.user@example.com\fP
-.fi
-.\"
-.SH FILES
-/usr/local/etc/vmm.cfg
+.I /etc/vmm.cfg
+will be used when none of the both above mentioned files exists.
+.\" -----------------------------------------------------------------------
.SH SEE ALSO
-vmm.cfg(5), configuration file for vmm
-.SH AUTHOR
+.BR dsync (1),
+.BR transport (5),
+.BR vmm.cfg (5)
+.\" -----------------------------------------------------------------------
+.SH INTERNET RESOURCES
+.TP
+Wiki
+http://vmm.localdomain.org/
+.TP
+Project site
+http://sf.net/projects/vmm/
+.TP
+Bug tracker
+http://sf.net/tracker/?group_id=213727&atid=1026862
+.\" -----------------------------------------------------------------------
+.SH COPYING
\fBvmm\fP and its man pages were written by Pascal Volk
<\fIneverseen@users.sourceforge.net\fP> and are licensed under the terms of the
-BSD License.
+BSD License.
\ No newline at end of file
--- a/man/man1/vmm.1.rst Fri Feb 18 16:14:07 2011 +0000
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,513 +0,0 @@
-=====
- 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
-
-.. _domainquota:
-
-``domainquota (dq) domain storage [messages] [force]``
- This subcommand is used to configure a new quota limit for the accounts
- of *domain* - not for the *domain* itself.
-
- The default quota limit for accounts is defined in the *vmm.cfg*
- (|misc.quota_bytes|_ and |misc.quota_messages|_). The new quota limit
- will be applied to all newly created accounts. If you want to apply the
- new quota limit also to existing accounts, you have to give the optional
- keyword **force**.
-
- ``storage``
- specifies the quota limit in bytes. One of the prefixes can be appended
- to the integer value: **b** (bytes), **k** (kilobytes), **M**
- (megabytes) or **G** (gigabytes). **0** means unlimited - no quota limit.
- ``messages``
- this optional argument specifies the quota limit in number of messages.
- When it was omitted the messages limit will be set to 0. **0** means
- unlimited - no quota limit.
-
- Example::
-
- vmm domainquota example.com 1g force
-
-.. _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?'
-
-.. _userquota:
-
-``userquota (uq) address storage [messages]``
- This subcommand is used to set a new quota limit for the given account.
-
- ``storage``
- specifies the quota limit in bytes. One of the prefixes can be appended
- to the integer value: **b** (bytes), **k** (kilobytes), **M**
- (megabytes) or **G** (gigabytes). **0** means unlimited - no quota limit.
- ``messages``
- this optional argument specifies the quota limit in number of messages.
- When it was omitted the messages limit will be set to 0. **0** means
- unlimited - no quota limit.
-
- Example::
-
- vmm userquota d.user@example.com 750m
-
-.. _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 with one or more *target*
- addresses.
-
- Examples::
-
- vmm aliasadd john.doe@example.com d.user@example.com
- vmm aa support@example.com d.user@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