postfix-master/virtual.8.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - virtual(8) </title>
   6 </head> <body> <pre>
   7 VIRTUAL(8)                                                          VIRTUAL(8)
   8
   9 <b>NAME</b>
  10        virtual - Postfix virtual domain mail delivery agent
  11
  12 <b>SYNOPSIS</b>
  13        <b>virtual</b> [generic Postfix daemon options]
  14
  15 <b>DESCRIPTION</b>
  16        The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent is designed for virtual mail
  17        hosting services. Originally based on the Postfix <a href="local.8.html"><b>local</b>(8)</a>
  18        delivery  agent,  this  agent looks up recipients with map
  19        lookups of their full recipient address, instead of  using
  20        hard-coded unix password file lookups of the address local
  21        part only.
  22
  23        This delivery agent only delivers  mail.   Other  features
  24        such  as  mail  forwarding,  out-of-office  notifications,
  25        etc., must be configured via  virtual_alias  maps  or  via
  26        similar lookup mechanisms.
  27
  28 <b>MAILBOX LOCATION</b>
  29        The  mailbox  location  is controlled by the <b><a href="postconf.5.html#virtual_mailbox_base">virtual_mail</a>-</b>
  30        <b><a href="postconf.5.html#virtual_mailbox_base">box_base</a></b> and <b><a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a></b> configuration parameters
  31        (see below).  The <b><a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a></b> table is indexed by
  32        the recipient address  as  described  under  TABLE  SEARCH
  33        ORDER below.
  34
  35        The mailbox pathname is constructed as follows:
  36
  37          <b>$<a href="postconf.5.html#virtual_mailbox_base">virtual_mailbox_base</a>/$virtual_mailbox_maps(</b><i>recipient</i><b>)</b>
  38
  39        where <i>recipient</i> is the full recipient address.
  40
  41 <b>UNIX MAILBOX FORMAT</b>
  42        When  the  mailbox location does not end in <b>/</b>, the message
  43        is delivered in UNIX mailbox format.   This format  stores
  44        multiple messages in one textfile.
  45
  46        The  <a href="virtual.8.html"><b>virtual</b>(8)</a>  delivery  agent  prepends  a "<b>From</b> <i>sender</i>
  47        <i>time</i><b>_</b><i>stamp</i>" envelope header to each  message,  prepends  a
  48        <b>Delivered-To:</b>  message  header with the envelope recipient
  49        address, prepends an <b>X-Original-To:</b> header with the recip-
  50        ient  address as given to Postfix, prepends a <b>Return-Path:</b>
  51        message header with the envelope sender address,  prepends
  52        a &gt; character to lines beginning with "<b>From</b> ", and appends
  53        an empty line.
  54
  55        The mailbox is locked for exclusive access while  delivery
  56        is in progress. In case of problems, an attempt is made to
  57        truncate the mailbox to its original length.
  58
  59 <b>QMAIL MAILDIR FORMAT</b>
  60        When the mailbox location ends in <b>/</b>, the message is deliv-
  61        ered  in qmail <b>maildir</b> format. This format stores one mes-
  62        sage per file.
  63
  64        The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery  agent  prepends  a  <b>Delivered-To:</b>
  65        message  header with the final envelope recipient address,
  66        prepends  an  <b>X-Original-To:</b>  header  with  the  recipient
  67        address  as  given to Postfix, and prepends a <b>Return-Path:</b>
  68        message header with the envelope sender address.
  69
  70        By definition, <b>maildir</b> format does  not  require  applica-
  71        tion-level file locking during mail delivery or retrieval.
  72
  73 <b>MAILBOX OWNERSHIP</b>
  74        Mailbox ownership is controlled  by  the  <b><a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a></b>
  75        and <b><a href="postconf.5.html#virtual_gid_maps">virtual_gid_maps</a></b> lookup tables, which are indexed with
  76        the full recipient address. Each table provides  a  string
  77        with the numerical user and group ID, respectively.
  78
  79        The <b><a href="postconf.5.html#virtual_minimum_uid">virtual_minimum_uid</a></b> parameter imposes a lower bound on
  80        numerical user ID values that may be specified in any <b><a href="postconf.5.html#virtual_uid_maps">vir</a>-</b>
  81        <b><a href="postconf.5.html#virtual_uid_maps">tual_uid_maps</a></b>.
  82
  83 <b>CASE FOLDING</b>
  84        All  delivery  decisions are made using the full recipient
  85        address, folded to lower case. See also the  next  section
  86        for a few exceptions with optional address extensions.
  87
  88 <b>TABLE SEARCH ORDER</b>
  89        Normally,  a lookup table is specified as a text file that
  90        serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The result,  an
  91        indexed file in <b>dbm</b> or <b>db</b> format, is used for fast search-
  92        ing by the mail system.
  93
  94        The search order is as follows. The search stops upon  the
  95        first successful lookup.
  96
  97        <b>o</b>      When  the  recipient has an optional address exten-
  98               sion  the  <i>user+extension@domain.tld</i>   address   is
  99               looked up first.
 100
 101               With  Postfix  versions  before  2.1,  the optional
 102               address extension is always ignored.
 103
 104        <b>o</b>      The <i>user@domain.tld</i> address, without address exten-
 105               sion, is looked up next.
 106
 107        <b>o</b>      Finally, the recipient <i>@domain</i> is looked up.
 108
 109        When  the  table  is provided via other means such as NIS,
 110        LDAP or SQL, the same lookups are  done  as  for  ordinary
 111        indexed files.
 112
 113        Alternatively,  a  table  can  be  provided  as a regular-
 114        expression map where patterns are given as regular expres-
 115        sions.  In  that  case, only the full recipient address is
 116        given to the regular-expression map.
 117
 118 <b>SECURITY</b>
 119        The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent is not  security  sensitive,
 120        provided  that the lookup tables with recipient user/group
 121        ID information are adequately protected. This  program  is
 122        not designed to run chrooted.
 123
 124        The <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent disallows regular expression
 125        substitution of  $1  etc.  in  regular  expression  lookup
 126        tables, because that would open a security hole.
 127
 128        The   <a href="virtual.8.html"><b>virtual</b>(8)</a>   delivery  agent  will  silently  ignore
 129        requests to use the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server.  Instead  it  will
 130        open  the  table directly. Before Postfix version 2.2, the
 131        virtual delivery agent will terminate with a fatal  error.
 132
 133 <b>STANDARDS</b>
 134        <a href="http://tools.ietf.org/html/rfc822">RFC 822</a> (ARPA Internet Text Messages)
 135
 136 <b>DIAGNOSTICS</b>
 137        Mail bounces when the recipient has no mailbox or when the
 138        recipient is over disk quota. In all other cases, mail for
 139        an existing recipient is deferred and a warning is logged.
 140
 141        Problems and transactions are logged to <b>syslogd</b>(8).   Cor-
 142        rupted  message files are marked so that the queue manager
 143        can move them to the <b>corrupt</b> queue afterwards.
 144
 145        Depending on the setting of the <b><a href="postconf.5.html#notify_classes">notify_classes</a></b>  parameter,
 146        the  postmaster  is notified of bounces and of other trou-
 147        ble.
 148
 149 <b>BUGS</b>
 150        This delivery agent supports address extensions  in  email
 151        addresses and in lookup table keys, but does not propagate
 152        address extension  information  to  the  result  of  table
 153        lookup.
 154
 155        Postfix should have lookup tables that can return multiple
 156        result attributes. In order to avoid the inconvenience  of
 157        maintaining three tables, use an LDAP or MYSQL database.
 158
 159 <b>CONFIGURATION PARAMETERS</b>
 160        Changes  to  <a href="postconf.5.html"><b>main.cf</b></a>  are picked up automatically, as <a href="virtual.8.html"><b>vir-</b></a>
 161        <a href="virtual.8.html"><b>tual</b>(8)</a> processes run for only a limited amount  of  time.
 162        Use the command "<b>postfix reload</b>" to speed up a change.
 163
 164        The  text  below  provides  only  a parameter summary. See
 165        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
 166
 167 <b>MAILBOX DELIVERY CONTROLS</b>
 168        <b><a href="postconf.5.html#virtual_mailbox_base">virtual_mailbox_base</a> (empty)</b>
 169               A  prefix  that  the  <a href="virtual.8.html"><b>virtual</b>(8)</a>   delivery   agent
 170               prepends   to   all  pathname  results  from  $<a href="postconf.5.html#virtual_mailbox_maps">vir</a>-
 171               <a href="postconf.5.html#virtual_mailbox_maps">tual_mailbox_maps</a> table lookups.
 172
 173        <b><a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a> (empty)</b>
 174               Optional lookup tables with all valid addresses  in
 175               the domains that match $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>.
 176
 177        <b><a href="postconf.5.html#virtual_minimum_uid">virtual_minimum_uid</a> (100)</b>
 178               The  minimum  user  ID  value  that  the <a href="virtual.8.html"><b>virtual</b>(8)</a>
 179               delivery agent  accepts  as  a  result  from  $<a href="postconf.5.html#virtual_uid_maps">vir</a>-
 180               <a href="postconf.5.html#virtual_uid_maps">tual_uid_maps</a> table lookup.
 181
 182        <b><a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a> (empty)</b>
 183               Lookup  tables  with the per-recipient user ID that
 184               the <a href="virtual.8.html"><b>virtual</b>(8)</a> delivery agent uses while writing to
 185               the recipient's mailbox.
 186
 187        <b><a href="postconf.5.html#virtual_gid_maps">virtual_gid_maps</a> (empty)</b>
 188               Lookup  tables  with the per-recipient group ID for
 189               <a href="virtual.8.html"><b>virtual</b>(8)</a> mailbox delivery.
 190
 191        Available in Postfix version 2.0 and later:
 192
 193        <b><a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a> ($<a href="postconf.5.html#virtual_mailbox_maps">virtual_mailbox_maps</a>)</b>
 194               Postfix is final destination for the specified list
 195               of   domains;  mail  is  delivered  via  the  $<a href="postconf.5.html#virtual_transport">vir</a>-
 196               <a href="postconf.5.html#virtual_transport">tual_transport</a> mail delivery transport.
 197
 198        <b><a href="postconf.5.html#virtual_transport">virtual_transport</a> (virtual)</b>
 199               The default mail delivery  transport  and  next-hop
 200               destination  for  final  delivery to domains listed
 201               with $<a href="postconf.5.html#virtual_mailbox_domains">virtual_mailbox_domains</a>.
 202
 203        Available in Postfix version 2.5.3 and later:
 204
 205        <b><a href="postconf.5.html#strict_mailbox_ownership">strict_mailbox_ownership</a> (yes)</b>
 206               Defer delivery when a mailbox file is not owned  by
 207               its recipient.
 208
 209 <b>LOCKING CONTROLS</b>
 210        <b><a href="postconf.5.html#virtual_mailbox_lock">virtual_mailbox_lock</a> (see 'postconf -d' output)</b>
 211               How  to lock a UNIX-style <a href="virtual.8.html"><b>virtual</b>(8)</a> mailbox before
 212               attempting delivery.
 213
 214        <b><a href="postconf.5.html#deliver_lock_attempts">deliver_lock_attempts</a> (20)</b>
 215               The maximal number of attempts to acquire an exclu-
 216               sive lock on a mailbox file or <a href="bounce.8.html"><b>bounce</b>(8)</a> logfile.
 217
 218        <b><a href="postconf.5.html#deliver_lock_delay">deliver_lock_delay</a> (1s)</b>
 219               The  time  between attempts to acquire an exclusive
 220               lock on a mailbox file or <a href="bounce.8.html"><b>bounce</b>(8)</a> logfile.
 221
 222        <b><a href="postconf.5.html#stale_lock_time">stale_lock_time</a> (500s)</b>
 223               The time after  which  a  stale  exclusive  mailbox
 224               lockfile is removed.
 225
 226 <b>RESOURCE AND RATE CONTROLS</b>
 227        <b><a href="postconf.5.html#virtual_destination_concurrency_limit">virtual_destination_concurrency_limit</a>   ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destina</a>-</b>
 228        <b><a href="postconf.5.html#default_destination_concurrency_limit">tion_concurrency_limit</a>)</b>
 229               The  maximal  number  of parallel deliveries to the
 230               same destination via the virtual  message  delivery
 231               transport.
 232
 233        <b><a href="postconf.5.html#virtual_destination_recipient_limit">virtual_destination_recipient_limit</a>     ($<a href="postconf.5.html#default_destination_recipient_limit">default_destina</a>-</b>
 234        <b><a href="postconf.5.html#default_destination_recipient_limit">tion_recipient_limit</a>)</b>
 235               The  maximal  number  of recipients per message for
 236               the virtual message delivery transport.
 237
 238        <b><a href="postconf.5.html#virtual_mailbox_limit">virtual_mailbox_limit</a> (51200000)</b>
 239               The maximal size in bytes  of  an  individual  <a href="virtual.8.html"><b>vir-</b></a>
 240               <a href="virtual.8.html"><b>tual</b>(8)</a>  mailbox  or  maildir  file,  or  zero  (no
 241               limit).
 242
 243 <b>MISCELLANEOUS CONTROLS</b>
 244        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 245               The default location of  the  Postfix  <a href="postconf.5.html">main.cf</a>  and
 246               <a href="master.5.html">master.cf</a> configuration files.
 247
 248        <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
 249               How  much time a Postfix daemon process may take to
 250               handle a request  before  it  is  terminated  by  a
 251               built-in watchdog timer.
 252
 253        <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
 254               The  maximal  number  of  digits  after the decimal
 255               point when logging sub-second delay values.
 256
 257        <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
 258               The time limit for sending or receiving information
 259               over an internal communication channel.
 260
 261        <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
 262               The  maximum  amount  of  time that an idle Postfix
 263               daemon process waits  for  an  incoming  connection
 264               before terminating voluntarily.
 265
 266        <b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
 267               The  maximal  number of incoming connections that a
 268               Postfix daemon process will service  before  termi-
 269               nating voluntarily.
 270
 271        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 272               The  process  ID  of  a  Postfix  command or daemon
 273               process.
 274
 275        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 276               The process name of a  Postfix  command  or  daemon
 277               process.
 278
 279        <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
 280               The  location of the Postfix top-level queue direc-
 281               tory.
 282
 283        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 284               The syslog facility of Postfix logging.
 285
 286        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 287               The mail system  name  that  is  prepended  to  the
 288               process  name  in  syslog  records, so that "smtpd"
 289               becomes, for example, "postfix/smtpd".
 290
 291 <b>SEE ALSO</b>
 292        <a href="qmgr.8.html">qmgr(8)</a>, queue manager
 293        <a href="bounce.8.html">bounce(8)</a>, delivery status reports
 294        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 295        syslogd(8), system logging
 296
 297 <b>README_FILES</b>
 298        <a href="VIRTUAL_README.html">VIRTUAL_README</a>, domain hosting howto
 299
 300 <b>LICENSE</b>
 301        The Secure Mailer license must be  distributed  with  this
 302        software.
 303
 304 <b>HISTORY</b>
 305        This  delivery  agent  was originally based on the Postfix
 306        local delivery agent. Modifications  mainly  consisted  of
 307        removing  code  that either was not applicable or that was
 308        not safe in this context: aliases,  ~user/.forward  files,
 309        delivery to "|command" or to /file/name.
 310
 311        The <b>Delivered-To:</b> message header appears in the <b>qmail</b> sys-
 312        tem by Daniel Bernstein.
 313
 314        The <b>maildir</b> structure  appears  in  the  <b>qmail</b>  system  by
 315        Daniel Bernstein.
 316
 317 <b>AUTHOR(S)</b>
 318        Wietse Venema
 319        IBM T.J. Watson Research
 320        P.O. Box 704
 321        Yorktown Heights, NY 10598, USA
 322
 323        Andrew McNamara
 324        andrewm@connect.com.au
 325        connect.com.au Pty. Ltd.
 326        Level 3, 213 Miller St
 327        North Sydney 2060, NSW, Australia
 328
 329                                                                     VIRTUAL(8)
 330 </pre> </body> </html>