access.5.html revision 1.1.1.1
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> 7ACCESS(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> <<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 <> 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> 442