unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-2.0)
Page:
Section:
Apropos / Subsearch:
optional field

VIRTUAL(8)                  System Manager's Manual                 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 ser-
       vices. 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_mailbox_base and vir-
       tual_mailbox_maps  configuration  parameters  (see  below).   The  vir-
       tual_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 recipient address as given to Postfix, prepends a Return-Path: mes-
       sage 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 mail-
       box to its original length.

QMAIL MAILDIR FORMAT
       When the mailbox location ends in /, the message is delivered in  qmail
       maildir format. This format stores one message per file.

       The  virtual  delivery  agent  daemon  prepends a Delivered-To: message
       header with the final envelope recipient address, prepends an  X-Origi-
       nal-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 locking during mail
       delivery or retrieval.

MAILBOX OWNERSHIP
       Mailbox ownership  is  controlled  by  the  virtual_uid_maps  and  vir-
       tual_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 virtual_uid_maps.

SECURITY
       The virtual delivery agent is not security sensitive, provided 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).  Corrupted  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  postmas-
       ter is notified of bounces and of other trouble.

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 pro-
       gram. 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  con-
              trol  map  in virtual_mailbox_maps doesn't litter the filesystem
              with mailboxes.  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   extension
              (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 spe-
              cific 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 security 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  mydes-
              tination 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   extension
              (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 spe-
              cific 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 security 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  extension
              (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 spe-
              cific 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 security 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  delivery,  because
              such deliveries are safe without explicit locks.

              Use the command postconf -l to find out what locking methods are
              available on your system.

       deliver_lock_attempts
              Limit the number of attempts to acquire an exclusive 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 mailbox file. The actual delay
              is slightly randomized.

       stale_lock_time
              Limit the time after which a stale lockfile is removed (applica-
              ble 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_concurrency_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 vir-
              tual delivery agent.   The  default  limit  is  taken  from  the
              default_destination_recipient_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/.for-
       ward files, delivery to "|command" or to /file/name.

       The Delivered-To: header appears in the qmail system  by  Daniel  Bern-
       stein.

       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
       andrewmATconnect.au
       connect.com.au Pty. Ltd.
       Level 3, 213 Miller St
       North Sydney 2060, NSW, Australia



                                                                    VIRTUAL(8)