diff options
Diffstat (limited to 'html/virtual.8.html')
| -rw-r--r-- | html/virtual.8.html | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/html/virtual.8.html b/html/virtual.8.html new file mode 100644 index 0000000..b15b4d4 --- /dev/null +++ b/html/virtual.8.html @@ -0,0 +1,332 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> +<title> Postfix manual - virtual(8) </title> +</head> <body> <pre> +VIRTUAL(8) VIRTUAL(8) + +<b>NAME</b> + virtual - Postfix virtual domain mail delivery agent + +<b>SYNOPSIS</b> + <b>virtual</b> [generic Postfix daemon options] + +<b>DESCRIPTION</b> + The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent is designed for virtual mail hosting ser- + vices. Originally based on the Postfix <a href="local.8.html"><b>local</b>(8)</a> delivery agent, this + agent looks up recipients with map lookups of their full recipient + address, instead of using hard-coded unix password file lookups of the + address local part only. + + This delivery agent only delivers mail. Other features such as mail + forwarding, out-of-office notifications, etc., must be configured via + virtual_alias maps or via similar lookup mechanisms. + +<b>MAILBOX LOCATION</b> + The mailbox location is controlled by the <b><a href="postconf.5.html#virtual_mailbox_base">virtual_mailbox_base</a></b> and <b><a href="postconf.5.html#virtual_mailbox_maps">vir</a>-</b> + <b><a href="postconf.5.html#virtual_mailbox_maps">tual_mailbox_maps</a></b> configuration parameters (see below). The <b><a href="postconf.5.html#virtual_mailbox_maps">vir-</b> + <b>tual_mailbox_maps</a></b> table is indexed by the recipient address as + described under TABLE SEARCH ORDER below. + + The mailbox pathname is constructed as follows: + + <b>$<a href="postconf.5.html#virtual_mailbox_base">virtual_mailbox_base</a>/$virtual_mailbox_maps(</b><i>recipient</i><b>)</b> + + where <i>recipient</i> is the full recipient address. + +<b>UNIX MAILBOX FORMAT</b> + When the mailbox location does not end in <b>/</b>, the message is delivered + in UNIX mailbox format. This format stores multiple messages in one + textfile. + + The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent prepends a "<b>From</b> <i>sender time</i><b>_</b><i>stamp</i>" enve- + lope header to each message, prepends a <b>Delivered-To:</b> message header + with the envelope recipient address, prepends an <b>X-Original-To:</b> header + with the recipient address as given to Postfix, prepends a <b>Return-Path:</b> + message header with the envelope sender address, prepends a > character + to lines beginning with "<b>From</b> ", and appends an empty line. + + The mailbox is locked for exclusive access while delivery is in + progress. In case of problems, an attempt is made to truncate the mail- + box to its original length. + +<b>QMAIL MAILDIR FORMAT</b> + When the mailbox location ends in <b>/</b>, the message is delivered in qmail + <b>maildir</b> format. This format stores one message per file. + + The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent prepends a <b>Delivered-To:</b> message header + with the final envelope recipient address, prepends an <b>X-Original-To:</b> + header with the recipient address as given to Postfix, and prepends a + <b>Return-Path:</b> message header with the envelope sender address. + + By definition, <b>maildir</b> format does not require application-level file + locking during mail delivery or retrieval. + +<b>MAILBOX OWNERSHIP</b> + Mailbox ownership is controlled by the <b><a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a></b> and <b><a href="postconf.5.html#virtual_gid_maps">vir</a>-</b> + <b><a href="postconf.5.html#virtual_gid_maps">tual_gid_maps</a></b> lookup tables, which are indexed with the full recipient + address. Each table provides a string with the numerical user and group + ID, respectively. + + The <b><a href="postconf.5.html#virtual_minimum_uid">virtual_minimum_uid</a></b> parameter imposes a lower bound on numerical + user ID values that may be specified in any <b><a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a></b>. + +<b>CASE FOLDING</b> + All delivery decisions are made using the full recipient address, + folded to lower case. See also the next section for a few exceptions + with optional address extensions. + +<b>TABLE SEARCH ORDER</b> + Normally, a lookup table is specified as a text file that serves as + input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The result, an indexed file in <b>dbm</b> or + <b>db</b> format, is used for fast searching by the mail system. + + The search order is as follows. The search stops upon the first suc- + cessful lookup. + + <b>o</b> When the recipient has an optional address extension the + <i>user+extension@domain.tld</i> address is looked up first. + + With Postfix versions before 2.1, the optional address extension + is always ignored. + + <b>o</b> The <i>user@domain.tld</i> address, without address extension, is + looked up next. + + <b>o</b> Finally, the recipient <i>@domain</i> is looked up. + + When the table is provided via other means such as NIS, LDAP or SQL, + the same lookups are done as for ordinary indexed files. + + Alternatively, a table can be provided as a regular-expression map + where patterns are given as regular expressions. In that case, only the + full recipient address is given to the regular-expression map. + +<b>SECURITY</b> + The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent is not security sensitive, provided that + the lookup tables with recipient user/group ID information are ade- + quately protected. This program is not designed to run chrooted. + + The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent disallows regular expression substitution + of $1 etc. in regular expression lookup tables, because that would open + a security hole. + + The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent will silently ignore requests to use the + <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server. Instead it will open the table directly. Before + Postfix version 2.2, the virtual delivery agent will terminate with a + fatal error. + +<b>STANDARDS</b> + <a href="http://tools.ietf.org/html/rfc822">RFC 822</a> (ARPA Internet Text Messages) + +<b>DIAGNOSTICS</b> + Mail bounces when the recipient has no mailbox or when the recipient is + over disk quota. In all other cases, mail for an existing recipient is + deferred and a warning is logged. + + Problems and transactions are logged to <b>syslogd</b>(8) or <a href="postlogd.8.html"><b>postlogd</b>(8)</a>. + Corrupted message files are marked so that the queue manager can move + them to the <b>corrupt</b> queue afterwards. + + Depending on the setting of the <b><a href="postconf.5.html#notify_classes">notify_classes</a></b> parameter, the postmas- + ter is notified of bounces and of other trouble. + +<b>BUGS</b> + This delivery agent supports address extensions in email addresses and + in lookup table keys, but does not propagate address extension informa- + tion to the result of table lookup. + + Postfix should have lookup tables that can return multiple result + attributes. In order to avoid the inconvenience of maintaining three + tables, use an LDAP or MYSQL database. + +<b>CONFIGURATION PARAMETERS</b> + Changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked up automatically, as <a href="virtual.8.html"><b>virtual</b>(8)</a> processes + run for only a limited amount of time. Use the command "<b>postfix reload</b>" + to speed up a change. + + The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for + more details including examples. + +<b>MAILBOX DELIVERY CONTROLS</b> + <b><a href="postconf.5.html#virtual_mailbox_base">virtual_mailbox_base</a> (empty)</b> + A prefix that the <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent prepends to all + pathname results from $<a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a> table lookups. + + <b><a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a> (empty)</b> + Optional lookup tables with all valid addresses in the domains + that match $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>. + + <b><a href="postconf.5.html#virtual_minimum_uid">virtual_minimum_uid</a> (100)</b> + The minimum user ID value that the <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent + accepts as a result from $<a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a> table lookup. + + <b><a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a> (empty)</b> + Lookup tables with the per-recipient user ID that the <a href="virtual.8.html"><b>virtual</b>(8)</a> + delivery agent uses while writing to the recipient's mailbox. + + <b><a href="postconf.5.html#virtual_gid_maps">virtual_gid_maps</a> (empty)</b> + Lookup tables with the per-recipient group ID for <a href="virtual.8.html"><b>virtual</b>(8)</a> + mailbox delivery. + + Available in Postfix version 2.0 and later: + + <b><a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a> ($<a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a>)</b> + Postfix is final destination for the specified list of domains; + mail is delivered via the $<a href="postconf.5.html#virtual_transport">virtual_transport</a> mail delivery + transport. + + <b><a href="postconf.5.html#virtual_transport">virtual_transport</a> (virtual)</b> + The default mail delivery transport and next-hop destination for + final delivery to domains listed with $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>. + + Available in Postfix version 2.5.3 and later: + + <b><a href="postconf.5.html#strict_mailbox_ownership">strict_mailbox_ownership</a> (yes)</b> + Defer delivery when a mailbox file is not owned by its recipi- + ent. + +<b>LOCKING CONTROLS</b> + <b><a href="postconf.5.html#virtual_mailbox_lock">virtual_mailbox_lock</a> (see 'postconf -d' output)</b> + How to lock a UNIX-style <a href="virtual.8.html"><b>virtual</b>(8)</a> mailbox before attempting + delivery. + + <b><a href="postconf.5.html#deliver_lock_attempts">deliver_lock_attempts</a> (20)</b> + The maximal number of attempts to acquire an exclusive lock on a + mailbox file or <a href="bounce.8.html"><b>bounce</b>(8)</a> logfile. + + <b><a href="postconf.5.html#deliver_lock_delay">deliver_lock_delay</a> (1s)</b> + The time between attempts to acquire an exclusive lock on a + mailbox file or <a href="bounce.8.html"><b>bounce</b>(8)</a> logfile. + + <b><a href="postconf.5.html#stale_lock_time">stale_lock_time</a> (500s)</b> + The time after which a stale exclusive mailbox lockfile is + removed. + +<b>RESOURCE AND RATE CONTROLS</b> + <b><a href="postconf.5.html#virtual_mailbox_limit">virtual_mailbox_limit</a> (51200000)</b> + The maximal size in bytes of an individual <a href="virtual.8.html"><b>virtual</b>(8)</a> mailbox or + maildir file, or zero (no limit). + + Implemented in the <a href="qmgr.8.html">qmgr(8)</a> daemon: + + <b><a href="postconf.5.html#virtual_destination_concurrency_limit">virtual_destination_concurrency_limit</a> ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concur</a>-</b> + <b><a href="postconf.5.html#default_destination_concurrency_limit">rency_limit</a>)</b> + The maximal number of parallel deliveries to the same destina- + tion via the virtual message delivery transport. + + <b><a href="postconf.5.html#virtual_destination_recipient_limit">virtual_destination_recipient_limit</a> ($<a href="postconf.5.html#default_destination_recipient_limit">default_destination_recipi</a>-</b> + <b><a href="postconf.5.html#default_destination_recipient_limit">ent_limit</a>)</b> + The maximal number of recipients per message for the virtual + message delivery transport. + +<b>MISCELLANEOUS CONTROLS</b> + <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> + The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- + figuration files. + + <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b> + How much time a Postfix daemon process may take to handle a + request before it is terminated by a built-in watchdog timer. + + <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b> + The maximal number of digits after the decimal point when log- + ging sub-second delay values. + + <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b> + The time limit for sending or receiving information over an + internal communication channel. + + <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b> + The maximum amount of time that an idle Postfix daemon process + waits for an incoming connection before terminating voluntarily. + + <b><a href="postconf.5.html#max_use">max_use</a> (100)</b> + The maximal number of incoming connections that a Postfix daemon + process will service before terminating voluntarily. + + <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> + The process ID of a Postfix command or daemon process. + + <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> + The process name of a Postfix command or daemon process. + + <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b> + The location of the Postfix top-level queue directory. + + <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> + The syslog facility of Postfix logging. + + <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> + A prefix that is prepended to the process name in syslog + records, so that, for example, "smtpd" becomes "prefix/smtpd". + + Available in Postfix version 3.0 and later: + + <b><a href="postconf.5.html#virtual_delivery_status_filter">virtual_delivery_status_filter</a> ($<a href="postconf.5.html#default_delivery_status_filter">default_delivery_status_filter</a>)</b> + Optional filter for the <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent to change the + delivery status code or explanatory text of successful or unsuc- + cessful deliveries. + + Available in Postfix version 3.3 and later: + + <b><a href="postconf.5.html#enable_original_recipient">enable_original_recipient</a> (yes)</b> + Enable support for the original recipient address after an + address is rewritten to a different address (for example with + aliasing or with canonical mapping). + + <b><a href="postconf.5.html#service_name">service_name</a> (read-only)</b> + The <a href="master.5.html">master.cf</a> service name of a Postfix daemon process. + + Available in Postfix 3.5 and later: + + <b>info_log_address_format (external)</b> + The email address form that will be used in non-debug logging + (info, warning, etc.). + +<b>SEE ALSO</b> + <a href="qmgr.8.html">qmgr(8)</a>, queue manager + <a href="bounce.8.html">bounce(8)</a>, delivery status reports + <a href="postconf.5.html">postconf(5)</a>, configuration parameters + <a href="postlogd.8.html">postlogd(8)</a>, Postfix logging + syslogd(8), system logging + +<b>README_FILES</b> + Use "<b>postconf <a href="postconf.5.html#readme_directory">readme_directory</a></b>" or + "<b>postconf <a href="postconf.5.html#html_directory">html_directory</a></b>" to locate this information. + <a href="VIRTUAL_README.html">VIRTUAL_README</a>, domain hosting howto + +<b>LICENSE</b> + The Secure Mailer license must be distributed with this software. + +<b>HISTORY</b> + This delivery agent was originally based on the Postfix local delivery + agent. Modifications mainly consisted of removing code that either was + not applicable or that was not safe in this context: aliases, + ~user/.forward files, delivery to "|command" or to /file/name. + + The <b>Delivered-To:</b> message header appears in the <b>qmail</b> system by Daniel + Bernstein. + + The <b>maildir</b> structure appears in the <b>qmail</b> system by Daniel Bernstein. + +<b>AUTHOR(S)</b> + Wietse Venema + IBM T.J. Watson Research + P.O. Box 704 + Yorktown Heights, NY 10598, USA + + Wietse Venema + Google, Inc. + 111 8th Avenue + New York, NY 10011, USA + + Andrew McNamara + andrewm@connect.com.au + connect.com.au Pty. Ltd. + Level 3, 213 Miller St + North Sydney 2060, NSW, Australia + + VIRTUAL(8) +</pre> </body> </html> |