external/ibm-public/postfix/dist/html/access.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 - access(5) </title>
   6 </head> <body> <pre>
   7 ACCESS(5)                                                            ACCESS(5)
   8
   9 <b>NAME</b>
  10        access - Postfix SMTP server access table
  11
  12 <b>SYNOPSIS</b>
  13        <b>postmap /etc/postfix/access</b>
  14
  15        <b>postmap -q "</b><i>string</i><b>" /etc/postfix/access</b>
  16
  17        <b>postmap -q - /etc/postfix/access</b> &lt;<i>inputfile</i>
  18
  19 <b>DESCRIPTION</b>
  20        This  document  describes  access  control  on remote SMTP
  21        client information: host  names,  network  addresses,  and
  22        envelope  sender or recipient addresses; it is implemented
  23        by the  Postfix  SMTP  server.   See  <a href="header_checks.5.html"><b>header_checks</b>(5)</a>  or
  24        <a href="header_checks.5.html"><b>body_checks</b>(5)</a>  for access control on the content of email
  25        messages.
  26
  27        Normally, the <a href="access.5.html"><b>access</b>(5)</a> table is specified as a text  file
  28        that  serves  as  input  to  the  <a href="postmap.1.html"><b>postmap</b>(1)</a> command.  The
  29        result, an indexed file in <b>dbm</b> or <b>db</b> format, is  used  for
  30        fast  searching  by  the  mail system. Execute the command
  31        "<b>postmap /etc/postfix/access</b>" to rebuild an  indexed  file
  32        after changing the corresponding text file.
  33
  34        When  the  table  is provided via other means such as NIS,
  35        LDAP or SQL, the same lookups are  done  as  for  ordinary
  36        indexed files.
  37
  38        Alternatively,  the  table  can  be provided as a regular-
  39        expression map where patterns are given as regular expres-
  40        sions,  or lookups can be directed to TCP-based server. In
  41        those cases, the lookups are done in a slightly  different
  42        way  as  described below under "REGULAR EXPRESSION TABLES"
  43        or "TCP-BASED TABLES".
  44
  45 <b>CASE FOLDING</b>
  46        The search string is folded to lowercase  before  database
  47        lookup.  As  of Postfix 2.3, the search string is not case
  48        folded with database types such as <a href="regexp_table.5.html">regexp</a>: or <a href="pcre_table.5.html">pcre</a>:  whose
  49        lookup fields can match both upper and lower case.
  50
  51 <b>TABLE FORMAT</b>
  52        The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows:
  53
  54        <i>pattern action</i>
  55               When <i>pattern</i> matches a mail address, domain or host
  56               address, perform the corresponding <i>action</i>.
  57
  58        blank lines and comments
  59               Empty  lines and whitespace-only lines are ignored,
  60               as are lines whose first  non-whitespace  character
  61               is a `#'.
  62
  63        multi-line text
  64               A  logical  line starts with non-whitespace text. A
  65               line that starts with whitespace continues a  logi-
  66               cal line.
  67
  68 <b>EMAIL ADDRESS PATTERNS</b>
  69        With lookups from indexed files such as DB or DBM, or from
  70        networked tables such as NIS, LDAP or  SQL,  patterns  are
  71        tried in the order as listed below:
  72
  73        <i>user</i>@<i>domain</i>
  74               Matches the specified mail address.
  75
  76        <i>domain.tld</i>
  77               Matches  <i>domain.tld</i>  as the domain part of an email
  78               address.
  79
  80               The pattern <i>domain.tld</i> also matches subdomains, but
  81               only when the string <b>smtpd_access_maps</b> is listed in
  82               the Postfix  <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a></b>  con-
  83               figuration  setting  (note that this is the default
  84               for some versions of Postfix).  Otherwise,  specify
  85               <i>.domain.tld</i>  (note  the  initial  dot)  in order to
  86               match subdomains.
  87
  88        <i>user</i>@  Matches all mail addresses with the specified  user
  89               part.
  90
  91        Note:  lookup  of  the null sender address is not possible
  92        with some types of lookup table. By default, Postfix  uses
  93        &lt;&gt;  as  the  lookup  key  for such addresses. The value is
  94        specified with the <b><a href="postconf.5.html#smtpd_null_access_lookup_key">smtpd_null_access_lookup_key</a></b>  parameter
  95        in the Postfix <a href="postconf.5.html"><b>main.cf</b></a> file.
  96
  97 <b>EMAIL ADDRESS EXTENSION</b>
  98        When a mail address localpart contains the optional recip-
  99        ient delimiter (e.g., <i>user+foo</i>@<i>domain</i>), the  lookup  order
 100        becomes:  <i>user+foo</i>@<i>domain</i>, <i>user</i>@<i>domain</i>, <i>domain</i>, <i>user+foo</i>@,
 101        and <i>user</i>@.
 102
 103 <b>HOST NAME/ADDRESS PATTERNS</b>
 104        With lookups from indexed files such as DB or DBM, or from
 105        networked  tables  such as NIS, LDAP or SQL, the following
 106        lookup patterns are examined in the order as listed:
 107
 108        <i>domain.tld</i>
 109               Matches <i>domain.tld</i>.
 110
 111               The pattern <i>domain.tld</i> also matches subdomains, but
 112               only when the string <b>smtpd_access_maps</b> is listed in
 113               the Postfix  <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a></b>  con-
 114               figuration setting.  Otherwise, specify <i>.domain.tld</i>
 115               (note the initial dot) in  order  to  match  subdo-
 116               mains.
 117
 118        <i>net.work.addr.ess</i>
 119
 120        <i>net.work.addr</i>
 121
 122        <i>net.work</i>
 123
 124        <i>net</i>    Matches  the specified IPv4 host address or subnet-
 125               work. An IPv4 host address is a  sequence  of  four
 126               decimal octets separated by ".".
 127
 128               Subnetworks  are  matched  by repeatedly truncating
 129               the last ".octet" from the remote IPv4 host address
 130               string  until a match is found in the access table,
 131               or until further truncation is not possible.
 132
 133               NOTE 1: The access map lookup key must be in canon-
 134               ical  form: do not specify unnecessary null charac-
 135               ters, and do not enclose network  address  informa-
 136               tion with "[]" characters.
 137
 138               NOTE  2:  use the <b>cidr</b> lookup table type to specify
 139               network/netmask  patterns.  See  <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a>  for
 140               details.
 141
 142        <i>net:work:addr:ess</i>
 143
 144        <i>net:work:addr</i>
 145
 146        <i>net:work</i>
 147
 148        <i>net</i>    Matches  the specified IPv6 host address or subnet-
 149               work. An IPv6 host address is a sequence  of  three
 150               to  eight hexadecimal octet pairs separated by ":".
 151
 152               Subnetworks are matched  by  repeatedly  truncating
 153               the  last  ":octetpair"  from  the remote IPv6 host
 154               address string until a match is found in the access
 155               table, or until further truncation is not possible.
 156
 157               NOTE 1: the truncation and comparison are done with
 158               the string representation of the IPv6 host address.
 159               Thus, not all the ":" subnetworks will be tried.
 160
 161               NOTE 2: The access map lookup key must be in canon-
 162               ical  form: do not specify unnecessary null charac-
 163               ters, and do not enclose network  address  informa-
 164               tion with "[]" characters.
 165
 166               NOTE  3:  use the <b>cidr</b> lookup table type to specify
 167               network/netmask  patterns.  See  <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a>  for
 168               details.
 169
 170               IPv6 support is available in Postfix 2.2 and later.
 171
 172 <b>ACCEPT ACTIONS</b>
 173        <b>OK</b>     Accept the address etc. that matches the pattern.
 174
 175        <i>all-numerical</i>
 176               An all-numerical result is treated as OK. This for-
 177               mat  is generated by address-based relay authoriza-
 178               tion schemes such as pop-before-smtp.
 179
 180 <b>REJECT ACTIONS</b>
 181        Postfix version 2.3  and  later  support  enhanced  status
 182        codes  as  defined in <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>.  When no code is specified
 183        at the beginning of the  <i>text</i>  below,  Postfix  inserts  a
 184        default  enhanced  status  code  of "5.7.1" in the case of
 185        reject actions, and "4.7.1" in the case of defer  actions.
 186        See "ENHANCED STATUS CODES" below.
 187
 188        <b>4</b><i>NN text</i>
 189
 190        <b>5</b><i>NN text</i>
 191               Reject  the  address etc. that matches the pattern,
 192               and respond with the numerical three-digit code and
 193               text.  <b>4</b><i>NN</i> means "try again later", while <b>5</b><i>NN</i> means
 194               "do not try again".
 195
 196               The reply code "421" causes Postfix  to  disconnect
 197               immediately (Postfix version 2.3 and later).
 198
 199        <b>REJECT</b> <i>optional text...</i>
 200               Reject  the  address etc. that matches the pattern.
 201               Reply   with   "<b>$<a href="postconf.5.html#access_map_reject_code">access_map_reject_code</a></b>    <i>optional</i>
 202               <i>text...</i>"  when the optional text is specified, oth-
 203               erwise reply with a generic error response message.
 204
 205        <b>DEFER</b> <i>optional text...</i>
 206               Reject  the  address etc. that matches the pattern.
 207               Reply   with    "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a></b>    <i>optional</i>
 208               <i>text...</i>"  when the optional text is specified, oth-
 209               erwise reply with a generic error response message.
 210
 211               This feature is available in Postfix 2.6 and later.
 212
 213        <b>DEFER_IF_REJECT</b> <i>optional text...</i>
 214               Defer the request if some later  restriction  would
 215               result    in    a   REJECT   action.   Reply   with
 216               "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a>  4.7.1</b>  <i>optional   text...</i>"
 217               when  the  optional  text  is  specified, otherwise
 218               reply with a generic error response message.
 219
 220               Prior to Postfix 2.6, the SMTP reply code is 450.
 221
 222               This feature is available in Postfix 2.1 and later.
 223
 224        <b>DEFER_IF_PERMIT</b> <i>optional text...</i>
 225               Defer  the  request if some later restriction would
 226               result in a an explicit or implicit PERMIT  action.
 227               Reply  with "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a> 4.7.1</b>  <i>optional</i>
 228               <i>text...</i>" when the optional text is specified,  oth-
 229               erwise reply with a generic error response message.
 230
 231               Prior to Postfix 2.6, the SMTP reply code is 450.
 232
 233               This feature is available in Postfix 2.1 and later.
 234
 235 <b>OTHER ACTIONS</b>
 236        <i>restriction...</i>
 237               Apply the named UCE restriction(s) (<b>permit</b>, <b>reject</b>,
 238               <b><a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a></b>, and so on).
 239
 240        <b>BCC</b> <i>user@domain</i>
 241               Send one copy  of  the  message  to  the  specified
 242               recipient.
 243
 244               If  multiple  BCC  actions are specified within the
 245               same SMTP MAIL transaction, only  the  last  action
 246               will be used.
 247
 248               This  feature  is  not  part  of the stable Postfix
 249               release.
 250
 251        <b>DISCARD</b> <i>optional text...</i>
 252               Claim successful delivery and silently discard  the
 253               message.   Log the optional text if specified, oth-
 254               erwise log a generic message.
 255
 256               Note: this action currently affects all  recipients
 257               of  the  message.   To  discard  only one recipient
 258               without discarding  the  entire  message,  use  the
 259               <a href="transport.5.html">transport(5)</a> table to direct mail to the <a href="discard.8.html">discard(8)</a>
 260               service.
 261
 262               This feature is available in Postfix 2.0 and later.
 263
 264        <b>DUNNO</b>  Pretend  that  the  lookup  key was not found. This
 265               prevents Postfix  from  trying  substrings  of  the
 266               lookup  key (such as a subdomain name, or a network
 267               address subnetwork).
 268
 269               This feature is available in Postfix 2.0 and later.
 270
 271        <b>FILTER</b> <i>transport:destination</i>
 272               After  the  message is queued, send the entire mes-
 273               sage through the specified external content filter.
 274               The  <i>transport:destination</i>  syntax  is described in
 275               the <a href="transport.5.html"><b>transport</b>(5)</a>  manual  page.   More  information
 276               about  external  content  filters is in the Postfix
 277               <a href="FILTER_README.html">FILTER_README</a> file.
 278
 279               Note: this action overrides the <b><a href="postconf.5.html#content_filter">content_filter</a></b> set-
 280               ting,  and  currently affects all recipients of the
 281               message.
 282
 283               This feature is available in Postfix 2.0 and later.
 284
 285        <b>HOLD</b> <i>optional text...</i>
 286               Place  the message on the <b>hold</b> queue, where it will
 287               sit until someone either deletes it or releases  it
 288               for  delivery.  Log the optional text if specified,
 289               otherwise log a generic message.
 290
 291               Mail that is placed on hold can  be  examined  with
 292               the  <a href="postcat.1.html"><b>postcat</b>(1)</a>  command,  and  can be destroyed or
 293               released with the <a href="postsuper.1.html"><b>postsuper</b>(1)</a> command.
 294
 295               Note: use "<b>postsuper -r</b>" to release mail  that  was
 296               kept  on  hold for a significant fraction of <b>$<a href="postconf.5.html#maximal_queue_lifetime">maxi</a>-</b>
 297               <b><a href="postconf.5.html#maximal_queue_lifetime">mal_queue_lifetime</a></b>  or  <b>$<a href="postconf.5.html#bounce_queue_lifetime">bounce_queue_lifetime</a></b>,  or
 298               longer.  Use "<b>postsuper -H</b>" only for mail that will
 299               not expire within a few delivery attempts.
 300
 301               Note: this action currently affects all  recipients
 302               of the message.
 303
 304               This feature is available in Postfix 2.0 and later.
 305
 306        <b>PREPEND</b> <i>headername: headervalue</i>
 307               Prepend the specified message header  to  the  mes-
 308               sage.   When more than one PREPEND action executes,
 309               the first prepended header appears before the  sec-
 310               ond etc. prepended header.
 311
 312               Note:  this  action must execute before the message
 313               content is received; it cannot execute in the  con-
 314               text of <b><a href="postconf.5.html#smtpd_end_of_data_restrictions">smtpd_end_of_data_restrictions</a></b>.
 315
 316               This feature is available in Postfix 2.1 and later.
 317
 318        <b>REDIRECT</b> <i>user@domain</i>
 319               After the message is queued, send  the  message  to
 320               the  specified  address  instead  of  the  intended
 321               recipient(s).
 322
 323               Note: this action overrides the FILTER action,  and
 324               currently affects all recipients of the message.
 325
 326               This feature is available in Postfix 2.1 and later.
 327
 328        <b>WARN</b> <i>optional text...</i>
 329               Log a warning with the optional text, together with
 330               client  information  and  if  available, with helo,
 331               sender, recipient and protocol information.
 332
 333               This feature is available in Postfix 2.1 and later.
 334
 335 <b>ENHANCED STATUS CODES</b>
 336        Postfix  version  2.3  and  later  support enhanced status
 337        codes as defined in <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>.   When  an  enhanced  status
 338        code  is  specified  in  an access table, it is subject to
 339        modification. The  following  transformations  are  needed
 340        when  the  same  access  table  is  used for client, helo,
 341        sender, or  recipient  access  restrictions;  they  happen
 342        regardless of whether Postfix replies to a MAIL FROM, RCPT
 343        TO or other SMTP command.
 344
 345        <b>o</b>      When a sender address matches a REJECT action,  the
 346               Postfix  SMTP server will transform a recipient DSN
 347               status (e.g., 4.1.1-4.1.6) into  the  corresponding
 348               sender DSN status, and vice versa.
 349
 350        <b>o</b>      When   non-address  information  matches  a  REJECT
 351               action (such as the HELO command  argument  or  the
 352               client  hostname/address),  the Postfix SMTP server
 353               will transform a sender  or  recipient  DSN  status
 354               into   a  generic  non-address  DSN  status  (e.g.,
 355               4.0.0).
 356
 357 <b>REGULAR EXPRESSION TABLES</b>
 358        This section describes how the table lookups  change  when
 359        the table is given in the form of regular expressions. For
 360        a description of regular expression lookup  table  syntax,
 361        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>.
 362
 363        Each  pattern  is  a regular expression that is applied to
 364        the entire string being looked up. Depending on the appli-
 365        cation,  that  string  is  an  entire  client hostname, an
 366        entire client IP address, or an entire mail address. Thus,
 367        no  parent  domain  or  parent  network  search  is  done,
 368        <i>user@domain</i> mail addresses are not broken  up  into  their
 369        <i>user@</i> and <i>domain</i> constituent parts, nor is <i>user+foo</i> broken
 370        up into <i>user</i> and <i>foo</i>.
 371
 372        Patterns are applied in the order as specified in the  ta-
 373        ble,  until  a  pattern  is  found that matches the search
 374        string.
 375
 376        Actions are the same as with indexed  file  lookups,  with
 377        the  additional feature that parenthesized substrings from
 378        the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on.
 379
 380 <b>TCP-BASED TABLES</b>
 381        This section describes how the table lookups  change  when
 382        lookups are directed to a TCP-based server. For a descrip-
 383        tion of the TCP client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_ta-</b></a>
 384        <a href="tcp_table.5.html"><b>ble</b>(5)</a>.  This feature is not available up to and including
 385        Postfix version 2.4.
 386
 387        Each lookup operation uses the entire query  string  once.
 388        Depending  on  the  application,  that string is an entire
 389        client hostname, an entire client IP address, or an entire
 390        mail  address.   Thus,  no parent domain or parent network
 391        search is done, <i>user@domain</i> mail addresses are not  broken
 392        up  into  their <i>user@</i> and <i>domain</i> constituent parts, nor is
 393        <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>.
 394
 395        Actions are the same as with indexed file lookups.
 396
 397 <b>EXAMPLE</b>
 398        The following example uses an indexed file,  so  that  the
 399        order  of  table entries does not matter. The example per-
 400        mits access by the client at address 1.2.3.4  but  rejects
 401        all  other  clients  in 1.2.3.0/24. Instead of <b>hash</b> lookup
 402        tables, some systems use <b>dbm</b>.  Use the  command  "<b>postconf</b>
 403        <b>-m</b>"  to  find  out  what lookup tables Postfix supports on
 404        your system.
 405
 406        /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 407            <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> =
 408                <a href="postconf.5.html#check_client_access">check_client_access</a> hash:/etc/postfix/access
 409
 410        /etc/postfix/access:
 411            1.2.3   REJECT
 412            1.2.3.4 OK
 413
 414        Execute the command  "<b>postmap  /etc/postfix/access</b>"  after
 415        editing the file.
 416
 417 <b>BUGS</b>
 418        The  table format does not understand quoting conventions.
 419
 420 <b>SEE ALSO</b>
 421        <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
 422        <a href="smtpd.8.html">smtpd(8)</a>, SMTP server
 423        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 424        <a href="transport.5.html">transport(5)</a>, transport:nexthop syntax
 425
 426 <b>README FILES</b>
 427        <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a>, built-in SMTP server access control
 428        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 429
 430 <b>LICENSE</b>
 431        The  Secure  Mailer  license must be distributed with this
 432        software.
 433
 434 <b>AUTHOR(S)</b>
 435        Wietse Venema
 436        IBM T.J. Watson Research
 437        P.O. Box 704
 438        Yorktown Heights, NY 10598, USA
 439
 440                                                                      ACCESS(5)
 441 </pre> </body> </html>