# HG changeset patch # User Pascal Volk # Date 1298312354 0 # Node ID 2bc9c36c1387ac8750d67fbcf734341034b7dd08 # Parent 54a89c19e53410952580a10a5ae7bc5a292da339 man/man1: Reworked/updated vmm.1. Removed vmm.1.rst. reStructuredText was nice to edit but the generated output … diff -r 54a89c19e534 -r 2bc9c36c1387 man/man1/vmm.1 --- 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 diff -r 54a89c19e534 -r 2bc9c36c1387 man/man1/vmm.1.rst --- 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 -: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