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 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. MAILBOX LOCATION The mailbox location is controlled by the virtual_mail- box_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: $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 recip- ient address as given to Postfix, 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 problems, an attempt is made to truncate the mailbox to its original length. QMAIL MAILDIR FORMAT When the mailbox location ends in /, the message is deliv- ered in qmail maildir format. This format stores one mes- sage per file. The virtual delivery agent daemon prepends a Delivered-To: message header with the final envelope recipient address, prepends an X-Original-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 lock- ing during mail delivery or retrieval. MAILBOX OWNERSHIP 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 vir- tual_uid_maps. SECURITY The virtual delivery agent is not security sensitive, pro- vided 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). Cor- rupted 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 trou- ble. 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 program. 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 control map in virtual_mail- box_maps doesn't litter the filesystem with mail- boxes. 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 exten- sion (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 specific 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 secu- rity 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 mydestination configuration parameter. virtual_minimum_uid Specifies a minimum uid that will be accepted as a return from a virtual_owner_maps or vir- tual_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 exten- sion (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 specific 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 secu- rity 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 exten- sion (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 specific 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 secu- rity 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 deliv- ery, because such deliveries are safe without explicit locks. Use the command postconf -l to find out what lock- ing methods are available on your system. deliver_lock_attempts Limit the number of attempts to acquire an exclu- sive 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 mail- box file. The actual delay is slightly randomized. stale_lock_time Limit the time after which a stale lockfile is removed (applicable 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_concur- rency_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 virtual delivery agent. The default limit is taken from the default_destination_recipi- ent_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/.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. 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)