postfix-master/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.
  84
  85        <i>.domain.tld</i>
  86               Matches subdomains of <i>domain.tld</i>, but only when the
  87               string <b>smtpd_access_maps</b> is not listed in the Post-
  88               fix  <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a></b> configuration
  89               setting.
  90
  91        <i>user</i>@  Matches all mail addresses with the specified  user
  92               part.
  93
  94        Note:  lookup  of  the null sender address is not possible
  95        with some types of lookup table. By default, Postfix  uses
  96        &lt;&gt;  as  the  lookup  key  for such addresses. The value is
  97        specified with the <b><a href="postconf.5.html#smtpd_null_access_lookup_key">smtpd_null_access_lookup_key</a></b>  parameter
  98        in the Postfix <a href="postconf.5.html"><b>main.cf</b></a> file.
  99
 100 <b>EMAIL ADDRESS EXTENSION</b>
 101        When a mail address localpart contains the optional recip-
 102        ient delimiter (e.g., <i>user+foo</i>@<i>domain</i>), the  lookup  order
 103        becomes:  <i>user+foo</i>@<i>domain</i>, <i>user</i>@<i>domain</i>, <i>domain</i>, <i>user+foo</i>@,
 104        and <i>user</i>@.
 105
 106 <b>HOST NAME/ADDRESS PATTERNS</b>
 107        With lookups from indexed files such as DB or DBM, or from
 108        networked  tables  such as NIS, LDAP or SQL, the following
 109        lookup patterns are examined in the order as listed:
 110
 111        <i>domain.tld</i>
 112               Matches <i>domain.tld</i>.
 113
 114               The pattern <i>domain.tld</i> also matches subdomains, but
 115               only when the string <b>smtpd_access_maps</b> is listed in
 116               the Postfix  <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a></b>  con-
 117               figuration setting.
 118
 119        <i>.domain.tld</i>
 120               Matches subdomains of <i>domain.tld</i>, but only when the
 121               string <b>smtpd_access_maps</b> is not listed in the Post-
 122               fix  <b><a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a></b> configuration
 123               setting.
 124
 125        <i>net.work.addr.ess</i>
 126
 127        <i>net.work.addr</i>
 128
 129        <i>net.work</i>
 130
 131        <i>net</i>    Matches the specified IPv4 host address or  subnet-
 132               work.  An  IPv4  host address is a sequence of four
 133               decimal octets separated by ".".
 134
 135               Subnetworks are matched  by  repeatedly  truncating
 136               the last ".octet" from the remote IPv4 host address
 137               string until a match is found in the access  table,
 138               or until further truncation is not possible.
 139
 140               NOTE 1: The access map lookup key must be in canon-
 141               ical form: do not specify unnecessary null  charac-
 142               ters,  and  do not enclose network address informa-
 143               tion with "[]" characters.
 144
 145               NOTE 2: use the <b>cidr</b> lookup table type  to  specify
 146               network/netmask  patterns.  See  <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a>  for
 147               details.
 148
 149        <i>net:work:addr:ess</i>
 150
 151        <i>net:work:addr</i>
 152
 153        <i>net:work</i>
 154
 155        <i>net</i>    Matches the specified IPv6 host address or  subnet-
 156               work.  An  IPv6 host address is a sequence of three
 157               to eight hexadecimal octet pairs separated by  ":".
 158
 159               Subnetworks  are  matched  by repeatedly truncating
 160               the last ":octetpair" from  the  remote  IPv6  host
 161               address string until a match is found in the access
 162               table, or until further truncation is not possible.
 163
 164               NOTE 1: the truncation and comparison are done with
 165               the string representation of the IPv6 host address.
 166               Thus, not all the ":" subnetworks will be tried.
 167
 168               NOTE 2: The access map lookup key must be in canon-
 169               ical form: do not specify unnecessary null  charac-
 170               ters,  and  do not enclose network address informa-
 171               tion with "[]" characters.
 172
 173               NOTE 3: use the <b>cidr</b> lookup table type  to  specify
 174               network/netmask  patterns.  See  <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a>  for
 175               details.
 176
 177               IPv6 support is available in Postfix 2.2 and later.
 178
 179 <b>ACCEPT ACTIONS</b>
 180        <b>OK</b>     Accept the address etc. that matches the pattern.
 181
 182        <i>all-numerical</i>
 183               An all-numerical result is treated as OK. This for-
 184               mat is generated by address-based relay  authoriza-
 185               tion schemes such as pop-before-smtp.
 186
 187 <b>REJECT ACTIONS</b>
 188        Postfix  version  2.3  and  later  support enhanced status
 189        codes as defined in <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>.  When no code  is  specified
 190        at  the  beginning  of  the  <i>text</i> below, Postfix inserts a
 191        default enhanced status code of "5.7.1"  in  the  case  of
 192        reject  actions, and "4.7.1" in the case of defer actions.
 193        See "ENHANCED STATUS CODES" below.
 194
 195        <b>4</b><i>NN text</i>
 196
 197        <b>5</b><i>NN text</i>
 198               Reject the address etc. that matches  the  pattern,
 199               and respond with the numerical three-digit code and
 200               text. <b>4</b><i>NN</i> means "try again later", while <b>5</b><i>NN</i>  means
 201               "do not try again".
 202
 203               The  following  responses  have special meaning for
 204               the Postfix SMTP server:
 205
 206               <b>421</b> <i>text</i> (Postfix 2.3 and later)
 207
 208               <b>521</b> <i>text</i> (Postfix 2.6 and later)
 209                      After responding with the  numerical  three-
 210                      digit  code and text, disconnect immediately
 211                      from the SMTP client.  This  frees  up  SMTP
 212                      server  resources  so  that they can be made
 213                      available to another SMTP client.
 214
 215                      Note: The "521" response should be used only
 216                      with  botnets and other malware where inter-
 217                      operability is of no concern.  The "send 521
 218                      and  disconnect"  behavior is NOT defined in
 219                      the SMTP standard.
 220
 221        <b>REJECT</b> <i>optional text...</i>
 222               Reject the address etc. that matches  the  pattern.
 223               Reply    with   "<b>$<a href="postconf.5.html#access_map_reject_code">access_map_reject_code</a></b>   <i>optional</i>
 224               <i>text...</i>" when the optional text is specified,  oth-
 225               erwise reply with a generic error response message.
 226
 227        <b>DEFER</b> <i>optional text...</i>
 228               Reject the address etc. that matches  the  pattern.
 229               Reply    with    "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a></b>   <i>optional</i>
 230               <i>text...</i>" when the optional text is specified,  oth-
 231               erwise reply with a generic error response message.
 232
 233               This feature is available in Postfix 2.6 and later.
 234
 235        <b>DEFER_IF_REJECT</b> <i>optional text...</i>
 236               Defer  the  request if some later restriction would
 237               result   in   a   REJECT   action.    Reply    with
 238               "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a>   4.7.1</b>  <i>optional  text...</i>"
 239               when the  optional  text  is  specified,  otherwise
 240               reply with a generic error response message.
 241
 242               Prior to Postfix 2.6, the SMTP reply code is 450.
 243
 244               This feature is available in Postfix 2.1 and later.
 245
 246        <b>DEFER_IF_PERMIT</b> <i>optional text...</i>
 247               Defer the request if some later  restriction  would
 248               result  in a an explicit or implicit PERMIT action.
 249               Reply with "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a> 4.7.1</b>   <i>optional</i>
 250               <i>text...</i>"  when the optional text is specified, oth-
 251               erwise reply with a generic error response message.
 252
 253               Prior to Postfix 2.6, the SMTP reply code is 450.
 254
 255               This feature is available in Postfix 2.1 and later.
 256
 257 <b>OTHER ACTIONS</b>
 258        <i>restriction...</i>
 259               Apply the named UCE restriction(s) (<b>permit</b>, <b>reject</b>,
 260               <b><a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a></b>, and so on).
 261
 262        <b>BCC</b> <i>user@domain</i>
 263               Send  one  copy  of  the  message  to the specified
 264               recipient.
 265
 266               If multiple BCC actions are  specified  within  the
 267               same  SMTP  MAIL  transaction, only the last action
 268               will be used.
 269
 270               This feature is not  part  of  the  stable  Postfix
 271               release.
 272
 273        <b>DISCARD</b> <i>optional text...</i>
 274               Claim  successful delivery and silently discard the
 275               message.  Log the optional text if specified,  oth-
 276               erwise log a generic message.
 277
 278               Note:  this action currently affects all recipients
 279               of the message.   To  discard  only  one  recipient
 280               without  discarding  the  entire  message,  use the
 281               <a href="transport.5.html">transport(5)</a> table to direct mail to the <a href="discard.8.html">discard(8)</a>
 282               service.
 283
 284               This feature is available in Postfix 2.0 and later.
 285
 286        <b>DUNNO</b>  Pretend that the lookup key  was  not  found.  This
 287               prevents  Postfix  from  trying  substrings  of the
 288               lookup key (such as a subdomain name, or a  network
 289               address subnetwork).
 290
 291               This feature is available in Postfix 2.0 and later.
 292
 293        <b>FILTER</b> <i>transport:destination</i>
 294               After the message is queued, send the  entire  mes-
 295               sage through the specified external content filter.
 296               The <i>transport</i> name specifies the first field  of  a
 297               mail  delivery  agent  definition in <a href="master.5.html">master.cf</a>; the
 298               syntax of the next-hop <i>destination</i> is described  in
 299               the  manual  page  of  the  corresponding  delivery
 300               agent.  More  information  about  external  content
 301               filters is in the Postfix <a href="FILTER_README.html">FILTER_README</a> file.
 302
 303               Note  1: do not use $<i>number</i> regular expression sub-
 304               stitutions for <i>transport</i> or <i>destination</i> unless  you
 305               know that the information has a trusted origin.
 306
 307               Note  2:  this  action  overrides  the <a href="postconf.5.html">main.cf</a> <b><a href="postconf.5.html#content_filter">con</a>-</b>
 308               <b><a href="postconf.5.html#content_filter">tent_filter</a></b> setting, and affects all recipients  of
 309               the  message.  In  the  case  that  multiple <b>FILTER</b>
 310               actions fire, only the last one is executed.
 311
 312               Note 3: the purpose of the  FILTER  command  is  to
 313               override  message routing.  To override the recipi-
 314               ent's <i>transport</i> but not the  next-hop  <i>destination</i>,
 315               specify  an  empty  filter <i>destination</i> (Postfix 2.7
 316               and later), or specify a <i>transport:destination</i> that
 317               delivers   through  a  different  Postfix  instance
 318               (Postfix 2.6 and earlier). Other options are  using
 319               the  recipient-dependent <b><a href="postconf.5.html#transport_maps">transport_maps</a></b> or the sen-
 320               der-dependent   <b><a href="postconf.5.html#sender_dependent_default_transport_maps">sender_dependent_default_transport</a>-</b>
 321               <b><a href="postconf.5.html#sender_dependent_default_transport_maps">_maps</a></b> features.
 322
 323               This feature is available in Postfix 2.0 and later.
 324
 325        <b>HOLD</b> <i>optional text...</i>
 326               Place the message on the <b>hold</b> queue, where it  will
 327               sit  until someone either deletes it or releases it
 328               for delivery.  Log the optional text if  specified,
 329               otherwise log a generic message.
 330
 331               Mail  that  is  placed on hold can be examined with
 332               the <a href="postcat.1.html"><b>postcat</b>(1)</a> command, and  can  be  destroyed  or
 333               released with the <a href="postsuper.1.html"><b>postsuper</b>(1)</a> command.
 334
 335               Note:  use  "<b>postsuper -r</b>" to release mail that was
 336               kept on hold for a significant fraction  of  <b>$<a href="postconf.5.html#maximal_queue_lifetime">maxi</a>-</b>
 337               <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
 338               longer. Use "<b>postsuper -H</b>" only for mail that  will
 339               not expire within a few delivery attempts.
 340
 341               Note:  this action currently affects all recipients
 342               of the message.
 343
 344               This feature is available in Postfix 2.0 and later.
 345
 346        <b>PREPEND</b> <i>headername: headervalue</i>
 347               Prepend  the  specified  message header to the mes-
 348               sage.  When more than one PREPEND action  executes,
 349               the  first prepended header appears before the sec-
 350               ond etc. prepended header.
 351
 352               Note: this action must execute before  the  message
 353               content  is received; it cannot execute in the con-
 354               text of <b><a href="postconf.5.html#smtpd_end_of_data_restrictions">smtpd_end_of_data_restrictions</a></b>.
 355
 356               This feature is available in Postfix 2.1 and later.
 357
 358        <b>REDIRECT</b> <i>user@domain</i>
 359               After  the  message  is queued, send the message to
 360               the  specified  address  instead  of  the  intended
 361               recipient(s).
 362
 363               Note:  this action overrides the FILTER action, and
 364               currently affects all recipients of the message.
 365
 366               This feature is available in Postfix 2.1 and later.
 367
 368        <b>WARN</b> <i>optional text...</i>
 369               Log a warning with the optional text, together with
 370               client information and  if  available,  with  helo,
 371               sender, recipient and protocol information.
 372
 373               This feature is available in Postfix 2.1 and later.
 374
 375 <b>ENHANCED STATUS CODES</b>
 376        Postfix version 2.3  and  later  support  enhanced  status
 377        codes  as  defined  in  <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>.  When an enhanced status
 378        code is specified in an access table,  it  is  subject  to
 379        modification.  The  following  transformations  are needed
 380        when the same access  table  is  used  for  client,  helo,
 381        sender,  or  recipient  access  restrictions;  they happen
 382        regardless of whether Postfix replies to a MAIL FROM, RCPT
 383        TO or other SMTP command.
 384
 385        <b>o</b>      When  a sender address matches a REJECT action, the
 386               Postfix SMTP server will transform a recipient  DSN
 387               status  (e.g.,  4.1.1-4.1.6) into the corresponding
 388               sender DSN status, and vice versa.
 389
 390        <b>o</b>      When  non-address  information  matches  a   REJECT
 391               action  (such  as  the HELO command argument or the
 392               client hostname/address), the Postfix  SMTP  server
 393               will  transform  a  sender  or recipient DSN status
 394               into  a  generic  non-address  DSN  status   (e.g.,
 395               4.0.0).
 396
 397 <b>REGULAR EXPRESSION TABLES</b>
 398        This  section  describes how the table lookups change when
 399        the table is given in the form of regular expressions. For
 400        a  description  of regular expression lookup table syntax,
 401        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>.
 402
 403        Each pattern is a regular expression that  is  applied  to
 404        the entire string being looked up. Depending on the appli-
 405        cation, that string  is  an  entire  client  hostname,  an
 406        entire client IP address, or an entire mail address. Thus,
 407        no  parent  domain  or  parent  network  search  is  done,
 408        <i>user@domain</i>  mail  addresses  are not broken up into their
 409        <i>user@</i> and <i>domain</i> constituent parts, nor is <i>user+foo</i> broken
 410        up into <i>user</i> and <i>foo</i>.
 411
 412        Patterns  are applied in the order as specified in the ta-
 413        ble, until a pattern is  found  that  matches  the  search
 414        string.
 415
 416        Actions  are  the  same as with indexed file lookups, with
 417        the additional feature that parenthesized substrings  from
 418        the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on.
 419
 420 <b>TCP-BASED TABLES</b>
 421        This  section  describes how the table lookups change when
 422        lookups are directed to a TCP-based server. For a descrip-
 423        tion of the TCP client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_ta-</b></a>
 424        <a href="tcp_table.5.html"><b>ble</b>(5)</a>.  This feature is not available up to and including
 425        Postfix version 2.4.
 426
 427        Each  lookup  operation uses the entire query string once.
 428        Depending on the application, that  string  is  an  entire
 429        client hostname, an entire client IP address, or an entire
 430        mail address.  Thus, no parent domain  or  parent  network
 431        search  is done, <i>user@domain</i> mail addresses are not broken
 432        up into their <i>user@</i> and <i>domain</i> constituent parts,  nor  is
 433        <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>.
 434
 435        Actions are the same as with indexed file lookups.
 436
 437 <b>EXAMPLE</b>
 438        The  following  example  uses an indexed file, so that the
 439        order of table entries does not matter. The  example  per-
 440        mits  access  by the client at address 1.2.3.4 but rejects
 441        all other clients in 1.2.3.0/24. Instead  of  <b>hash</b>  lookup
 442        tables,  some  systems use <b>dbm</b>.  Use the command "<b>postconf</b>
 443        <b>-m</b>" to find out what lookup  tables  Postfix  supports  on
 444        your system.
 445
 446        /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 447            <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> =
 448                <a href="postconf.5.html#check_client_access">check_client_access</a> hash:/etc/postfix/access
 449
 450        /etc/postfix/access:
 451            1.2.3   REJECT
 452            1.2.3.4 OK
 453
 454        Execute  the  command  "<b>postmap /etc/postfix/access</b>" after
 455        editing the file.
 456
 457 <b>BUGS</b>
 458        The table format does not understand quoting  conventions.
 459
 460 <b>SEE ALSO</b>
 461        <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
 462        <a href="smtpd.8.html">smtpd(8)</a>, SMTP server
 463        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 464        <a href="transport.5.html">transport(5)</a>, transport:nexthop syntax
 465
 466 <b>README FILES</b>
 467        <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a>, built-in SMTP server access control
 468        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 469
 470 <b>LICENSE</b>
 471        The Secure Mailer license must be  distributed  with  this
 472        software.
 473
 474 <b>AUTHOR(S)</b>
 475        Wietse Venema
 476        IBM T.J. Watson Research
 477        P.O. Box 704
 478        Yorktown Heights, NY 10598, USA
 479
 480                                                                      ACCESS(5)
 481 </pre> </body> </html>