    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)