    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 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  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  envelope  recipient  address  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 (regexp maps disallowed)
                  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.

           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 (regexp maps disallowed)
                  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.

           virtual_gid_maps (regexp maps disallowed)
                  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.

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