diff options
Diffstat (limited to 'html/access.5.html')
| -rw-r--r-- | html/access.5.html | 438 |
1 files changed, 438 insertions, 0 deletions
diff --git a/html/access.5.html b/html/access.5.html new file mode 100644 index 0000000..cfbec47 --- /dev/null +++ b/html/access.5.html @@ -0,0 +1,438 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<title> Postfix manual - access(5) </title> +</head> <body> <pre> +ACCESS(5) ACCESS(5) + +<b>NAME</b> + access - Postfix SMTP server access table + +<b>SYNOPSIS</b> + <b>postmap /etc/postfix/access</b> + + <b>postmap -q "</b><i>string</i><b>" /etc/postfix/access</b> + + <b>postmap -q - /etc/postfix/access</b> <<i>inputfile</i> + +<b>DESCRIPTION</b> + This document describes access control on remote SMTP client informa- + tion: host names, network addresses, and envelope sender or recipient + addresses; it is implemented by the Postfix SMTP server. See + <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 + email messages. + + Normally, the <a href="access.5.html"><b>access</b>(5)</a> table is specified as a text file that serves + as input to the <a href="postmap.1.html"><b>postmap</b>(1)</a> command. The result, an indexed file in <b>dbm</b> + or <b>db</b> format, is used for fast searching by the mail system. Execute + the command "<b>postmap /etc/postfix/access</b>" to rebuild an indexed file + after changing the corresponding text file. + + When the table is provided via other means such as NIS, LDAP or SQL, + the same lookups are done as for ordinary indexed files. + + Alternatively, the table can be provided as a regular-expression map + where patterns are given as regular expressions, or lookups can be + directed to a TCP-based server. In those cases, the lookups are done in + a slightly different way as described below under "REGULAR EXPRESSION + TABLES" or "TCP-BASED TABLES". + +<b>CASE FOLDING</b> + The search string is folded to lowercase before database lookup. As of + Postfix 2.3, the search string is not case folded with database types + 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 + lower case. + +<b>TABLE FORMAT</b> + The input format for the <a href="postmap.1.html"><b>postmap</b>(1)</a> command is as follows: + + <i>pattern action</i> + When <i>pattern</i> matches a mail address, domain or host address, + perform the corresponding <i>action</i>. + + blank lines and comments + Empty lines and whitespace-only lines are ignored, as are lines + whose first non-whitespace character is a `#'. + + multi-line text + A logical line starts with non-whitespace text. A line that + starts with whitespace continues a logical line. + +<b>EMAIL ADDRESS PATTERNS</b> + With lookups from indexed files such as DB or DBM, or from networked + tables such as NIS, LDAP or SQL, patterns are tried in the order as + listed below: + + <i>user</i>@<i>domain</i> + Matches the specified mail address. + + <i>domain.tld</i> + Matches <i>domain.tld</i> as the domain part of an email address. + + The pattern <i>domain.tld</i> also matches subdomains, but only when + 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> + <b><a href="postconf.5.html#parent_domain_matches_subdomains">ent_domain_matches_subdomains</a></b> configuration setting. + + <i>.domain.tld</i> + Matches subdomains of <i>domain.tld</i>, but only when the string + <b>smtpd_access_maps</b> is not listed in the Postfix <b><a href="postconf.5.html#parent_domain_matches_subdomains">par</a>-</b> + <b><a href="postconf.5.html#parent_domain_matches_subdomains">ent_domain_matches_subdomains</a></b> configuration setting. + + <i>user</i>@ Matches all mail addresses with the specified user part. + + Note: lookup of the null sender address is not possible with some types + of lookup table. By default, Postfix uses <> as the lookup key for such + 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> + parameter in the Postfix <a href="postconf.5.html"><b>main.cf</b></a> file. + +<b>EMAIL ADDRESS EXTENSION</b> + When a mail address localpart contains the optional recipient delimiter + (e.g., <i>user+foo</i>@<i>domain</i>), the lookup order becomes: <i>user+foo</i>@<i>domain</i>, + <i>user</i>@<i>domain</i>, <i>domain</i>, <i>user+foo</i>@, and <i>user</i>@. + +<b>HOST NAME/ADDRESS PATTERNS</b> + With lookups from indexed files such as DB or DBM, or from networked + tables such as NIS, LDAP or SQL, the following lookup patterns are + examined in the order as listed: + + <i>domain.tld</i> + Matches <i>domain.tld</i>. + + The pattern <i>domain.tld</i> also matches subdomains, but only when + 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> + <b><a href="postconf.5.html#parent_domain_matches_subdomains">ent_domain_matches_subdomains</a></b> configuration setting. + + <i>.domain.tld</i> + Matches subdomains of <i>domain.tld</i>, but only when the string + <b>smtpd_access_maps</b> is not listed in the Postfix <b><a href="postconf.5.html#parent_domain_matches_subdomains">par</a>-</b> + <b><a href="postconf.5.html#parent_domain_matches_subdomains">ent_domain_matches_subdomains</a></b> configuration setting. + + <i>net.work.addr.ess</i> + + <i>net.work.addr</i> + + <i>net.work</i> + + <i>net</i> Matches a remote IPv4 host address or network address range. + Specify one to four decimal octets separated by ".". Do not + specify "[]" , "/", leading zeros, or hexadecimal forms. + + Network ranges are matched by repeatedly truncating the last + ".octet" from a remote IPv4 host address string, until a match + is found in the access table, or until further truncation is not + possible. + + NOTE: use the <b>cidr</b> lookup table type to specify network/netmask + patterns. See <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a> for details. + + <i>net:work:addr:ess</i> + + <i>net:work:addr</i> + + <i>net:work</i> + + <i>net</i> Matches a remote IPv6 host address or network address range. + Specify three to eight hexadecimal octet pairs separated by ":", + using the compressed form "::" for a sequence of zero-valued + octet pairs. Do not specify "[]", "/", leading zeros, or + non-compressed forms. + + A network range is matched by repeatedly truncating the last + ":octetpair" from the compressed-form remote IPv6 host address + string, until a match is found in the access table, or until + further truncation is not possible. + + NOTE: use the <b>cidr</b> lookup table type to specify network/netmask + patterns. See <a href="cidr_table.5.html"><b>cidr_table</b>(5)</a> for details. + + IPv6 support is available in Postfix 2.2 and later. + +<b>ACCEPT ACTIONS</b> + <b>OK</b> Accept the address etc. that matches the pattern. + + <i>all-numerical</i> + An all-numerical result is treated as OK. This format is gener- + ated by address-based relay authorization schemes such as + pop-before-smtp. + + For other accept actions, see "OTHER ACTIONS" below. + +<b>REJECT ACTIONS</b> + Postfix version 2.3 and later support enhanced status codes as defined + 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> + below, Postfix inserts a default enhanced status code of "5.7.1" in the + case of reject actions, and "4.7.1" in the case of defer actions. See + "ENHANCED STATUS CODES" below. + + <b>4</b><i>NN text</i> + + <b>5</b><i>NN text</i> + Reject the address etc. that matches the pattern, and respond + with the numerical three-digit code and text. <b>4</b><i>NN</i> means "try + again later", while <b>5</b><i>NN</i> means "do not try again". + + The following responses have special meaning for the Postfix + SMTP server: + + <b>421</b> <i>text</i> (Postfix 2.3 and later) + + <b>521</b> <i>text</i> (Postfix 2.6 and later) + After responding with the numerical three-digit code and + text, disconnect immediately from the SMTP client. This + frees up SMTP server resources so that they can be made + available to another SMTP client. + + Note: The "521" response should be used only with botnets + and other malware where interoperability is of no con- + cern. The "send 521 and disconnect" behavior is NOT + defined in the SMTP standard. + + <b>REJECT</b> <i>optional text...</i> + Reject the address etc. that matches the pattern. Reply with + "<b>$<a href="postconf.5.html#access_map_reject_code">access_map_reject_code</a></b> <i>optional text...</i>" when the optional + text is specified, otherwise reply with a generic error response + message. + + <b>DEFER</b> <i>optional text...</i> + Reject the address etc. that matches the pattern. Reply with + "<b>$<a href="postconf.5.html#access_map_defer_code">access_map_defer_code</a></b> <i>optional text...</i>" when the optional text + is specified, otherwise reply with a generic error response mes- + sage. + + This feature is available in Postfix 2.6 and later. + + <b>DEFER_IF_REJECT</b> <i>optional text...</i> + Defer the request if some later restriction would result in a + 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> + <i>text...</i>" when the optional text is specified, otherwise reply + with a generic error response message. + + Prior to Postfix 2.6, the SMTP reply code is 450. + + This feature is available in Postfix 2.1 and later. + + <b>DEFER_IF_PERMIT</b> <i>optional text...</i> + Defer the request if some later restriction would result in an + explicit or implicit PERMIT action. Reply with + "<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 + optional text is specified, otherwise reply with a generic error + response message. + + Prior to Postfix 2.6, the SMTP reply code is 450. + + This feature is available in Postfix 2.1 and later. + + For other reject actions, see "OTHER ACTIONS" below. + +<b>OTHER ACTIONS</b> + <i>restriction...</i> + Apply the named UCE restriction(s) (<b>permit</b>, <b>reject</b>, + <b><a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a></b>, and so on). + + <b>BCC</b> <i>user@domain</i> + Send one copy of the message to the specified recipient. + + If multiple BCC actions are specified within the same SMTP MAIL + transaction, with Postfix 3.0 only the last action will be used. + + This feature is available in Postfix 3.0 and later. + + <b>DISCARD</b> <i>optional text...</i> + Claim successful delivery and silently discard the message. Log + the optional text if specified, otherwise log a generic message. + + Note: this action currently affects all recipients of the mes- + sage. To discard only one recipient without discarding the + entire message, use the <a href="transport.5.html">transport(5)</a> table to direct mail to the + <a href="discard.8.html">discard(8)</a> service. + + This feature is available in Postfix 2.0 and later. + + <b>DUNNO</b> Pretend that the lookup key was not found. This prevents Postfix + from trying substrings of the lookup key (such as a subdomain + name, or a network address subnetwork). + + This feature is available in Postfix 2.0 and later. + + <b>FILTER</b> <i>transport:destination</i> + After the message is queued, send the entire message through the + specified external content filter. The <i>transport</i> name specifies + the first field of a mail delivery agent definition in <a href="master.5.html">mas- + ter.cf</a>; the syntax of the next-hop <i>destination</i> is described in + the manual page of the corresponding delivery agent. More + information about external content filters is in the Postfix + <a href="FILTER_README.html">FILTER_README</a> file. + + Note 1: do not use $<i>number</i> regular expression substitutions for + <i>transport</i> or <i>destination</i> unless you know that the information + has a trusted origin. + + 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- + ting, and affects all recipients of the message. In the case + that multiple <b>FILTER</b> actions fire, only the last one is exe- + cuted. + + Note 3: the purpose of the FILTER command is to override message + routing. To override the recipient's <i>transport</i> but not the + next-hop <i>destination</i>, specify an empty filter <i>destination</i> (Post- + fix 2.7 and later), or specify a <i>transport:destination</i> that + delivers through a different Postfix instance (Postfix 2.6 and + earlier). Other options are using the recipient-dependent <b><a href="postconf.5.html#transport_maps">trans</a>-</b> + <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> + <b>_transport_maps</a></b> features. + + This feature is available in Postfix 2.0 and later. + + <b>HOLD</b> <i>optional text...</i> + Place the message on the <b>hold</b> queue, where it will sit until + someone either deletes it or releases it for delivery. Log the + optional text if specified, otherwise log a generic message. + + Mail that is placed on hold can be examined with the <a href="postcat.1.html"><b>postcat</b>(1)</a> + command, and can be destroyed or released with the <a href="postsuper.1.html"><b>postsuper</b>(1)</a> + command. + + Note: use "<b>postsuper -r</b>" to release mail that was kept on hold + for a significant fraction of <b>$<a href="postconf.5.html#maximal_queue_lifetime">maximal_queue_lifetime</a></b> or + <b>$<a href="postconf.5.html#bounce_queue_lifetime">bounce_queue_lifetime</a></b>, or longer. Use "<b>postsuper -H</b>" only for + mail that will not expire within a few delivery attempts. + + Note: this action currently affects all recipients of the mes- + sage. + + This feature is available in Postfix 2.0 and later. + + <b>PREPEND</b> <i>headername: headervalue</i> + Prepend the specified message header to the message. When more + than one PREPEND action executes, the first prepended header + appears before the second etc. prepended header. + + Note: this action must execute before the message content is + received; it cannot execute in the context of + <b><a href="postconf.5.html#smtpd_end_of_data_restrictions">smtpd_end_of_data_restrictions</a></b>. + + This feature is available in Postfix 2.1 and later. + + <b>REDIRECT</b> <i>user@domain</i> + After the message is queued, send the message to the specified + address instead of the intended recipient(s). When multiple <b>RE-</b> + <b>DIRECT</b> actions fire, only the last one takes effect. + + Note: this action overrides the FILTER action, and currently + overrides all recipients of the message. + + This feature is available in Postfix 2.1 and later. + + <b>INFO</b> <i>optional text...</i> + Log an informational record with the optional text, together + with client information and if available, with helo, sender, + recipient and protocol information. + + This feature is available in Postfix 3.0 and later. + + <b>WARN</b> <i>optional text...</i> + Log a warning with the optional text, together with client + information and if available, with helo, sender, recipient and + protocol information. + + This feature is available in Postfix 2.1 and later. + +<b>ENHANCED STATUS CODES</b> + Postfix version 2.3 and later support enhanced status codes as defined + in <a href="https://tools.ietf.org/html/rfc3463">RFC 3463</a>. When an enhanced status code is specified in an access + table, it is subject to modification. The following transformations are + needed when the same access table is used for client, helo, sender, or + recipient access restrictions; they happen regardless of whether Post- + fix replies to a MAIL FROM, RCPT TO or other SMTP command. + + <b>o</b> When a sender address matches a REJECT action, the Postfix SMTP + server will transform a recipient DSN status (e.g., 4.1.1-4.1.6) + into the corresponding sender DSN status, and vice versa. + + <b>o</b> When non-address information matches a REJECT action (such as + the HELO command argument or the client hostname/address), the + Postfix SMTP server will transform a sender or recipient DSN + status into a generic non-address DSN status (e.g., 4.0.0). + +<b>REGULAR EXPRESSION TABLES</b> + This section describes how the table lookups change when the table is + given in the form of regular expressions. For a description of regular + 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>. + + Each pattern is a regular expression that is applied to the entire + string being looked up. Depending on the application, that string is an + entire client hostname, an entire client IP address, or an entire mail + address. Thus, no parent domain or parent network search is done, + <i>user@domain</i> mail addresses are not broken up into their <i>user@</i> and + <i>domain</i> constituent parts, nor is <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>. + + Patterns are applied in the order as specified in the table, until a + pattern is found that matches the search string. + + Actions are the same as with indexed file lookups, with the additional + feature that parenthesized substrings from the pattern can be interpo- + lated as <b>$1</b>, <b>$2</b> and so on. + +<b>TCP-BASED TABLES</b> + This section describes how the table lookups change when lookups are + directed to a TCP-based server. For a description of the TCP + client/server lookup protocol, see <a href="tcp_table.5.html"><b>tcp_table</b>(5)</a>. This feature is not + available up to and including Postfix version 2.4. + + Each lookup operation uses the entire query string once. Depending on + the application, that string is an entire client hostname, an entire + client IP address, or an entire mail address. Thus, no parent domain + or parent network search is done, <i>user@domain</i> mail addresses are not + broken up into their <i>user@</i> and <i>domain</i> constituent parts, nor is + <i>user+foo</i> broken up into <i>user</i> and <i>foo</i>. + + Actions are the same as with indexed file lookups. + +<b>EXAMPLE</b> + The following example uses an indexed file, so that the order of table + entries does not matter. The example permits access by the client at + address 1.2.3.4 but rejects all other clients in 1.2.3.0/24. Instead of + <b>hash</b> lookup tables, some systems use <b>dbm</b>. Use the command "<b>postconf</b> + <b>-m</b>" to find out what lookup tables Postfix supports on your system. + + /etc/postfix/<a href="postconf.5.html">main.cf</a>: + <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> = + <a href="postconf.5.html#check_client_access">check_client_access</a> <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/access + + /etc/postfix/access: + 1.2.3 REJECT + 1.2.3.4 OK + + Execute the command "<b>postmap /etc/postfix/access</b>" after editing the + file. + +<b>BUGS</b> + The table format does not understand quoting conventions. + +<b>SEE ALSO</b> + <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager + <a href="smtpd.8.html">smtpd(8)</a>, SMTP server + <a href="postconf.5.html">postconf(5)</a>, configuration parameters + <a href="transport.5.html">transport(5)</a>, transport:nexthop syntax + +<b>README FILES</b> + <a href="SMTPD_ACCESS_README.html">SMTPD_ACCESS_README</a>, built-in SMTP server access control + <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview + +<b>LICENSE</b> + The Secure Mailer license must be distributed with this software. + +<b>AUTHOR(S)</b> + Wietse Venema + IBM T.J. Watson Research + P.O. Box 704 + Yorktown Heights, NY 10598, USA + + Wietse Venema + Google, Inc. + 111 8th Avenue + New York, NY 10011, USA + + ACCESS(5) +</pre> </body> </html> |