virtual - Postfix virtual domain mail delivery agent
virtual [generic Postfix daemon options]
The virtual 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 maps or via similar lookup
The mailbox location is controlled by the virtual_mailbox_base and virtual_mailbox_maps
configuration parameters (see below). The virtual_mailbox_maps table is indexed by the
full recipient address.
The mailbox pathname is constructed as follows:
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 for-
mat. 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 a Return-Path: message 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 prob-
lems, an attempt is made to truncate the mailbox 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 enve-
lope recipient address and prepends a Return-Path: message header with the envelope sender
By definition, maildir format does not require file locking during mail delivery or
Mailbox ownership is controlled by the virtual_uid_maps and virtual_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_owner_maps or virtual_uid_maps.
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.
RFC 822 (ARPA Internet Text Messages)
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 postmaster is notified of
bounces and of other trouble.
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.
The following main.cf parameters are especially relevant to this program. See the Postfix
main.cf file for syntax details and for default values. Use the postfix reload command
after a configuration change.
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 virtual_mailbox_maps doesn't
litter the filesystem with mailboxes. While it could be set to "/", this setting
virtual_mailbox_maps (regexp maps disallowed)
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 car-
ried out, otherwise the path is assumed to specify a UNIX-style mailbox file.
Note that virtual_mailbox_base is unconditionally prepended to this path.
Specifies a minimum uid that will be accepted as a return from a virtual_owner_maps
or virtual_uid_maps lookup. Returned values less than this will be rejected, and
the message will be deferred.
virtual_uid_maps (regexp maps disallowed)
Recipients are looked up in these maps to determine the user ID to be used when
writing to the target mailbox.
virtual_gid_maps (regexp maps disallowed)
Recipients are looked up in these maps to determine the group ID to be used when
writing to the target mailbox.
How to lock UNIX-style mailboxes: one or more of flock, fcntl or dotlock. The dot-
lock 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
Limit the number of attempts to acquire an exclusive lock on a UNIX-style mailbox
Time (default: seconds) between successive attempts to acquire an exclusive lock on
a UNIX-style mailbox file. The actual delay is slightly randomized.
Limit the time after which a stale lockfile is removed (applicable to UNIX-style
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.
Limit the number of recipients per message delivery via the virtual delivery agent.
The default limit is taken from the default_destination_recipient_limit parameter.
The limit is enforced by the Postfix queue manager.
The maximal size in bytes of a mailbox or maildir file. Set to zero to disable the
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 Delivered-To: header appears in the qmail system by Daniel Bernstein.
The maildir structure appears in the qmail system by Daniel Bernstein.
bounce(8) non-delivery status reports
syslogd(8) system logging
qmgr(8) queue manager
The Secure Mailer license must be distributed with this software.
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
connect.com.au Pty. Ltd.
Level 3, 213 Miller St
North Sydney 2060, NSW, Australia