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. 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 <> 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> 482