    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)