1ACCESS(5)                     File Formats Manual                    ACCESS(5)
2
3
4

NAME

6       access - Postfix SMTP server access table
7

SYNOPSIS

9       postmap /etc/postfix/access
10
11       postmap -q "string" /etc/postfix/access
12
13       postmap -q - /etc/postfix/access <inputfile
14

DESCRIPTION

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
22       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
28       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
31       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

CASE FOLDING

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

TABLE FORMAT

44       The input format for the postmap(1) command is as follows:
45
46       pattern action
47              When  pattern  matches  a  mail address, domain or host address,
48              perform the corresponding action.
49
50       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
54       multi-line text
55              A  logical  line  starts  with  non-whitespace text. A line that
56              starts with whitespace continues a logical line.
57

EMAIL ADDRESS PATTERNS

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
63       user@domain
64              Matches the specified mail address.
65
66       domain.tld
67              Matches domain.tld as the domain part of an email address.
68
69              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
73       .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
78       user@  Matches all mail addresses with the specified user part.
79
80       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

EMAIL ADDRESS EXTENSION

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

HOST NAME/ADDRESS PATTERNS

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
95       domain.tld
96              Matches domain.tld.
97
98              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
102       .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
107       net.work.addr.ess
108
109       net.work.addr
110
111       net.work
112
113       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
117              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
122              NOTE: use the cidr lookup table type to specify  network/netmask
123              patterns. See cidr_table(5) for details.
124
125       net:work:addr:ess
126
127       net:work:addr
128
129       net:work
130
131       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
137              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
142              NOTE: use the cidr lookup table type to specify  network/netmask
143              patterns. See cidr_table(5) for details.
144
145              IPv6 support is available in Postfix 2.2 and later.
146

ACCEPT ACTIONS

148       OK     Accept the address etc. that matches the pattern.
149
150       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
155       For other accept actions, see "OTHER ACTIONS" below.
156

REJECT ACTIONS

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
164       4NN text
165
166       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
171              The  following  responses  have  special meaning for the Postfix
172              SMTP server:
173
174              421 text (Postfix 2.3 and later)
175
176              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
182                     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
187       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
193       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
199              This feature is available in Postfix 2.6 and later.
200
201       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
207              Prior to Postfix 2.6, the SMTP reply code is 450.
208
209              This feature is available in Postfix 2.1 and later.
210
211       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
218              Prior to Postfix 2.6, the SMTP reply code is 450.
219
220              This feature is available in Postfix 2.1 and later.
221
222       For other reject actions, see "OTHER ACTIONS" below.
223

OTHER ACTIONS

225       restriction...
226              Apply   the   named  UCE  restriction(s)  (permit,  reject,  re‐
227              ject_unauth_destination, and so on).
228
229       BCC user@domain
230              Send one copy of the message to the specified recipient.
231
232              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
235              This feature is available in Postfix 3.0 and later.
236
237       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
241              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
246              This feature is available in Postfix 2.0 and later.
247
248       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
252              This feature is available in Postfix 2.0 and later.
253
254       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
263              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
267              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
272              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
281              This feature is available in Postfix 2.0 and later.
282
283       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
288              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
292              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
297              Note: this action currently affects all recipients of  the  mes‐
298              sage.
299
300              This feature is available in Postfix 2.0 and later.
301
302       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
307              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
311              This feature is available in Postfix 2.1 and later.
312
313       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
318              Note:  this  action  overrides  the FILTER action, and currently
319              overrides all recipients of the message.
320
321              This feature is available in Postfix 2.1 and later.
322
323       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
328              This feature is available in Postfix 3.0 and later.
329
330       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
335              This feature is available in Postfix 2.1 and later.
336

ENHANCED STATUS CODES

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
345       •      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
349       •      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

REGULAR EXPRESSION TABLES

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
359       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
366       Patterns  are  applied  in the order as specified in the table, until a
367       pattern is found that matches the search string.
368
369       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

TCP-BASED TABLES

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
379       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
386       Actions are the same as with indexed file lookups.
387

EXAMPLE

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
395       /etc/postfix/main.cf:
396           smtpd_client_restrictions =
397               check_client_access hash:/etc/postfix/access
398
399       /etc/postfix/access:
400           1.2.3   REJECT
401           1.2.3.4 OK
402
403       Execute the command "postmap  /etc/postfix/access"  after  editing  the
404       file.
405

BUGS

407       The table format does not understand quoting conventions.
408

SEE ALSO

410       postmap(1), Postfix lookup table manager
411       smtpd(8), SMTP server
412       postconf(5), configuration parameters
413       transport(5), transport:nexthop syntax
414

README FILES

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

LICENSE

422       The Secure Mailer license must be distributed with this software.
423

AUTHOR(S)

425       Wietse Venema
426       IBM T.J. Watson Research
427       P.O. Box 704
428       Yorktown Heights, NY 10598, USA
429
430       Wietse Venema
431       Google, Inc.
432       111 8th Avenue
433       New York, NY 10011, USA
434
435
436
437                                                                     ACCESS(5)
Impressum