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
33       directed to TCP-based server. In those cases, the lookups are done in a
34       slightly  different  way  as  described below under "REGULAR EXPRESSION
35       TABLES" 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 par‐
71              ent_domain_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  par‐
76              ent_domain_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
93       examined 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  par‐
100              ent_domain_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   par‐
105              ent_domain_matches_subdomains configuration setting.
106
107       net.work.addr.ess
108
109       net.work.addr
110
111       net.work
112
113       net    Matches  the  specified IPv4 host address or subnetwork. An IPv4
114              host address is a sequence of four decimal octets  separated  by
115              ".".
116
117              Subnetworks  are  matched  by  repeatedly  truncating  the  last
118              ".octet" from the 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 1: The access map lookup key must be in canonical form:  do
123              not specify unnecessary null characters, and do not enclose net‐
124              work address information with "[]" characters.
125
126              NOTE 2: use the cidr lookup table type to  specify  network/net‐
127              mask patterns. See cidr_table(5) for details.
128
129       net:work:addr:ess
130
131       net:work:addr
132
133       net:work
134
135       net    Matches  the  specified IPv6 host address or subnetwork. An IPv6
136              host address is a sequence of three to eight  hexadecimal  octet
137              pairs separated by ":".
138
139              Subnetworks  are  matched  by  repeatedly  truncating  the  last
140              ":octetpair" from the remote IPv6 host address  string  until  a
141              match  is found in the access table, or until further truncation
142              is not possible.
143
144              NOTE 1: the truncation and comparison are done with  the  string
145              representation  of  the IPv6 host address. Thus, not all the ":"
146              subnetworks will be tried.
147
148              NOTE 2: The access map lookup key must be in canonical form:  do
149              not specify unnecessary null characters, and do not enclose net‐
150              work address information with "[]" characters.
151
152              NOTE 3: use the cidr lookup table type to  specify  network/net‐
153              mask patterns. See cidr_table(5) for details.
154
155              IPv6 support is available in Postfix 2.2 and later.
156

ACCEPT ACTIONS

158       OK     Accept the address etc. that matches the pattern.
159
160       all-numerical
161              An  all-numerical result is treated as OK. This format is gener‐
162              ated  by  address-based  relay  authorization  schemes  such  as
163              pop-before-smtp.
164
165       For other accept actions, see "OTHER ACTIONS" below.
166

REJECT ACTIONS

168       Postfix  version 2.3 and later support enhanced status codes as defined
169       in RFC 3463.  When no code is specified at the beginning  of  the  text
170       below, Postfix inserts a default enhanced status code of "5.7.1" in the
171       case of reject actions, and "4.7.1" in the case of defer  actions.  See
172       "ENHANCED STATUS CODES" below.
173
174       4NN text
175
176       5NN text
177              Reject  the  address  etc. that matches the pattern, and respond
178              with the numerical three-digit code and  text.  4NN  means  "try
179              again later", while 5NN means "do not try again".
180
181              The  following  responses  have  special meaning for the Postfix
182              SMTP server:
183
184              421 text (Postfix 2.3 and later)
185
186              521 text (Postfix 2.6 and later)
187                     After responding with the numerical three-digit code  and
188                     text,  disconnect immediately from the SMTP client.  This
189                     frees up SMTP server resources so that they can  be  made
190                     available to another SMTP client.
191
192                     Note: The "521" response should be used only with botnets
193                     and other malware where interoperability is  of  no  con‐
194                     cern.   The  "send  521  and  disconnect" behavior is NOT
195                     defined in the SMTP standard.
196
197       REJECT optional text...
198              Reject the address etc. that matches  the  pattern.  Reply  with
199              "$access_map_reject_code  optional  text..."  when  the optional
200              text is specified, otherwise reply with a generic error response
201              message.
202
203       DEFER optional text...
204              Reject  the  address  etc.  that matches the pattern. Reply with
205              "$access_map_defer_code optional text..." when the optional text
206              is specified, otherwise reply with a generic error response mes‐
207              sage.
208
209              This feature is available in Postfix 2.6 and later.
210
211       DEFER_IF_REJECT optional text...
212              Defer the request if some later restriction would  result  in  a
213              REJECT action. Reply with "$access_map_defer_code 4.7.1 optional
214              text..." when the optional text is  specified,  otherwise  reply
215              with a generic error response message.
216
217              Prior to Postfix 2.6, the SMTP reply code is 450.
218
219              This feature is available in Postfix 2.1 and later.
220
221       DEFER_IF_PERMIT optional text...
222              Defer the request if some later restriction would result in a an
223              explicit   or    implicit    PERMIT    action.     Reply    with
224              "$access_map_defer_code   4.7.1    optional  text..."  when  the
225              optional text is specified, otherwise reply with a generic error
226              response message.
227
228              Prior to Postfix 2.6, the SMTP reply code is 450.
229
230              This feature is available in Postfix 2.1 and later.
231
232       For other reject actions, see "OTHER ACTIONS" below.
233

