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 available in Postfix 3.0 and later. 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). When multiple 344# \fBREDIRECT\fR actions fire, only the last one takes effect. 345# .sp 346# Note: this action overrides the FILTER action, and currently 347# overrides all recipients of the message. 348# .sp 349# This feature is available in Postfix 2.1 and later. 350# .IP "\fBINFO \fIoptional text...\fR 351# Log an informational record with the optional text, together 352# with client information and if available, with helo, sender, 353# recipient and protocol information. 354# .sp 355# This feature is available in Postfix 3.0 and later. 356# .IP "\fBWARN \fIoptional text...\fR 357# Log a warning with the optional text, together with client information 358# and if available, with helo, sender, recipient and protocol information. 359# .sp 360# This feature is available in Postfix 2.1 and later. 361# ENHANCED STATUS CODES 362# .ad 363# .fi 364# Postfix version 2.3 and later support enhanced status codes 365# as defined in RFC 3463. 366# When an enhanced status code is specified in an access 367# table, it is subject to modification. The following 368# transformations are needed when the same access table is 369# used for client, helo, sender, or recipient access restrictions; 370# they happen regardless of whether Postfix replies to a MAIL 371# FROM, RCPT TO or other SMTP command. 372# .IP \(bu 373# When a sender address matches a REJECT action, the Postfix 374# SMTP server will transform a recipient DSN status (e.g., 375# 4.1.1-4.1.6) into the corresponding sender DSN status, and 376# vice versa. 377# .IP \(bu 378# When non-address information matches a REJECT action (such 379# as the HELO command argument or the client hostname/address), 380# the Postfix SMTP server will transform a sender or recipient 381# DSN status into a generic non-address DSN status (e.g., 382# 4.0.0). 383# REGULAR EXPRESSION TABLES 384# .ad 385# .fi 386# This section describes how the table lookups change when the table 387# is given in the form of regular expressions. For a description of 388# regular expression lookup table syntax, see \fBregexp_table\fR(5) 389# or \fBpcre_table\fR(5). 390# 391# Each pattern is a regular expression that is applied to the entire 392# string being looked up. Depending on the application, that string 393# is an entire client hostname, an entire client IP address, or an 394# entire mail address. Thus, no parent domain or parent network search 395# is done, \fIuser@domain\fR mail addresses are not broken up into 396# their \fIuser@\fR and \fIdomain\fR constituent parts, nor is 397# \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 398# 399# Patterns are applied in the order as specified in the table, until a 400# pattern is found that matches the search string. 401# 402# Actions are the same as with indexed file lookups, with 403# the additional feature that parenthesized substrings from the 404# pattern can be interpolated as \fB$1\fR, \fB$2\fR and so on. 405# TCP-BASED TABLES 406# .ad 407# .fi 408# This section describes how the table lookups change when lookups 409# are directed to a TCP-based server. For a description of the TCP 410# client/server lookup protocol, see \fBtcp_table\fR(5). 411# This feature is not available up to and including Postfix version 2.4. 412# 413# Each lookup operation uses the entire query string once. 414# Depending on the application, that string is an entire client 415# hostname, an entire client IP address, or an entire mail address. 416# Thus, no parent domain or parent network search is done, 417# \fIuser@domain\fR mail addresses are not broken up into 418# their \fIuser@\fR and \fIdomain\fR constituent parts, nor is 419# \fIuser+foo\fR broken up into \fIuser\fR and \fIfoo\fR. 420# 421# Actions are the same as with indexed file lookups. 422# EXAMPLE 423# .ad 424# .fi 425# The following example uses an indexed file, so that the 426# order of table entries does not matter. The example permits 427# access by the client at address 1.2.3.4 but rejects all 428# other clients in 1.2.3.0/24. Instead of \fBhash\fR lookup 429# tables, some systems use \fBdbm\fR. Use the command 430# "\fBpostconf -m\fR" to find out what lookup tables Postfix 431# supports on your system. 432# 433# .nf 434# .na 435# /etc/postfix/main.cf: 436# smtpd_client_restrictions = 437# check_client_access hash:/etc/postfix/access 438# 439# /etc/postfix/access: 440# 1.2.3 REJECT 441# 1.2.3.4 OK 442# .fi 443# .ad 444# 445# Execute the command "\fBpostmap /etc/postfix/access\fR" after 446# editing the file. 447# BUGS 448# The table format does not understand quoting conventions. 449# SEE ALSO 450# postmap(1), Postfix lookup table manager 451# smtpd(8), SMTP server 452# postconf(5), configuration parameters 453# transport(5), transport:nexthop syntax 454# README FILES 455# .ad 456# .fi 457# Use "\fBpostconf readme_directory\fR" or 458# "\fBpostconf html_directory\fR" to locate this information. 459# .na 460# .nf 461# SMTPD_ACCESS_README, built-in SMTP server access control 462# DATABASE_README, Postfix lookup table overview 463# LICENSE 464# .ad 465# .fi 466# The Secure Mailer license must be distributed with this software. 467# AUTHOR(S) 468# Wietse Venema 469# IBM T.J. Watson Research 470# P.O. Box 704 471# Yorktown Heights, NY 10598, USA 472# 473# Wietse Venema 474# Google, Inc. 475# 111 8th Avenue 476# New York, NY 10011, USA 477#-- 478