VIRTUAL(8) VIRTUAL(8)
NAME
virtual - Postfix virtual domain mail delivery agent
SYNOPSIS
virtual [generic Postfix daemon options]
DESCRIPTION
The virtual delivery agent is designed for virtual mail hosting ser-
vices. 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.
MAILBOX LOCATION
The mailbox location is controlled by the virtual_mailbox_base and vir-
tual_mailbox_maps configuration parameters (see below). The vir-
tual_mailbox_maps table is indexed by the full recipient address.
The mailbox pathname is constructed as follows:
$virtual_mailbox_base/$virtual_mailbox_maps(recipient)
where recipient is the full recipient address.
UNIX MAILBOX FORMAT
When the mailbox location does not end in /, the message is delivered
in UNIX mailbox format. This format stores multiple messages in one
textfile.
The virtual delivery agent prepends a "From sender time_stamp" envelope
header to each message, prepends a Delivered-To: message header with
the envelope recipient address, prepends an X-Original-To: header with
the recipient address as given to Postfix, prepends a Return-Path: mes-
sage header with the envelope sender address, prepends a > character to
lines beginning with "From ", 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.
QMAIL MAILDIR FORMAT
When the mailbox location ends in /, the message is delivered in qmail
maildir format. This format stores one message per file.
The virtual delivery agent daemon prepends a Delivered-To: message
header with the final envelope recipient address, prepends an X-Origi-
nal-To: header with the recipient address as given to Postfix, and
prepends a Return-Path: message header with the envelope sender
address.
By definition, maildir format does not require file locking during mail
delivery or retrieval.
MAILBOX OWNERSHIP
Mailbox ownership is controlled by the virtual_uid_maps and vir-
tual_gid_maps lookup tables, which are indexed with the full recipient
address. Each table provides a string with the numerical user and group
ID, respectively.
The virtual_minimum_uid parameter imposes a lower bound on numerical
user ID values that may be specified in any virtual_uid_maps.
SECURITY
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.
STANDARDS
RFC 822 (ARPA Internet Text Messages)
DIAGNOSTICS
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 syslogd(8). Corrupted message
files are marked so that the queue manager can move them to the corrupt
queue afterwards.
Depending on the setting of the notify_classes parameter, the postmas-
ter is notified of bounces and of other trouble.
BUGS
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.
CONFIGURATION PARAMETERS
The following main.cf parameters are especially relevant to this pro-
gram. See the Postfix main.cf file for syntax details and for default
values. Use the postfix reload command after a configuration change.
Mailbox delivery
virtual_mailbox_base
Specifies a path that is prepended to all mailbox or maildir
paths. This is a safety measure to ensure that an out of con-
trol map in virtual_mailbox_maps doesn't litter the filesystem
with mailboxes. While it could be set to "/", this setting
isn't recommended.
virtual_mailbox_maps
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
(user+foo@domain.tld) is ignored.
In a lookup table, specify a left-hand side of @domain.tld to
match any user in the specified domain that does not have a spe-
cific user@domain.tld entry.
Note that virtual_mailbox_base 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.
virtual_mailbox_domains
The list of domains that should be delivered via the Postfix
virtual delivery agent. This uses the same syntax as the mydes-
tination configuration parameter.
virtual_minimum_uid
Specifies a minimum uid that will be accepted as a return from a
virtual_uid_maps lookup. Returned values less than this will be
rejected, and the message will be deferred.
virtual_uid_maps
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
(user+foo@domain.tld) is ignored.
In a lookup table, specify a left-hand side of @domain.tld to
match any user in the specified domain that does not have a spe-
cific user@domain.tld 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.
virtual_gid_maps
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
(user+foo@domain.tld) is ignored.
In a lookup table, specify a left-hand side of @domain.tld to
match any user in the specified domain that does not have a spe-
cific user@domain.tld 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.
Locking controls
virtual_mailbox_lock
How to lock UNIX-style mailboxes: one or more of flock, fcntl or
dotlock. The dotlock method requires that the recipient UID or
GID has write access to the parent directory of the mailbox
file.
This setting is ignored with maildir style delivery, because
such deliveries are safe without explicit locks.
Use the command postconf -l to find out what locking methods are
available on your system.
deliver_lock_attempts
Limit the number of attempts to acquire an exclusive lock on a
UNIX-style mailbox file.
deliver_lock_delay
Time (default: seconds) between successive attempts to acquire
an exclusive lock on a UNIX-style mailbox file. The actual delay
is slightly randomized.
stale_lock_time
Limit the time after which a stale lockfile is removed (applica-
ble to UNIX-style mailboxes only).
Resource controls
virtual_destination_concurrency_limit
Limit the number of parallel deliveries to the same domain via
the virtual delivery agent. The default limit is taken from the
default_destination_concurrency_limit parameter. The limit is
enforced by the Postfix queue manager.
virtual_destination_recipient_limit
Limit the number of recipients per message delivery via the vir-
tual delivery agent. The default limit is taken from the
default_destination_recipient_limit parameter. The limit is
enforced by the Postfix queue manager.
virtual_mailbox_limit
The maximal size in bytes of a mailbox or maildir file. Set to
zero to disable the limit.
HISTORY
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/.for-
ward files, delivery to "|command" or to /file/name.
The Delivered-To: header appears in the qmail system by Daniel Bern-
stein.
The maildir structure appears in the qmail system by Daniel Bernstein.
SEE ALSO
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
LICENSE
The Secure Mailer license must be distributed with this software.
AUTHOR(S)
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
VIRTUAL(8)