OTHER ACTIONS

235       restriction...
236              Apply    the   named   UCE   restriction(s)   (permit,   reject,
237              reject_unauth_destination, and so on).
238
239       BCC user@domain
240              Send one copy of the message to the specified recipient.
241
242              If multiple BCC actions are specified within the same SMTP  MAIL
243              transaction, with Postfix 3.0 only the last action will be used.
244
245              This feature is available in Postfix 3.0 and later.
246
247       DISCARD optional text...
248              Claim successful delivery and silently discard the message.  Log
249              the optional text if specified, otherwise log a generic message.
250
251              Note: this action currently affects all recipients of  the  mes‐
252              sage.   To  discard  only  one  recipient without discarding the
253              entire message, use the transport(5) table to direct mail to the
254              discard(8) 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 prevents Postfix
259              from trying substrings of the lookup key (such  as  a  subdomain
260              name, or a network address subnetwork).
261
262              This feature is available in Postfix 2.0 and later.
263
264       FILTER transport:destination
265              After the message is queued, send the entire message through the
266              specified external content filter. The transport name  specifies
267              the  first  field  of  a  mail delivery agent definition in mas‐
268              ter.cf; the syntax of the next-hop destination is  described  in
269              the  manual  page  of  the  corresponding  delivery agent.  More
270              information about external content filters  is  in  the  Postfix
271              FILTER_README file.
272
273              Note  1: do not use $number regular expression substitutions for
274              transport or destination unless you know  that  the  information
275              has a trusted origin.
276
277              Note  2:  this  action overrides the main.cf content_filter set‐
278              ting, and affects all recipients of the  message.  In  the  case
279              that  multiple  FILTER  actions  fire, only the last one is exe‐
280              cuted.
281
282              Note 3: the purpose of the FILTER command is to override message
283              routing.   To  override  the  recipient's  transport but not the
284              next-hop destination, specify an empty filter destination (Post‐
285              fix  2.7  and  later),  or  specify a transport:destination that
286              delivers through a different Postfix instance (Postfix  2.6  and
287              earlier). Other options are using the recipient-dependent trans‐
288              port_maps  or  the  sender-dependent   sender_dependent_default‐
289              _transport_maps features.
290
291              This feature is available in Postfix 2.0 and later.
292
293       HOLD optional text...
294              Place  the  message  on  the hold queue, where it will sit until
295              someone either deletes it or releases it for delivery.  Log  the
296              optional text if specified, otherwise log a generic message.
297
298              Mail  that is placed on hold can be examined with the postcat(1)
299              command, and can be destroyed or released with the  postsuper(1)
300              command.
301
302              Note:  use  "postsuper -r" to release mail that was kept on hold
303              for  a  significant  fraction  of   $maximal_queue_lifetime   or
304              $bounce_queue_lifetime,  or  longer. Use "postsuper -H" only for
305              mail that will not expire within a few delivery attempts.
306
307              Note: this action currently affects all recipients of  the  mes‐
308              sage.
309
310              This feature is available in Postfix 2.0 and later.
311
312       PREPEND headername: headervalue
313              Prepend  the specified message header to the message.  When more
314              than one PREPEND action executes,  the  first  prepended  header
315              appears before the second etc. prepended header.
316
317              Note:  this  action  must  execute before the message content is
318              received;   it   cannot    execute    in    the    context    of
319              smtpd_end_of_data_restrictions.
320
321              This feature is available in Postfix 2.1 and later.
322
323       REDIRECT user@domain
324              After  the  message is queued, send the message to the specified
325              address instead of the intended recipient(s).  When multiple RE‐
326              DIRECT actions fire, only the last one takes effect.
327
328              Note:  this  action  overrides  the FILTER action, and currently
329              overrides all recipients of the message.
330
331              This feature is available in Postfix 2.1 and later.
332
333       INFO optional text...
334              Log an informational record with  the  optional  text,  together
335              with  client  information  and  if available, with helo, sender,
336              recipient and protocol information.
337
338              This feature is available in Postfix 3.0 and later.
339
340       WARN optional text...
341              Log a warning with  the  optional  text,  together  with  client
342              information  and  if available, with helo, sender, recipient and
343              protocol information.
344
345              This feature is available in Postfix 2.1 and later.
346

