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