.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 delivery agent is designed for virtual mail
hosting services. Originally based on the Postfix local 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 full recipient
address.
The mailbox pathname is constructed as follows:
.ti +2
\fB$virtual_mailbox_base/$virtual_mailbox_maps(\fIrecipient\fB)\fR
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 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 delivery agent daemon 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 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 SECURITY
.na
.nf
.ad
.fi
The virtual 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.
.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).
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 silently ignores address extensions.
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
The following \fBmain.cf\fR parameters are especially relevant to
this program. See the Postfix \fBmain.cf\fR file for syntax details
and for default values. Use the \fBpostfix reload\fR command after
a configuration change.
.SH Mailbox delivery
.ad
.fi
.IP \fBvirtual_mailbox_base\fR
Specifies a path that is prepended to all mailbox or maildir paths.
This is a safety measure to ensure that an out of control map in
\fBvirtual_mailbox_maps\fR doesn't litter the filesystem with mailboxes.
While it could be set to "/", this setting isn't recommended.
.IP \fBvirtual_mailbox_maps\fR
Recipients are looked up in these maps to determine the path to
their mailbox or maildir. If the returned path ends in a slash
("/"), maildir-style delivery is carried out, otherwise the
path is assumed to specify a UNIX-style mailbox file.
While searching a lookup table, an address extension
(\fIuser+foo@domain.tld\fR) is ignored.
In a lookup table, specify a left-hand side of \fI@domain.tld\fR
to match any user in the specified domain that does not have a
specific \fIuser@domain.tld\fR entry.
Note that \fBvirtual_mailbox_base\fR is unconditionally prepended
to this path.
For security reasons, regular expression maps are allowed but
regular expression substitution of $1 etc. is disallowed,
because that would open a security hole.
For security reasons, proxied table lookup is not allowed,
because that would open a security hole.
.IP \fBvirtual_mailbox_domains\fR
The list of domains that should be delivered via the Postfix virtual
delivery agent. This uses the same syntax as the \fBmydestination\fR
configuration parameter.
.IP \fBvirtual_minimum_uid\fR
Specifies a minimum uid that will be accepted as a return from
a \fBvirtual_owner_maps\fR or \fBvirtual_uid_maps\fR lookup.
Returned values less than this will be rejected, and the message
will be deferred.
.IP \fBvirtual_uid_maps\fR
Recipients are looked up in these maps to determine the user ID to be
used when writing to the target mailbox.
While searching a lookup table, an address extension
(\fIuser+foo@domain.tld\fR) is ignored.
In a lookup table, specify a left-hand side of \fI@domain.tld\fR
to match any user in the specified domain that does not have a
specific \fIuser@domain.tld\fR entry.
For security reasons, regular expression maps are allowed but
regular expression substitution of $1 etc. is disallowed,
because that would open a security hole.
For security reasons, proxied table lookup is not allowed,
because that would open a security hole.
.IP \fBvirtual_gid_maps\fR
Recipients are looked up in these maps to determine the group ID to be
used when writing to the target mailbox.
While searching a lookup table, an address extension
(\fIuser+foo@domain.tld\fR) is ignored.
In a lookup table, specify a left-hand side of \fI@domain.tld\fR
to match any user in the specified domain that does not have a
specific \fIuser@domain.tld\fR entry.
For security reasons, regular expression maps are allowed but
regular expression substitution of $1 etc. is disallowed,
because that would open a security hole.
For security reasons, proxied table lookup is not allowed,
because that would open a security hole.
.SH "Locking controls"
.ad
.fi
.IP \fBvirtual_mailbox_lock\fR
How to lock UNIX-style mailboxes: one or more of \fBflock\fR,
\fBfcntl\fR or \fBdotlock\fR. The \fBdotlock\fR method requires
that the recipient UID or GID has write access to the parent
directory of the mailbox file.
This setting is ignored with \fBmaildir\fR style delivery,
because such deliveries are safe without explicit locks.
Use the command \fBpostconf -l\fR to find out what locking methods
are available on your system.
.IP \fBdeliver_lock_attempts\fR
Limit the number of attempts to acquire an exclusive lock
on a UNIX-style mailbox file.
.IP \fBdeliver_lock_delay\fR
Time (default: seconds) between successive attempts to acquire
an exclusive lock on a UNIX-style mailbox file. The actual delay
is slightly randomized.
.IP \fBstale_lock_time\fR
Limit the time after which a stale lockfile is removed (applicable
to UNIX-style mailboxes only).
.SH "Resource controls"
.ad
.fi
.IP \fBvirtual_destination_concurrency_limit\fR
Limit the number of parallel deliveries to the same domain
via the \fBvirtual\fR delivery agent.
The default limit is taken from the
\fBdefault_destination_concurrency_limit\fR parameter.
The limit is enforced by the Postfix queue manager.
.IP \fBvirtual_destination_recipient_limit\fR
Limit the number of recipients per message delivery
via the \fBvirtual\fR delivery agent.
The default limit is taken from the
\fBdefault_destination_recipient_limit\fR parameter.
The limit is enforced by the Postfix queue manager.
.IP \fBvirtual_mailbox_limit\fR
The maximal size in bytes of a mailbox or maildir file.
Set to zero to disable the limit.
.SH HISTORY
.na
.nf
.ad
.fi
This 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 header appears in the \fBqmail\fR system
by Daniel Bernstein.
The \fBmaildir\fR structure appears in the \fBqmail\fR system
by Daniel Bernstein.
.SH SEE ALSO
.na
.nf
regexp_table(5) POSIX regular expression table format
pcre_table(5) Perl Compatible Regular Expression table format
bounce(8) non-delivery status reports
syslogd(8) system logging
qmgr(8) queue manager
.SH LICENSE
.na
.nf
.ad
.fi
The Secure Mailer license must be distributed with this software.
.SH AUTHOR(S)
.na
.nf
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Andrew McNamara
andrewm@connect.com.au
connect.com.au Pty. Ltd.
Level 3, 213 Miller St
North Sydney 2060, NSW, Australia