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# .IP \fI.domain.tld\fR 70# Matches subdomains of \fIdomain.tld\fR, but only when the 71# string \fBsmtpd_access_maps\fR is not listed in the Postfix 72# \fBparent_domain_matches_subdomains\fR configuration setting. 73# .IP \fIuser\fR@ 74# Matches all mail addresses with the specified user part. 75# .PP 76# Note: lookup of the null sender address is not possible with 77# some types of lookup table. By default, Postfix uses \fB<>\fR 78# as the lookup key for such addresses. The value is specified with 79# the \fBsmtpd_null_access_lookup_key\fR parameter in the Postfix 80# \fBmain.cf\fR file. 81# EMAIL ADDRESS EXTENSION 82# .fi 83# .ad 84# When a mail address localpart contains the optional recipient delimiter 85# (e.g., \fIuser+foo\fR@\fIdomain\fR), the lookup order becomes: 86# \fIuser+foo\fR@\fIdomain\fR, \fIuser\fR@\fIdomain\fR, \fIdomain\fR, 87# \fIuser+foo\fR@, and \fIuser\fR@. 88# HOST NAME/ADDRESS PATTERNS 89# .ad 90# .fi 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# .IP \fIdomain.tld\fR 95# Matches \fIdomain.tld\fR. 96# .sp 97# The pattern \fIdomain.tld\fR also matches subdomains, but only 98# when the string \fBsmtpd_access_maps\fR is listed in the Postfix 99# \fBparent_domain_matches_subdomains\fR configuration setting. 100# .IP \fI.domain.tld\fR 101# Matches subdomains of \fIdomain.tld\fR, but only when the 102# string \fBsmtpd_access_maps\fR is not listed in the Postfix 103# \fBparent_domain_matches_subdomains\fR configuration setting. 104# .IP \fInet.work.addr.ess\fR 105# .IP \fInet.work.addr\fR 106# .IP \fInet.work\fR 107# .IP \fInet\fR 108# Matches the specified IPv4 host address or subnetwork. An 109# IPv4 host address is a sequence of four decimal octets 110# separated by ".". 111# 112# Subnetworks are matched by repeatedly truncating the last 113# ".octet" from the remote IPv4 host address string until a 114# match is found in the access table, or until further 115# truncation is not possible. 116# 117# NOTE 1: The access map lookup key must be in canonical form: 118# do not specify unnecessary null characters, and do not 119# enclose network address information with "[]" characters. 120# 121# NOTE 2: use the \fBcidr\fR lookup table type to specify 122# network/netmask patterns. See \fBcidr_table\fR(5) for details. 123# .IP \fInet:work:addr:ess\fR 124# .IP \fInet:work:addr\fR 125# .IP \fInet:work\fR 126# .IP \fInet\fR 127# Matches the specified IPv6 host address or subnetwork. An 128# IPv6 host address is a sequence of three to eight hexadecimal 129# octet pairs separated by ":". 130# 131# Subnetworks are matched by repeatedly truncating the last 132# ":octetpair" from the remote IPv6 host address string until 133# a match is found in the access table, or until further 134# truncation is not possible. 135# 136# NOTE 1: the truncation and comparison are done with the 137# string representation of the IPv6 host address. Thus, not 138# all the ":" subnetworks will be tried. 139# 140# NOTE 2: The access map lookup key must be in canonical form: 141# do not specify unnecessary null characters, and do not 142# enclose network address information with "[]" characters. 143# 144# NOTE 3: use the \fBcidr\fR lookup table type to specify 145# network/netmask patterns. See \fBcidr_table\fR(5) for details. 146# 147# IPv6 support is available in Postfix 2.2 and later. 148# ACCEPT ACTIONS 149# .ad 150# .fi 151# .IP \fBOK\fR 152# Accept the address etc. that matches the pattern. 153# .IP \fIall-numerical\fR 154# An all-numerical result is treated as OK. This format is 155# generated by address-based relay authorization schemes 156# such as pop-before-smtp. 157# REJECT ACTIONS 158# .ad 159# .fi 160# Postfix version 2.3 and later support enhanced status codes 161# as defined in RFC 3463. 162# When no code is specified at the beginning of the \fItext\fR 163# below, Postfix inserts a default enhanced status code of "5.7.1" 164# in the case of reject actions, and "4.7.1" in the case of 165# defer actions. See "ENHANCED STATUS CODES" below. 166# .IP "\fB4\fINN text\fR" 167# .IP "\fB5\fINN text\fR" 168# Reject the address etc. that matches the pattern, and respond with 169# the numerical three-digit code and text. \fB4\fINN\fR means "try 170# again later", while \fB5\fINN\fR means "do not try again". 171# 172# The following responses have special meaning for the Postfix 173# SMTP server: 174# .RS 175# .IP "\fB421 \fItext\fR (Postfix 2.3 and later)" 176# .IP "\fB521 \fItext\fR (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# .IP 182# Note: The "521" response should be used only with botnets 183# and other malware where interoperability is of no concern. 184# The "send 521 and disconnect" behavior is NOT defined in 185# the SMTP standard. 186# .RE 187# .IP "\fBREJECT \fIoptional text...\fR 188# Reject the address etc. that matches the pattern. Reply with 189# "\fB$access_map_reject_code \fIoptional text...\fR" when the 190# optional text is 191# specified, otherwise reply with a generic error response message. 192# .IP "\fBDEFER \fIoptional text...\fR 193# Reject the address etc. that matches the pattern. Reply with 194# "\fB$access_map_defer_code \fIoptional text...\fR" when the 195# optional text is 196# specified, otherwise reply with a generic error response message. 197# .sp 198# This feature is available in Postfix 2.6 and later. 199# .IP "\fBDEFER_IF_REJECT \fIoptional text...\fR 200# Defer the request if some later restriction would result in a 201# REJECT action. Reply with "\fB$access_map_defer_code 4.7.1 202# \fIoptional text...\fR" when the 203# optional text is specified, otherwise reply with a generic error 204# response message. 205# .sp 206# Prior to Postfix 2.6, the SMTP reply code is 450. 207# .sp 208# This feature is available in Postfix 2.1 and later. 209# .IP "\fBDEFER_IF_PERMIT \fIoptional text...\fR 210# Defer the request if some later restriction would result in a 211# an explicit or implicit PERMIT action. 212# Reply with "\fB$access_map_defer_code 4.7.1 \fI optional 213# text...\fR" when the 214# optional text is specified, otherwise reply with a generic error 215# response message. 216# .sp 217# Prior to Postfix 2.6, the SMTP reply code is 450. 218# .sp 219# This feature is available in Postfix 2.1 and later. 220# OTHER ACTIONS 221# .ad 222# .fi 223# .IP \fIrestriction...\fR 224# Apply the named UCE restriction(s) (\fBpermit\fR, \fBreject\fR, 225# \fBreject_unauth_destination\fR, and so on). 226# .IP "\fBBCC \fIuser@domain\fR" 227# Send one copy of the message to the specified recipient. 228# .sp 229# If multiple BCC actions are specified within the same SMTP 230# MAIL transaction, only the last action will be used. 231# .sp 232# This feature is not part of the stable Postfix release. 233# \" .IP "\fBDELAY \fItime\fR" 234# \" Place the message into the deferred queue, and delay the 235# \" initial delivery attempt by \fItime\fR. The time value may 236# \" be followed by a one-character suffix that specifies the 237# \" time unit: s (seconds), m (minutes), h (hours), d (days), 238# \" w (weeks). The default time unit is s (seconds). 239# \" .sp 240# \" Limitations: 241# \" .RS 242# \" .IP \(bu 243# \" This action affects all the recipients of the message. 244# \" .IP \(bu 245# \" The delay value has no effect with remote file systems that 246# \" don't correctly emulate UNIX local file system semantics. 247# \" In that case, the delay will be half of $queue_run_delay 248# \" on average. 249# \" .IP \(bu 250# \" Mail will still be delivered with "sendmail -q", "postfix 251# \" flush" or "postqueue -f". 252# \" .IP \(bu 253# \" Delayed mail increases the amount of disk I/O during deferred 254# \" queue scans. When large amounts of mail are queued for 255# \" delayed delivery it may be preferable to use the HOLD feature 256# \" instead. 257# \" .RE 258# \" .IP 259# \" This feature is available in Postfix 2.3 and later. 260# .IP "\fBDISCARD \fIoptional text...\fR 261# Claim successful delivery and silently discard the message. 262# Log the optional text if specified, otherwise log a generic 263# message. 264# .sp 265# Note: this action currently affects all recipients of the message. 266# To discard only one recipient without discarding the entire message, 267# use the transport(5) table to direct mail to the discard(8) service. 268# .sp 269# This feature is available in Postfix 2.0 and later. 270# .IP \fBDUNNO\fR 271# Pretend that the lookup key was not found. This 272# prevents Postfix from trying substrings of the lookup key 273# (such as a subdomain name, or a network address subnetwork). 274# .sp 275# This feature is available in Postfix 2.0 and later. 276# .IP "\fBFILTER \fItransport:destination\fR" 277# After the message is queued, send the entire message through 278# the specified external content filter. The \fItransport\fR 279# name specifies the first field of a mail delivery agent 280# definition in master.cf; the syntax of the next-hop 281# \fIdestination\fR is described in the manual page of the 282# corresponding delivery agent. More information about 283# external content filters is in the Postfix FILTER_README 284# file. 285# .sp 286# Note 1: do not use $\fInumber\fR regular expression 287# substitutions for \fItransport\fR or \fIdestination\fR 288# unless you know that the information has a trusted origin. 289# .sp 290# Note 2: this action overrides the main.cf \fBcontent_filter\fR 291# setting, and affects all recipients of the message. In the 292# case that multiple \fBFILTER\fR actions fire, only the last 293# one is executed. 294# .sp 295# Note 3: the purpose of the FILTER command is to override 296# message routing. To override the recipient's \fItransport\fR 297# but not the next-hop \fIdestination\fR, specify an empty 298# filter \fIdestination\fR (Postfix 2.7 and later), or specify 299# a \fItransport:destination\fR that delivers through a 300# different Postfix instance (Postfix 2.6 and earlier). Other 301# options are using the recipient-dependent \fBtrans\%port\%_maps\fR 302# or the sen\%der-dependent 303# \fBsender\%_de\%pen\%dent\%_de\%fault\%_trans\%port\%_maps\fR 304# features. 305# .sp 306# This feature is available in Postfix 2.0 and later. 307# .IP "\fBHOLD \fIoptional text...\fR" 308# Place the message on the \fBhold\fR queue, where it will 309# sit until someone either deletes it or releases it for 310# delivery. 311# Log the optional text if specified, otherwise log a generic 312# message. 313# 314# Mail that is placed on hold can be examined with the 315# \fBpostcat\fR(1) command, and can be destroyed or released with 316# the \fBpostsuper\fR(1) command. 317# .sp 318# Note: use "\fBpostsuper -r\fR" to release mail that was kept on 319# hold for a significant fraction of \fB$maximal_queue_lifetime\fR 320# or \fB$bounce_queue_lifetime\fR, or longer. Use "\fBpostsuper -H\fR" 321# only for mail that will not expire within a few delivery attempts. 322# .sp 323# Note: this action currently affects all recipients of the message. 324# .sp 325# This feature is available in Postfix 2.0 and later. 326# .IP "\fBPREPEND \fIheadername: headervalue\fR" 327# Prepend the specified message header to the message. 328# When more than one PREPEND action executes, the first 329# prepended header appears before the second etc. prepended 330# header. 331# .sp 332# Note: this action must execute before the message content 333# is received; it cannot execute in the context of 334# \fBsmtpd_end_of_data_restrictions\fR. 335# .sp 336# This feature is available in Postfix 2.1 and later. 337# .IP "\fBREDIRECT \fIuser@domain\fR" 338# After the message is queued, send the message to the specified 339# address instead of the intended recipient(s). 340# .sp 341# Note: this action overrides the FILTER action, and currently affects 342# all recipients of the message. 343# .sp 344# This feature is available in Postfix 2.1 and later. 345# .IP "\fBWARN \fIoptional text...\fR 346# Log a warning with the optional text, together with client information 347# and if available, with helo, sender, recipient and protocol information. 348# .sp 349# This feature is available in Postfix 2.1 and later. 350# ENHANCED STATUS CODES 351# .ad 352# .fi 353# Postfix version 2.3 and later support enhanced status codes 354# as defined in RFC 3463. 355# When an enhanced status code is specified in an access 356# table, it is subject to modification. The following 357# transformations are needed when the same access table is 358# used for client, helo, sender, or recipient access restrictions; 359# they happen regardless of whether Postfix replies to a MAIL 360# FROM, RCPT TO or other SMTP command. 361# .IP \(bu 362# When a sender address matches a REJECT action, the Postfix 363# SMTP server will transform a recipient DSN status (e.g., 364# 4.1.1-4.1.6) into the corresponding sender DSN status, and 365# vice versa. 366# .IP \(bu 367# When non-address information matches a REJECT action (such 368# as the HELO command argument or the client hostname/address), 369# the Postfix SMTP server will transform a sender or recipient 370# DSN status into a generic non-address DSN status (e.g., 371# 4.0.0). 372# REGULAR EXPRESSION TABLES 373# .ad 374# .fi 375# This section describes how the table lookups change when the table 376# is given in the form of regular expressions. For a description of 377# regular expression lookup table syntax, see \fBregexp_table\fR(5) 378# or \fBpcre_table\fR(5). 379# 380# Each pattern is a regular expression that is applied to the entire 381# string being looked up. Depending on the application, that string 382# is an entire client hostname, an entire client IP address, or an 383# entire mail address. Thus, no parent domain or parent network search 384# is done, \fIuser@domain\fR mail addresses are not broken up into 385# their \fIuser@\fR and \fIdomain\fR constituent parts, nor is 386# \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 387# 388# Patterns are applied in the order as specified in the table, until a 389# pattern is found that matches the search string. 390# 391# Actions are the same as with indexed file lookups, with 392# the additional feature that parenthesized substrings from the 393# pattern can be interpolated as \fB$1\fR, \fB$2\fR and so on. 394# TCP-BASED TABLES 395# .ad 396# .fi 397# This section describes how the table lookups change when lookups 398# are directed to a TCP-based server. For a description of the TCP 399# client/server lookup protocol, see \fBtcp_table\fR(5). 400# This feature is not available up to and including Postfix version 2.4. 401# 402# Each lookup operation uses the entire query string once. 403# Depending on the application, that string is an entire client 404# hostname, an entire client IP address, or an entire mail address. 405# Thus, no parent domain or parent network search is done, 406# \fIuser@domain\fR mail addresses are not broken up into 407# their \fIuser@\fR and \fIdomain\fR constituent parts, nor is 408# \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 409# 410# Actions are the same as with indexed file lookups. 411# EXAMPLE 412# .ad 413# .fi 414# The following example uses an indexed file, so that the 415# order of table entries does not matter. The example permits 416# access by the client at address 1.2.3.4 but rejects all 417# other clients in 1.2.3.0/24. Instead of \fBhash\fR lookup 418# tables, some systems use \fBdbm\fR. Use the command 419# "\fBpostconf -m\fR" to find out what lookup tables Postfix 420# supports on your system. 421# 422# .nf 423# .na 424# /etc/postfix/main.cf: 425# smtpd_client_restrictions = 426# check_client_access hash:/etc/postfix/access 427# 428# /etc/postfix/access: 429# 1.2.3 REJECT 430# 1.2.3.4 OK 431# .fi 432# .ad 433# 434# Execute the command "\fBpostmap /etc/postfix/access\fR" after 435# editing the file. 436# BUGS 437# The table format does not understand quoting conventions. 438# SEE ALSO 439# postmap(1), Postfix lookup table manager 440# smtpd(8), SMTP server 441# postconf(5), configuration parameters 442# transport(5), transport:nexthop syntax 443# README FILES 444# .ad 445# .fi 446# Use "\fBpostconf readme_directory\fR" or 447# "\fBpostconf html_directory\fR" to locate this information. 448# .na 449# .nf 450# SMTPD_ACCESS_README, built-in SMTP server access control 451# DATABASE_README, Postfix lookup table overview 452# LICENSE 453# .ad 454# .fi 455# The Secure Mailer license must be distributed with this software. 456# AUTHOR(S) 457# Wietse Venema 458# IBM T.J. Watson Research 459# P.O. Box 704 460# Yorktown Heights, NY 10598, USA 461#-- 462