443 lines
24 KiB
HTML
443 lines
24 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
<html> <head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
<title> Postfix manual - access(5) </title>
|
|
</head> <body> <pre>
|
|
ACCESS(5) ACCESS(5)
|
|
|
|
<b><a name="name">NAME</a></b>
|
|
access - Postfix SMTP server access table
|
|
|
|
<b><a name="synopsis">SYNOPSIS</a></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><a name="description">DESCRIPTION</a></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><a name="case_folding">CASE FOLDING</a></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><a name="table_format">TABLE FORMAT</a></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><a name="email_address_patterns_in_indexed_tables">EMAIL ADDRESS PATTERNS IN INDEXED TABLES</a></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><a name="email_address_extension">EMAIL ADDRESS EXTENSION</a></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 IN INDEXED TABLES</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><a name="accept_actions">ACCEPT ACTIONS</a></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><a name="reject_actions">REJECT ACTIONS</a></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><a name="other_actions">OTHER ACTIONS</a></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 1: this action overrides the FILTER action, and currently
|
|
overrides all recipients of the message.
|
|
|
|
Note 2: a REDIRECT address is subject to canonicalization (add
|
|
missing domain) but NOT subject to canonical, masquerade, bcc,
|
|
or virtual alias mapping.
|
|
|
|
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><a name="enhanced_status_codes">ENHANCED STATUS CODES</a></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><a name="regular_expression_tables">REGULAR EXPRESSION TABLES</a></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><a name="tcp-based_tables">TCP-BASED TABLES</a></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><a name="example">EXAMPLE</a></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><a name="bugs">BUGS</a></b>
|
|
The table format does not understand quoting conventions.
|
|
|
|
<b><a name="see_also">SEE ALSO</a></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><a name="readme_files">README FILES</a></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><a name="license">LICENSE</a></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>
|