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