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 following responses have special meaning for 197 the Postfix SMTP server: 198 199 <b>421</b> <i>text</i> (Postfix 2.3 and later) 200 201 <b>521</b> <i>text</i> (Postfix 2.6 and later) 202 After responding with the numerical three- 203 digit code and text, disconnect immediately 204 from the SMTP client. This frees up SMTP 205 server resources so that they can be made 206 available to another SMTP client. 207 208 Note: The "521" response should be used only 209 with botnets and other malware where inter- 210 operability is of no concern. The "send 521 211 and disconnect" behavior is NOT defined in 212 the SMTP standard. 213 214 <b>REJECT</b> <i>optional text...</i> 215 Reject the address etc. that matches the pattern. 216 Reply with "<b>$<a href="postconf.5.html#access_map_reject_code">access_map_reject_code</a></b> <i>optional</i> 217 <i>text...</i>" when the optional text is specified, oth- 218 erwise reply with a generic error response message. 219 220 <b>DEFER</b> <i>optional text...</i> 221 Reject the address etc. that matches the pattern. 222 Reply with "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a></b> <i>optional</i> 223 <i>text...</i>" when the optional text is specified, oth- 224 erwise reply with a generic error response message. 225 226 This feature is available in Postfix 2.6 and later. 227 228 <b>DEFER_IF_REJECT</b> <i>optional text...</i> 229 Defer the request if some later restriction would 230 result in a REJECT action. Reply with 231 "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a> 4.7.1</b> <i>optional text...</i>" 232 when the optional text is specified, otherwise 233 reply with a generic error response message. 234 235 Prior to Postfix 2.6, the SMTP reply code is 450. 236 237 This feature is available in Postfix 2.1 and later. 238 239 <b>DEFER_IF_PERMIT</b> <i>optional text...</i> 240 Defer the request if some later restriction would 241 result in a an explicit or implicit PERMIT action. 242 Reply with "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a> 4.7.1</b> <i>optional</i> 243 <i>text...</i>" when the optional text is specified, oth- 244 erwise reply with a generic error response message. 245 246 Prior to Postfix 2.6, the SMTP reply code is 450. 247 248 This feature is available in Postfix 2.1 and later. 249 250<b>OTHER ACTIONS</b> 251 <i>restriction...</i> 252 Apply the named UCE restriction(s) (<b>permit</b>, <b>reject</b>, 253 <b><a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a></b>, and so on). 254 255 <b>BCC</b> <i>user@domain</i> 256 Send one copy of the message to the specified 257 recipient. 258 259 If multiple BCC actions are specified within the 260 same SMTP MAIL transaction, only the last action 261 will be used. 262 263 This feature is not part of the stable Postfix 264 release. 265 266 <b>DISCARD</b> <i>optional text...</i> 267 Claim successful delivery and silently discard the 268 message. Log the optional text if specified, oth- 269 erwise log a generic message. 270 271 Note: this action currently affects all recipients 272 of the message. To discard only one recipient 273 without discarding the entire message, use the 274 <a href="transport.5.html">transport(5)</a> table to direct mail to the <a href="discard.8.html">discard(8)</a> 275 service. 276 277 This feature is available in Postfix 2.0 and later. 278 279 <b>DUNNO</b> Pretend that the lookup key was not found. This 280 prevents Postfix from trying substrings of the 281 lookup key (such as a subdomain name, or a network 282 address subnetwork). 283 284 This feature is available in Postfix 2.0 and later. 285 286 <b>FILTER</b> <i>transport:destination</i> 287 After the message is queued, send the entire mes- 288 sage through the specified external content filter. 289 The <i>transport:destination</i> syntax is described in 290 the <a href="transport.5.html"><b>transport</b>(5)</a> manual page. More information 291 about external content filters is in the Postfix 292 <a href="FILTER_README.html">FILTER_README</a> file. 293 294 Note: this action overrides the <b><a href="postconf.5.html#content_filter">content_filter</a></b> set- 295 ting, and currently affects all recipients of the 296 message. 297 298 This feature is available in Postfix 2.0 and later. 299 300 <b>HOLD</b> <i>optional text...</i> 301 Place the message on the <b>hold</b> queue, where it will 302 sit until someone either deletes it or releases it 303 for delivery. Log the optional text if specified, 304 otherwise log a generic message. 305 306 Mail that is placed on hold can be examined with 307 the <a href="postcat.1.html"><b>postcat</b>(1)</a> command, and can be destroyed or 308 released with the <a href="postsuper.1.html"><b>postsuper</b>(1)</a> command. 309 310 Note: use "<b>postsuper -r</b>" to release mail that was 311 kept on hold for a significant fraction of <b>$<a href="postconf.5.html#maximal_queue_lifetime">maxi</a>-</b> 312 <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 313 longer. Use "<b>postsuper -H</b>" only for mail that will 314 not expire within a few delivery attempts. 315 316 Note: this action currently affects all recipients 317 of the message. 318 319 This feature is available in Postfix 2.0 and later. 320 321 <b>PREPEND</b> <i>headername: headervalue</i> 322 Prepend the specified message header to the mes- 323 sage. When more than one PREPEND action executes, 324 the first prepended header appears before the sec- 325 ond etc. prepended header. 326 327 Note: this action must execute before the message 328 content is received; it cannot execute in the con- 329 text of <b><a href="postconf.5.html#smtpd_end_of_data_restrictions">smtpd_end_of_data_restrictions</a></b>. 330 331 This feature is available in Postfix 2.1 and later. 332 333 <b>REDIRECT</b> <i>user@domain</i> 334 After the message is queued, send the message to 335 the specified address instead of the intended 336 recipient(s). 337 338 Note: this action overrides the FILTER action, and 339 currently affects all recipients of the message. 340 341 This feature is available in Postfix 2.1 and later. 342 343 <b>WARN</b> <i>optional text...</i> 344 Log a warning with the optional text, together with 345 client information and if available, with helo, 346 sender, recipient and protocol information. 347 348 This feature is available in Postfix 2.1 and later. 349 350<b>ENHANCED STATUS CODES</b> 351 Postfix version 2.3 and later support enhanced status 352 codes as defined in <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>. When an enhanced status 353 code is specified in an access table, it is subject to 354 modification. The following transformations are needed 355 when the same access table is used for client, helo, 356 sender, or recipient access restrictions; they happen 357 regardless of whether Postfix replies to a MAIL FROM, RCPT 358 TO or other SMTP command. 359 360 <b>o</b> When a sender address matches a REJECT action, the 361 Postfix SMTP server will transform a recipient DSN 362 status (e.g., 4.1.1-4.1.6) into the corresponding 363 sender DSN status, and vice versa. 364 365 <b>o</b> When non-address information matches a REJECT 366 action (such as the HELO command argument or the 367 client hostname/address), the Postfix SMTP server 368 will transform a sender or recipient DSN status 369 into a generic non-address DSN status (e.g., 370 4.0.0). 371 372<b>REGULAR EXPRESSION TABLES</b> 373 This section describes how the table lookups change when 374 the table is given in the form of regular expressions. For 375 a description of regular expression lookup table syntax, 376 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>. 377 378 Each pattern is a regular expression that is applied to 379 the entire string being looked up. Depending on the appli- 380 cation, that string is an entire client hostname, an 381 entire client IP address, or an entire mail address. Thus, 382 no parent domain or parent network search is done, 383 <i>user@domain</i> mail addresses are not broken up into their 384 <i>user@</i> and <i>domain</i> constituent parts, nor is <i>user+foo</i> broken 385 up into <i>user</i> and <i>foo</i>. 386 387 Patterns are applied in the order as specified in the ta- 388 ble, until a pattern is found that matches the search 389 string. 390 391 Actions are the same as with indexed file lookups, with 392 the additional feature that parenthesized substrings from 393 the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on. 394 395<b>TCP-BASED TABLES</b> 396 This section describes how the table lookups change when 397 lookups are directed to a TCP-based server. For a descrip- 398 tion of the TCP client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_ta-</b></a> 399 <a href="tcp_table.5.html"><b>ble</b>(5)</a>. This feature is not available up to and including 400 Postfix version 2.4. 401 402 Each lookup operation uses the entire query string once. 403 Depending on the application, that string is an entire 404 client hostname, an entire client IP address, or an entire 405 mail address. Thus, no parent domain or parent network 406 search is done, <i>user@domain</i> mail addresses are not broken 407 up into their <i>user@</i> and <i>domain</i> constituent parts, nor is 408 <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>. 409 410 Actions are the same as with indexed file lookups. 411 412<b>EXAMPLE</b> 413 The following example uses an indexed file, so that the 414 order of table entries does not matter. The example per- 415 mits access by the client at address 1.2.3.4 but rejects 416 all other clients in 1.2.3.0/24. Instead of <b>hash</b> lookup 417 tables, some systems use <b>dbm</b>. Use the command "<b>postconf</b> 418 <b>-m</b>" to find out what lookup tables Postfix supports on 419 your system. 420 421 /etc/postfix/<a href="postconf.5.html">main.cf</a>: 422 <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> = 423 <a href="postconf.5.html#check_client_access">check_client_access</a> hash:/etc/postfix/access 424 425 /etc/postfix/access: 426 1.2.3 REJECT 427 1.2.3.4 OK 428 429 Execute the command "<b>postmap /etc/postfix/access</b>" after 430 editing the file. 431 432<b>BUGS</b> 433 The table format does not understand quoting conventions. 434 435<b>SEE ALSO</b> 436 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 437 <a href="smtpd.8.html">smtpd(8)</a>, SMTP server 438 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 439 <a href="transport.5.html">transport(5)</a>, transport:nexthop syntax 440 441<b>README FILES</b> 442 <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a>, built-in SMTP server access control 443 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 444 445<b>LICENSE</b> 446 The Secure Mailer license must be distributed with this 447 software. 448 449<b>AUTHOR(S)</b> 450 Wietse Venema 451 IBM T.J. Watson Research 452 P.O. Box 704 453 Yorktown Heights, NY 10598, USA 454 455 ACCESS(5) 456</pre> </body> </html> 457