ENHANCED STATUS CODES

348       Postfix version 2.3 and later support enhanced status codes as  defined
349       in  RFC  3463.   When an enhanced status code is specified in an access
350       table, it is subject to modification. The following transformations are
351       needed  when the same access table is used for client, helo, sender, or
352       recipient access restrictions; they happen regardless of whether  Post‐
353       fix replies to a MAIL FROM, RCPT TO or other SMTP command.
354
355       ·      When  a sender address matches a REJECT action, the Postfix SMTP
356              server will transform a recipient DSN status (e.g., 4.1.1-4.1.6)
357              into the corresponding sender DSN status, and vice versa.
358
359       ·      When  non-address  information  matches a REJECT action (such as
360              the HELO command argument or the client  hostname/address),  the
361              Postfix  SMTP  server  will  transform a sender or recipient DSN
362              status into a generic non-address DSN status (e.g., 4.0.0).
363

REGULAR EXPRESSION TABLES

365       This section describes how the table lookups change when the  table  is
366       given  in the form of regular expressions. For a description of regular
367       expression lookup table syntax, see regexp_table(5) or pcre_table(5).
368
369       Each pattern is a regular expression that  is  applied  to  the  entire
370       string being looked up. Depending on the application, that string is an
371       entire client hostname, an entire client IP address, or an entire  mail
372       address.  Thus,  no  parent  domain  or  parent network search is done,
373       user@domain mail addresses are not  broken  up  into  their  user@  and
374       domain constituent parts, nor is user+foo broken up into user and foo.
375
376       Patterns  are  applied  in the order as specified in the table, until a
377       pattern is found that matches the search string.
378
379       Actions are the same as with indexed file lookups, with the  additional
380       feature  that parenthesized substrings from the pattern can be interpo‐
381       lated as $1, $2 and so on.
382

TCP-BASED TABLES

384       This section describes how the table lookups change  when  lookups  are
385       directed   to  a  TCP-based  server.  For  a  description  of  the  TCP
386       client/server lookup protocol, see tcp_table(5).  This feature  is  not
387       available up to and including Postfix version 2.4.
388
389       Each  lookup operation uses the entire query string once.  Depending on
390       the application, that string is an entire client  hostname,  an  entire
391       client  IP  address, or an entire mail address.  Thus, no parent domain
392       or parent network search is done, user@domain mail  addresses  are  not
393       broken  up  into  their  user@  and  domain  constituent  parts, nor is
394       user+foo broken up into user and foo.
395
396       Actions are the same as with indexed file lookups.
397

EXAMPLE

399       The following example uses an indexed file, so that the order of  table
400       entries  does  not  matter. The example permits access by the client at
401       address 1.2.3.4 but rejects all other clients in 1.2.3.0/24. Instead of
402       hash  lookup  tables,  some systems use dbm.  Use the command "postconf
403       -m" to find out what lookup tables Postfix supports on your system.
404
405       /etc/postfix/main.cf:
406           smtpd_client_restrictions =
407               check_client_access hash:/etc/postfix/access
408
409       /etc/postfix/access:
410           1.2.3   REJECT
411           1.2.3.4 OK
412
413       Execute the command "postmap  /etc/postfix/access"  after  editing  the
414       file.
415

BUGS

417       The table format does not understand quoting conventions.
418

SEE ALSO

420       postmap(1), Postfix lookup table manager
421       smtpd(8), SMTP server
422       postconf(5), configuration parameters
423       transport(5), transport:nexthop syntax
424

README FILES

426       Use  "postconf readme_directory" or "postconf html_directory" to locate
427       this information.
428       SMTPD_ACCESS_README, built-in SMTP server access control
429       DATABASE_README, Postfix lookup table overview
430

LICENSE

432       The Secure Mailer license must be distributed with this software.
433

AUTHOR(S)

435       Wietse Venema
436       IBM T.J. Watson Research
437       P.O. Box 704
438       Yorktown Heights, NY 10598, USA
439
440       Wietse Venema
441       Google, Inc.
442       111 8th Avenue
443       New York, NY 10011, USA
444
445
446
447                                                                     ACCESS(5)
Impressum