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</i> name specifies the first field of a 290 mail delivery agent definition in <a href="master.5.html">master.cf</a>; the 291 syntax of the next-hop <i>destination</i> is described in 292 the manual page of the corresponding delivery 293 agent. More information about external content 294 filters is in the Postfix <a href="FILTER_README.html">FILTER_README</a> file. 295 296 Note 1: do not use $<i>number</i> regular expression sub- 297 stitutions for <i>transport</i> or <i>destination</i> unless you 298 know that the information has a trusted origin. 299 300 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> 301 <b><a href="postconf.5.html#content_filter">tent_filter</a></b> setting, and affects all recipients of 302 the message. In the case that multiple <b>FILTER</b> 303 actions fire, only the last one is executed. 304 305 Note 3: the purpose of the FILTER command is to 306 override message routing. To override the recipi- 307 ent's <i>transport</i> but not the next-hop <i>destination</i>, 308 specify an empty filter <i>destination</i> (Postfix 2.7 309 and later), or specify a <i>transport:destination</i> that 310 delivers through a different Postfix instance 311 (Postfix 2.6 and earlier). Other options are using 312 the recipient-dependent <b><a href="postconf.5.html#transport_maps">transport_maps</a></b> or the sen- 313 der-dependent <b><a href="postconf.5.html#sender_dependent_default_transport_maps">sender_dependent_default_transport</a>-</b> 314 <b><a href="postconf.5.html#sender_dependent_default_transport_maps">_maps</a></b> features. 315 316 This feature is available in Postfix 2.0 and later. 317 318 <b>HOLD</b> <i>optional text...</i> 319 Place the message on the <b>hold</b> queue, where it will 320 sit until someone either deletes it or releases it 321 for delivery. Log the optional text if specified, 322 otherwise log a generic message. 323 324 Mail that is placed on hold can be examined with 325 the <a href="postcat.1.html"><b>postcat</b>(1)</a> command, and can be destroyed or 326 released with the <a href="postsuper.1.html"><b>postsuper</b>(1)</a> command. 327 328 Note: use "<b>postsuper -r</b>" to release mail that was 329 kept on hold for a significant fraction of <b>$<a href="postconf.5.html#maximal_queue_lifetime">maxi</a>-</b> 330 <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 331 longer. Use "<b>postsuper -H</b>" only for mail that will 332 not expire within a few delivery attempts. 333 334 Note: this action currently affects all recipients 335 of the message. 336 337 This feature is available in Postfix 2.0 and later. 338 339 <b>PREPEND</b> <i>headername: headervalue</i> 340 Prepend the specified message header to the mes- 341 sage. When more than one PREPEND action executes, 342 the first prepended header appears before the sec- 343 ond etc. prepended header. 344 345 Note: this action must execute before the message 346 content is received; it cannot execute in the con- 347 text of <b><a href="postconf.5.html#smtpd_end_of_data_restrictions">smtpd_end_of_data_restrictions</a></b>. 348 349 This feature is available in Postfix 2.1 and later. 350 351 <b>REDIRECT</b> <i>user@domain</i> 352 After the message is queued, send the message to 353 the specified address instead of the intended 354 recipient(s). 355 356 Note: this action overrides the FILTER action, and 357 currently affects all recipients of the message. 358 359 This feature is available in Postfix 2.1 and later. 360 361 <b>WARN</b> <i>optional text...</i> 362 Log a warning with the optional text, together with 363 client information and if available, with helo, 364 sender, recipient and protocol information. 365 366 This feature is available in Postfix 2.1 and later. 367 368<b>ENHANCED STATUS CODES</b> 369 Postfix version 2.3 and later support enhanced status 370 codes as defined in <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>. When an enhanced status 371 code is specified in an access table, it is subject to 372 modification. The following transformations are needed 373 when the same access table is used for client, helo, 374 sender, or recipient access restrictions; they happen 375 regardless of whether Postfix replies to a MAIL FROM, RCPT 376 TO or other SMTP command. 377 378 <b>o</b> When a sender address matches a REJECT action, the 379 Postfix SMTP server will transform a recipient DSN 380 status (e.g., 4.1.1-4.1.6) into the corresponding 381 sender DSN status, and vice versa. 382 383 <b>o</b> When non-address information matches a REJECT 384 action (such as the HELO command argument or the 385 client hostname/address), the Postfix SMTP server 386 will transform a sender or recipient DSN status 387 into a generic non-address DSN status (e.g., 388 4.0.0). 389 390<b>REGULAR EXPRESSION TABLES</b> 391 This section describes how the table lookups change when 392 the table is given in the form of regular expressions. For 393 a description of regular expression lookup table syntax, 394 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>. 395 396 Each pattern is a regular expression that is applied to 397 the entire string being looked up. Depending on the appli- 398 cation, that string is an entire client hostname, an 399 entire client IP address, or an entire mail address. Thus, 400 no parent domain or parent network search is done, 401 <i>user@domain</i> mail addresses are not broken up into their 402 <i>user@</i> and <i>domain</i> constituent parts, nor is <i>user+foo</i> broken 403 up into <i>user</i> and <i>foo</i>. 404 405 Patterns are applied in the order as specified in the ta- 406 ble, until a pattern is found that matches the search 407 string. 408 409 Actions are the same as with indexed file lookups, with 410 the additional feature that parenthesized substrings from 411 the pattern can be interpolated as <b>$1</b>, <b>$2</b> and so on. 412 413<b>TCP-BASED TABLES</b> 414 This section describes how the table lookups change when 415 lookups are directed to a TCP-based server. For a descrip- 416 tion of the TCP client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_ta-</b></a> 417 <a href="tcp_table.5.html"><b>ble</b>(5)</a>. This feature is not available up to and including 418 Postfix version 2.4. 419 420 Each lookup operation uses the entire query string once. 421 Depending on the application, that string is an entire 422 client hostname, an entire client IP address, or an entire 423 mail address. Thus, no parent domain or parent network 424 search is done, <i>user@domain</i> mail addresses are not broken 425 up into their <i>user@</i> and <i>domain</i> constituent parts, nor is 426 <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>. 427 428 Actions are the same as with indexed file lookups. 429 430<b>EXAMPLE</b> 431 The following example uses an indexed file, so that the 432 order of table entries does not matter. The example per- 433 mits access by the client at address 1.2.3.4 but rejects 434 all other clients in 1.2.3.0/24. Instead of <b>hash</b> lookup 435 tables, some systems use <b>dbm</b>. Use the command "<b>postconf</b> 436 <b>-m</b>" to find out what lookup tables Postfix supports on 437 your system. 438 439 /etc/postfix/<a href="postconf.5.html">main.cf</a>: 440 <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> = 441 <a href="postconf.5.html#check_client_access">check_client_access</a> hash:/etc/postfix/access 442 443 /etc/postfix/access: 444 1.2.3 REJECT 445 1.2.3.4 OK 446 447 Execute the command "<b>postmap /etc/postfix/access</b>" after 448 editing the file. 449 450<b>BUGS</b> 451 The table format does not understand quoting conventions. 452 453<b>SEE ALSO</b> 454 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 455 <a href="smtpd.8.html">smtpd(8)</a>, SMTP server 456 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 457 <a href="transport.5.html">transport(5)</a>, transport:nexthop syntax 458 459<b>README FILES</b> 460 <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a>, built-in SMTP server access control 461 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 462 463<b>LICENSE</b> 464 The Secure Mailer license must be distributed with this 465 software. 466 467<b>AUTHOR(S)</b> 468 Wietse Venema 469 IBM T.J. Watson Research 470 P.O. Box 704 471 Yorktown Heights, NY 10598, USA 472 473 ACCESS(5) 474</pre> </body> </html> 475