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