postfix-master/generics.5.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 - generics(5) </title>
   6 </head> <body> <pre>
   7 GENERICS(5)                                           GENERICS(5)
   8
   9 <b>NAME</b>
  10        generics - Postfix generics table format
  11
  12 <b>SYNOPSIS</b>
  13        <b>postmap /etc/postfix/generics</b>
  14
  15        <b>postmap -q "</b><i>string</i><b>" /etc/postfix/generics</b>
  16
  17        <b>postmap -q - /etc/postfix/generics</b> &lt;<i>inputfile</i>
  18
  19 <b>DESCRIPTION</b>
  20        The  optional  <a href="generics.5.html"><b>generics</b>(5)</a> table specifies an address map-
  21        ping that applies when mail  is  delivered.  This  is  the
  22        opposite  of <a href="canonical.5.html"><b>canonical</b>(5)</a> mapping, which applies when mail
  23        is received.
  24
  25        Typically, one would use the <a href="generics.5.html"><b>generics</b>(5)</a> table on a system
  26        that  does  not have a valid Internet domain name and that
  27        uses something like <i>localdomain.local</i> instead.  The <a href="generics.5.html"><b>gener-</b></a>
  28        <a href="generics.5.html"><b>ics</b>(5)</a>  table is then used by the <a href="smtp.8.html"><b>smtp</b>(8)</a> client to trans-
  29        form  local  mail  addresses  into  valid  Internet   mail
  30        addresses  when  mail  has to be sent across the Internet.
  31        See the EXAMPLE section at the end of this document.
  32
  33        The  <a href="generics.5.html"><b>generics</b>(5)</a>  mapping  affects  both  message   header
  34        addresses (i.e. addresses that appear inside messages) and
  35        message envelope addresses  (for  example,  the  addresses
  36        that are used in SMTP protocol commands).
  37
  38        Normally,  the  <a href="generics.5.html"><b>generics</b>(5)</a>  table  is specified as a text
  39        file that serves as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command.   The
  40        result,  an  indexed file in <b>dbm</b> or <b>db</b> format, is used for
  41        fast searching by the mail  system.  Execute  the  command
  42        "<b>postmap  /etc/postfix/generics</b>"  in  order to rebuild the
  43        indexed file after changing the text file.
  44
  45        When the table is provided via other means  such  as  NIS,
  46        LDAP  or  SQL,  the  same lookups are done as for ordinary
  47        indexed files.
  48
  49        Alternatively, the table can be  provided  as  a  regular-
  50        expression map where patterns are given as regular expres-
  51        sions, or lookups can be directed to TCP-based server.  In
  52        that  case,  the  lookups are done in a slightly different
  53        way as described below under "REGULAR  EXPRESSION  TABLES"
  54        and "TCP-BASED TABLES".
  55
  56 <b>TABLE FORMAT</b>
  57        The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows:
  58
  59        <i>pattern result</i>
  60               When <i>pattern</i> matches a mail address, replace it  by
  61               the corresponding <i>result</i>.
  62
  63        blank lines and comments
  64               Empty  lines and whitespace-only lines are ignored,
  65               as are lines whose first  non-whitespace  character
  66               is a `#'.
  67
  68        multi-line text
  69               A  logical  line starts with non-whitespace text. A
  70               line that starts with whitespace continues a  logi-
  71               cal line.
  72
  73 <b>TABLE SEARCH ORDER</b>
  74        With lookups from indexed files such as DB or DBM, or from
  75        networked tables such as NIS, LDAP or  SQL,  patterns  are
  76        tried in the order as listed below:
  77
  78        <i>user</i>@<i>domain address</i>
  79               Replace  <i>user</i>@<i>domain</i>  by <i>address</i>. This form has the
  80               highest precedence.
  81
  82        <i>user address</i>
  83               Replace <i>user</i>@<i>site</i> by <i>address</i> when <i>site</i> is equal  to
  84               $<b><a href="postconf.5.html#myorigin">myorigin</a></b>,  when  <i>site</i> is listed in $<b><a href="postconf.5.html#mydestination">mydestination</a></b>,
  85               or  when  it  is  listed  in  $<b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b>   or
  86               $<b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>.
  87
  88        @<i>domain address</i>
  89               Replace other addresses in <i>domain</i> by <i>address</i>.  This
  90               form has the lowest precedence.
  91
  92 <b>RESULT ADDRESS REWRITING</b>
  93        The lookup result is subject to address rewriting:
  94
  95        <b>o</b>      When the result  has  the  form  @<i>otherdomain</i>,  the
  96               result becomes the same <i>user</i> in <i>otherdomain</i>.
  97
  98        <b>o</b>      When  "<b><a href="postconf.5.html#append_at_myorigin">append_at_myorigin</a>=yes</b>", append "<b>@$<a href="postconf.5.html#myorigin">myorigin</a></b>"
  99               to addresses without "@domain".
 100
 101        <b>o</b>      When "<b><a href="postconf.5.html#append_dot_mydomain">append_dot_mydomain</a>=yes</b>", append "<b>.$<a href="postconf.5.html#mydomain">mydomain</a></b>"
 102               to addresses without ".domain".
 103
 104 <b>ADDRESS EXTENSION</b>
 105        When a mail address localpart contains the optional recip-
 106        ient delimiter (e.g., <i>user+foo</i>@<i>domain</i>), the  lookup  order
 107        becomes: <i>user+foo</i>@<i>domain</i>, <i>user</i>@<i>domain</i>, <i>user+foo</i>, <i>user</i>, and
 108        @<i>domain</i>.
 109
 110        The  <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b>   parameter   controls
 111        whether  an  unmatched  address extension (<i>+foo</i>) is propa-
 112        gated to the result of table lookup.
 113
 114 <b>REGULAR EXPRESSION TABLES</b>
 115        This section describes how the table lookups  change  when
 116        the table is given in the form of regular expressions. For
 117        a description of regular expression lookup  table  syntax,
 118        see <a href="regexp_table.5.html"><b>regexp_table</b>(5)</a> or <a href="pcre_table.5.html"><b>pcre_table</b>(5)</a>.
 119
 120        Each  pattern  is  a regular expression that is applied to
 121        the entire address being looked up. Thus, <i>user@domain</i> mail
 122        addresses  are  not  broken up into their <i>user</i> and <i>@domain</i>
 123        constituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and
 124        <i>foo</i>.
 125
 126        Patterns  are  applied  in  the  order as specified in the
 127        table, until a pattern is found that  matches  the  search
 128        string.
 129
 130        Results  are  the  same as with indexed file lookups, with
 131        the additional feature that parenthesized substrings  from
 132        the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on.
 133
 134 <b>TCP-BASED TABLES</b>
 135        This  section  describes how the table lookups change when
 136        lookups are directed to a TCP-based server. For a descrip-
 137        tion   of  the  TCP  client/server  lookup  protocol,  see
 138        <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>.  This feature is not  available  up  to  and
 139        including Postfix version 2.2.
 140
 141        Each lookup operation uses the entire address once.  Thus,
 142        <i>user@domain</i> mail addresses are not broken  up  into  their
 143        <i>user</i> and <i>@domain</i> constituent parts, nor is <i>user+foo</i> broken
 144        up into <i>user</i> and <i>foo</i>.
 145
 146        Results are the same as with indexed file lookups.
 147
 148 <b>EXAMPLE</b>
 149        The following shows a  generic  mapping  with  an  indexed
 150        file.   When  mail is sent to a remote host via SMTP, this
 151        replaces <i>his@localdomain.local</i> by his  ISP  mail  address,
 152        replaces  <i>her@localdomain.local</i>  by  her ISP mail address,
 153        and replaces other local addresses  by  his  ISP  account,
 154        with  an address extension of <i>+local</i> (this example assumes
 155        that the ISP supports "+" style address extensions).
 156
 157        /etc/postfix/main.cf:
 158                <a href="postconf.5.html#smtp_generics_maps">smtp_generics_maps</a> = hash:/etc/postfix/generics
 159
 160        /etc/postfix/generics:
 161                his@localdomain.local   hisaccount@hisisp.example
 162                her@localdomain.local   heraccount@herisp.example
 163                @localdomain.local      hisaccount+local@hisisp.example
 164
 165        Execute the command "<b>postmap /etc/postfix/generics</b>"  when-
 166        ever  the table is changed.  Instead of <b>hash</b>, some systems
 167        use <b>dbm</b> database files. To find out what tables your  sys-
 168        tem supports use the command "<b>postconf -m</b>".
 169
 170 <b>BUGS</b>
 171        The  table format does not understand quoting conventions.
 172
 173 <b>CONFIGURATION PARAMETERS</b>
 174        The following <b>main.cf</b> parameters are especially  relevant.
 175        The  text  below  provides  only  a parameter summary. See
 176        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
 177
 178        <b><a href="postconf.5.html#smtp_generics_maps">smtp_generics_maps</a></b>
 179               Address  mapping  lookup  table  for  envelope  and
 180               header  sender and recipient addresses while deliv-
 181               ering mail via SMTP.
 182
 183        <b><a href="postconf.5.html#propagate_unmatched_extensions">propagate_unmatched_extensions</a></b>
 184               A list of address rewriting  or  forwarding  mecha-
 185               nisms  that propagate an address extension from the
 186               original address to the result.   Specify  zero  or
 187               more   of   <b>canonical</b>,   <b>virtual</b>,  <b>alias</b>,  <b>forward</b>,
 188               <b>include</b>, or <b>generics</b>.
 189
 190        Other parameters of interest:
 191
 192        <b><a href="postconf.5.html#inet_interfaces">inet_interfaces</a></b>
 193               The network interface addresses  that  this  system
 194               receives mail on.  You need to stop and start Post-
 195               fix when this parameter changes.
 196
 197        <b><a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a></b>
 198               Other interfaces that this machine receives mail on
 199               by way of a proxy agent or network address transla-
 200               tor.
 201
 202        <b><a href="postconf.5.html#mydestination">mydestination</a></b>
 203               List of domains that  this  mail  system  considers
 204               local.
 205
 206        <b><a href="postconf.5.html#myorigin">myorigin</a></b>
 207               The domain that is appended to locally-posted mail.
 208
 209        <b><a href="postconf.5.html#owner_request_special">owner_request_special</a></b>
 210               Give special treatment to <b>owner-</b><i>xxx</i> and <i>xxx</i><b>-request</b>
 211               addresses.
 212
 213 <b>SEE ALSO</b>
 214        <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
 215        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 216        <a href="smtp.8.html">smtp(8)</a>, Postfix SMTP client
 217
 218 <b>README FILES</b>
 219        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 220        <a href="ADDRESS_REWRITING_README.html">ADDRESS_REWRITING_README</a>, address rewriting guide
 221
 222 <b>LICENSE</b>
 223        The Secure Mailer license must be  distributed  with  this
 224        software.
 225
 226 <b>HISTORY</b>
 227        A genericstable feature appears in the Sendmail MTA.
 228
 229        This feature is available in Postfix 2.2 and later.
 230
 231 <b>AUTHOR(S)</b>
 232        Wietse Venema
 233        IBM T.J. Watson Research
 234        P.O. Box 704
 235        Yorktown Heights, NY 10598, USA
 236
 237                                                       GENERICS(5)
 238 </pre> </body> </html>