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