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