summaryrefslogtreecommitdiffstats
path: root/html/virtual.8.html
diff options
context:
space:
mode:
Diffstat (limited to 'html/virtual.8.html')
-rw-r--r--html/virtual.8.html326
1 files changed, 326 insertions, 0 deletions
diff --git a/html/virtual.8.html b/html/virtual.8.html
new file mode 100644
index 0000000..3373eb3
--- /dev/null
+++ b/html/virtual.8.html
@@ -0,0 +1,326 @@
+<!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 &gt; 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.
+
+<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>