    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 recipient address  as  described  under  TABLE  SEARCH
           ORDER below.

           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  applica-
           tion-level file locking 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.

    TABLE SEARCH ORDER
           Normally,  a lookup table is specified as a text file that
           serves as input to the postmap(1) command. The result,  an
           indexed file in dbm or db format, is used for fast search-
           ing by the mail system.

           The canonical search order is as follows. The search stops
           upon the first successful lookup.

           o      When  the  recipient has an optional address exten-
                  sion  the  user+extension@domain.tld   address   is
                  looked up first.

           o      The user@domain.tld address, without address exten-
                  sion, is looked up next.

           o      Finally, the recipient @domain is looked up.

           When the table is provided via other means  such  as  NIS,
           LDAP  or  SQL,  the  same lookups are done as for ordinary
           indexed files.

           Alternatively, a table  can  be  provided  as  a  regular-
           expression map where patterns are given as regular expres-
           sions. In that case, only the full  recipient  address  is
           given to the regular-expression map.

    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 supports address extensions in email
           addresses and in lookup table keys, but does not propagate
           address  extension  information  to  the  result  of table
           lookup.

           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)