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_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)