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