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