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