summaryrefslogtreecommitdiffstats
path: root/man/man8/virtual.8
diff options
context:
space:
mode:
Diffstat (limited to 'man/man8/virtual.8')
-rw-r--r--man/man8/virtual.8358
1 files changed, 358 insertions, 0 deletions
diff --git a/man/man8/virtual.8 b/man/man8/virtual.8
new file mode 100644
index 0000000..3a3525a
--- /dev/null
+++ b/man/man8/virtual.8
@@ -0,0 +1,358 @@
+.TH VIRTUAL 8
+.ad
+.fi
+.SH NAME
+virtual
+\-
+Postfix virtual domain mail delivery agent
+.SH "SYNOPSIS"
+.na
+.nf
+\fBvirtual\fR [generic Postfix daemon options]
+.SH DESCRIPTION
+.ad
+.fi
+The \fBvirtual\fR(8) delivery agent is designed for virtual mail
+hosting services. Originally based on the Postfix \fBlocal\fR(8)
+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.
+.SH "MAILBOX LOCATION"
+.na
+.nf
+.ad
+.fi
+The mailbox location is controlled by the \fBvirtual_mailbox_base\fR
+and \fBvirtual_mailbox_maps\fR configuration parameters (see below).
+The \fBvirtual_mailbox_maps\fR table is indexed by the recipient
+address as described under TABLE SEARCH ORDER below.
+
+The mailbox pathname is constructed as follows:
+
+.nf
+ \fB$virtual_mailbox_base/$virtual_mailbox_maps(\fIrecipient\fB)\fR
+.fi
+
+where \fIrecipient\fR is the full recipient address.
+.SH "UNIX MAILBOX FORMAT"
+.na
+.nf
+.ad
+.fi
+When the mailbox location does not end in \fB/\fR, the message
+is delivered in UNIX mailbox format. This format stores multiple
+messages in one textfile.
+
+The \fBvirtual\fR(8) delivery agent prepends a "\fBFrom \fIsender
+time_stamp\fR" envelope header to each message, prepends a
+\fBDelivered\-To:\fR message header with the envelope recipient
+address,
+prepends an \fBX\-Original\-To:\fR header with the recipient address as
+given to Postfix,
+prepends a \fBReturn\-Path:\fR message header with the
+envelope sender address, prepends a \fB>\fR character to lines
+beginning with "\fBFrom \fR", 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
+mailbox to its original length.
+.SH "QMAIL MAILDIR FORMAT"
+.na
+.nf
+.ad
+.fi
+When the mailbox location ends in \fB/\fR, the message is delivered
+in qmail \fBmaildir\fR format. This format stores one message per file.
+
+The \fBvirtual\fR(8) delivery agent prepends a \fBDelivered\-To:\fR
+message header with the final envelope recipient address,
+prepends an \fBX\-Original\-To:\fR header with the recipient address as
+given to Postfix, and prepends a
+\fBReturn\-Path:\fR message header with the envelope sender address.
+
+By definition, \fBmaildir\fR format does not require application\-level
+file locking during mail delivery or retrieval.
+.SH "MAILBOX OWNERSHIP"
+.na
+.nf
+.ad
+.fi
+Mailbox ownership is controlled by the \fBvirtual_uid_maps\fR
+and \fBvirtual_gid_maps\fR lookup tables, which are indexed
+with the full recipient address. Each table provides
+a string with the numerical user and group ID, respectively.
+
+The \fBvirtual_minimum_uid\fR parameter imposes a lower bound on
+numerical user ID values that may be specified in any
+\fBvirtual_uid_maps\fR.
+.SH "CASE FOLDING"
+.na
+.nf
+.ad
+.fi
+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.
+.SH "TABLE SEARCH ORDER"
+.na
+.nf
+.ad
+.fi
+Normally, a lookup table is specified as a text file that
+serves as input to the \fBpostmap\fR(1) command. The result, an
+indexed file in \fBdbm\fR or \fBdb\fR format, is used for fast
+searching by the mail system.
+
+The search order is as follows. The search stops
+upon the first successful lookup.
+.IP \(bu
+When the recipient has an optional address extension the
+\fIuser+extension@domain.tld\fR address is looked up first.
+.sp
+With Postfix versions before 2.1, the optional address extension
+is always ignored.
+.IP \(bu
+The \fIuser@domain.tld\fR address, without address extension,
+is looked up next.
+.IP \(bu
+Finally, the recipient \fI@domain\fR is looked up.
+.PP
+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.
+.SH "SECURITY"
+.na
+.nf
+.ad
+.fi
+The \fBvirtual\fR(8) delivery agent is not security sensitive, provided
+that the lookup tables with recipient user/group ID information are
+adequately protected. This program is not designed to run chrooted.
+
+The \fBvirtual\fR(8) delivery agent disallows regular expression
+substitution of $1 etc. in regular expression lookup tables,
+because that would open a security hole.
+
+The \fBvirtual\fR(8) delivery agent will silently ignore requests
+to use the \fBproxymap\fR(8) server. Instead it will open the
+table directly. Before Postfix version 2.2, the virtual
+delivery agent will terminate with a fatal error.
+.SH "STANDARDS"
+.na
+.nf
+RFC 822 (ARPA Internet Text Messages)
+.SH DIAGNOSTICS
+.ad
+.fi
+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 \fBsyslogd\fR(8)
+or \fBpostlogd\fR(8).
+Corrupted message files are marked so that the queue
+manager can move them to the \fBcorrupt\fR queue afterwards.
+
+Depending on the setting of the \fBnotify_classes\fR parameter,
+the postmaster is notified of bounces and of other trouble.
+.SH BUGS
+.ad
+.fi
+This delivery agent supports address extensions in email
+addresses and in lookup table keys, but does not propagate
+address extension information 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.
+.SH "CONFIGURATION PARAMETERS"
+.na
+.nf
+.ad
+.fi
+Changes to \fBmain.cf\fR are picked up automatically, as
+\fBvirtual\fR(8)
+processes run for only a limited amount of time. Use the command
+"\fBpostfix reload\fR" to speed up a change.
+
+The text below provides only a parameter summary. See
+\fBpostconf\fR(5) for more details including examples.
+.SH "MAILBOX DELIVERY CONTROLS"
+.na
+.nf
+.ad
+.fi
+.IP "\fBvirtual_mailbox_base (empty)\fR"
+A prefix that the \fBvirtual\fR(8) delivery agent prepends to all pathname
+results from $virtual_mailbox_maps table lookups.
+.IP "\fBvirtual_mailbox_maps (empty)\fR"
+Optional lookup tables with all valid addresses in the domains that
+match $virtual_mailbox_domains.
+.IP "\fBvirtual_minimum_uid (100)\fR"
+The minimum user ID value that the \fBvirtual\fR(8) delivery agent accepts
+as a result from $virtual_uid_maps table lookup.
+.IP "\fBvirtual_uid_maps (empty)\fR"
+Lookup tables with the per\-recipient user ID that the \fBvirtual\fR(8)
+delivery agent uses while writing to the recipient's mailbox.
+.IP "\fBvirtual_gid_maps (empty)\fR"
+Lookup tables with the per\-recipient group ID for \fBvirtual\fR(8) mailbox
+delivery.
+.PP
+Available in Postfix version 2.0 and later:
+.IP "\fBvirtual_mailbox_domains ($virtual_mailbox_maps)\fR"
+Postfix is final destination for the specified list of domains;
+mail is delivered via the $virtual_transport mail delivery transport.
+.IP "\fBvirtual_transport (virtual)\fR"
+The default mail delivery transport and next\-hop destination for
+final delivery to domains listed with $virtual_mailbox_domains.
+.PP
+Available in Postfix version 2.5.3 and later:
+.IP "\fBstrict_mailbox_ownership (yes)\fR"
+Defer delivery when a mailbox file is not owned by its recipient.
+.SH "LOCKING CONTROLS"
+.na
+.nf
+.ad
+.fi
+.IP "\fBvirtual_mailbox_lock (see 'postconf -d' output)\fR"
+How to lock a UNIX\-style \fBvirtual\fR(8) mailbox before attempting
+delivery.
+.IP "\fBdeliver_lock_attempts (20)\fR"
+The maximal number of attempts to acquire an exclusive lock on a
+mailbox file or \fBbounce\fR(8) logfile.
+.IP "\fBdeliver_lock_delay (1s)\fR"
+The time between attempts to acquire an exclusive lock on a mailbox
+file or \fBbounce\fR(8) logfile.
+.IP "\fBstale_lock_time (500s)\fR"
+The time after which a stale exclusive mailbox lockfile is removed.
+.SH "RESOURCE AND RATE CONTROLS"
+.na
+.nf
+.ad
+.fi
+.IP "\fBvirtual_mailbox_limit (51200000)\fR"
+The maximal size in bytes of an individual \fBvirtual\fR(8) mailbox or
+maildir file, or zero (no limit).
+.PP
+Implemented in the qmgr(8) daemon:
+.IP "\fBvirtual_destination_concurrency_limit ($default_destination_concurrency_limit)\fR"
+The maximal number of parallel deliveries to the same destination
+via the virtual message delivery transport.
+.IP "\fBvirtual_destination_recipient_limit ($default_destination_recipient_limit)\fR"
+The maximal number of recipients per message for the virtual
+message delivery transport.
+.SH "MISCELLANEOUS CONTROLS"
+.na
+.nf
+.ad
+.fi
+.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
+The default location of the Postfix main.cf and master.cf
+configuration files.
+.IP "\fBdaemon_timeout (18000s)\fR"
+How much time a Postfix daemon process may take to handle a
+request before it is terminated by a built\-in watchdog timer.
+.IP "\fBdelay_logging_resolution_limit (2)\fR"
+The maximal number of digits after the decimal point when logging
+sub\-second delay values.
+.IP "\fBipc_timeout (3600s)\fR"
+The time limit for sending or receiving information over an internal
+communication channel.
+.IP "\fBmax_idle (100s)\fR"
+The maximum amount of time that an idle Postfix daemon process waits
+for an incoming connection before terminating voluntarily.
+.IP "\fBmax_use (100)\fR"
+The maximal number of incoming connections that a Postfix daemon
+process will service before terminating voluntarily.
+.IP "\fBprocess_id (read\-only)\fR"
+The process ID of a Postfix command or daemon process.
+.IP "\fBprocess_name (read\-only)\fR"
+The process name of a Postfix command or daemon process.
+.IP "\fBqueue_directory (see 'postconf -d' output)\fR"
+The location of the Postfix top\-level queue directory.
+.IP "\fBsyslog_facility (mail)\fR"
+The syslog facility of Postfix logging.
+.IP "\fBsyslog_name (see 'postconf -d' output)\fR"
+A prefix that is prepended to the process name in syslog
+records, so that, for example, "smtpd" becomes "prefix/smtpd".
+.PP
+Available in Postfix version 3.0 and later:
+.IP "\fBvirtual_delivery_status_filter ($default_delivery_status_filter)\fR"
+Optional filter for the \fBvirtual\fR(8) delivery agent to change the
+delivery status code or explanatory text of successful or unsuccessful
+deliveries.
+.PP
+Available in Postfix version 3.3 and later:
+.IP "\fBenable_original_recipient (yes)\fR"
+Enable support for the original recipient address after an
+address is rewritten to a different address (for example with
+aliasing or with canonical mapping).
+.IP "\fBservice_name (read\-only)\fR"
+The master.cf service name of a Postfix daemon process.
+.PP
+Available in Postfix 3.5 and later:
+.IP "\fBinfo_log_address_format (external)\fR"
+The email address form that will be used in non\-debug logging
+(info, warning, etc.).
+.SH "SEE ALSO"
+.na
+.nf
+qmgr(8), queue manager
+bounce(8), delivery status reports
+postconf(5), configuration parameters
+postlogd(8), Postfix logging
+syslogd(8), system logging
+.SH "README_FILES"
+.na
+.nf
+Use "\fBpostconf readme_directory\fR" or
+"\fBpostconf html_directory\fR" to locate this information.
+VIRTUAL_README, domain hosting howto
+.SH "LICENSE"
+.na
+.nf
+.ad
+.fi
+The Secure Mailer license must be distributed with this software.
+.SH HISTORY
+.ad
+.fi
+.ad
+.fi
+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 \fBDelivered\-To:\fR message header appears in the \fBqmail\fR
+system by Daniel Bernstein.
+
+The \fBmaildir\fR structure appears in the \fBqmail\fR system
+by Daniel Bernstein.
+.SH "AUTHOR(S)"
+.na
+.nf
+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