1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Postfix SMTP relay and access control </title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 13</head> 14 15<body> 16 17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 18SMTP relay and access control </h1> 19 20<hr> 21 22<h2> Introduction </h2> 23 24<p> The Postfix SMTP server receives mail from the network and is 25exposed to the big bad world of junk email and viruses. This document 26introduces the built-in and external methods that control what SMTP 27mail Postfix will accept, what mistakes to avoid, and how to test 28your configuration. </p> 29 30<p> Topics covered in this document: </p> 31 32<ul> 33 34<li> <a href="#relay"> Relay control, junk mail control, and per-user 35policies </a> 36 37<li> <a href="#global"> Restrictions that apply to all SMTP mail 38</a> 39 40<li> <a href="#lists"> Getting selective with SMTP access restriction 41lists </a> 42 43<li> <a href="#timing"> Delayed evaluation of SMTP access restriction lists </a> 44 45<li> <a href="#danger"> Dangerous use of smtpd_recipient_restrictions 46</a> 47 48<li> <a href="#testing"> SMTP access rule testing </a> 49 50</ul> 51 52<h2> <a name="relay"> Relay control, junk mail control, and per-user 53policies </a> </h2> 54 55<p> In a distant past, the Internet was a friendly environment. 56Mail servers happily forwarded mail on behalf of anyone towards 57any destination. On today's Internet, spammers abuse servers that 58forward mail from arbitrary systems, and abused systems end up on 59anti-spammer denylists. See, for example, the information on 60http://www.mail-abuse.org/ and other websites. </p> 61 62<p> By default, Postfix has a moderately restrictive approach to 63mail relaying. Postfix forwards mail only from clients in trusted 64networks, from clients that have authenticated with SASL, or to 65domains that are configured as authorized relay 66destinations. For a description of the default mail relay policy, 67see the smtpd_relay_restrictions parameter in the postconf(5) manual 68page, and the information that is referenced from there. </p> 69 70<blockquote> <p> NOTE: Postfix versions before 2.10 did not have 71smtpd_relay_restrictions. They combined the mail relay and spam 72blocking policies, under smtpd_recipient_restrictions. This could 73lead to unexpected results. For example, a permissive spam blocking 74policy could unexpectedly result in a permissive mail relay policy. 75An example of this is documented under "<a href="#danger">Dangerous 76use of smtpd_recipient_restrictions</a>". </p> </blockquote> 77 78<p> Most of the Postfix SMTP server access controls are targeted 79at stopping junk email. </p> 80 81<ul> 82 83<li> <p> Protocol oriented: some SMTP server access controls block 84mail by being very strict with respect to the SMTP protocol; these 85catch poorly implemented and/or poorly configured junk email 86software, as well as email worms that come with their own non-standard 87SMTP client implementations. Protocol-oriented access controls 88become less useful over time as spammers and worm writers learn to 89read RFC documents. </p> 90 91<li> <p> Denylist oriented: some SMTP server access controls 92query denylists with known to be bad sites such as open mail 93relays, open web proxies, and home computers that have been 94compromised and that are under remote control by criminals. The 95effectiveness of these denylists depends on how complete and how 96up to date they are. </p> 97 98<li> <p> Threshold oriented: some SMTP server access controls attempt 99to raise the bar by either making the client do more work (greylisting) 100or by asking for a second opinion (SPF and sender/recipient address 101verification). The greylisting and SPF policies are implemented 102externally, and are the subject of the SMTPD_POLICY_README document. 103Sender/recipient address verification is the subject of the 104ADDRESS_VERIFICATION_README document. </p> 105 106</ul> 107 108<p> Unfortunately, all junk mail controls have the possibility of 109falsely rejecting legitimate mail. This can be a problem for sites 110with many different types of users. For some users it is unacceptable 111when any junk email slips through, while for other users the world 112comes to an end when a single legitimate email message is blocked. 113Because there is no single policy that is "right" for all users, 114Postfix supports different SMTP access restrictions for different 115users. This is described in the RESTRICTION_CLASS_README document. 116</p> 117 118<h2> <a name="global"> Restrictions that apply to all SMTP mail </a> </h2> 119 120<p> Besides the restrictions that can be made configurable per 121client or per user as described in the next section, Postfix 122implements a few restrictions that apply to all SMTP mail. </p> 123 124<ul> 125 126<li> <p> The built-in header_checks and body_checks content 127restrictions, as described in the BUILTIN_FILTER_README document. 128This happens while Postfix receives mail, before it is stored in 129the incoming queue. </p> 130 131<li> <p> The external before-queue content restrictions, as described 132in the SMTPD_PROXY_README document. This happens while Postfix 133receives mail, before it is stored in the incoming queue. </p> 134 135<li> <p> Requiring that the client sends the HELO or EHLO command 136before sending the MAIL FROM or ETRN command. This may cause problems 137with home-grown applications that send mail. For this reason, the 138requirement is disabled by default ("smtpd_helo_required = no"). 139</p> 140 141<li> <p> Disallowing illegal syntax in MAIL FROM or RCPT TO commands. 142This may cause problems with home-grown applications that send 143mail, and with ancient PC mail clients. For this reason, the 144requirement is disabled by default ("strict_rfc821_envelopes = 145no"). </p> 146 147<ul> 148 149<li> <p> Disallowing RFC 822 address syntax (example: "MAIL FROM: the 150dude <dude@example.com>"). </p> 151 152<li> <p> Disallowing addresses that are not enclosed with <> 153(example: "MAIL FROM: dude@example.com"). </p> 154 155</ul> 156 157<li> <p> Rejecting mail from a non-existent sender address. This form 158of egress filtering helps to slow down worms and other malware, but 159may cause problems with home-grown software that sends out mail 160software with an unreplyable address. For this reason the requirement 161is disabled by default ("smtpd_reject_unlisted_sender = no"). </p> 162 163<li> <p> Rejecting mail for a non-existent recipient address. This 164form of ingress filtering helps to keep the mail queue free of 165undeliverable MAILER-DAEMON messages. This requirement is enabled 166by default ("smtpd_reject_unlisted_recipient = yes"). </p> 167 168</ul> 169 170<h2> <a name="lists"> Getting selective with SMTP access restriction 171lists </a> </h2> 172 173<p> Postfix allows you to specify lists of access restrictions for 174each stage of the SMTP conversation. Individual restrictions are 175described in the postconf(5) manual page. </p> 176 177<p> Examples of simple restriction lists are: </p> 178 179<pre> 180/etc/postfix/main.cf: 181 # Allow connections from trusted networks only. 182 smtpd_client_restrictions = permit_mynetworks, reject 183 184 # Don't talk to mail systems that don't know their own hostname. 185 # With Postfix < 2.3, specify reject_unknown_hostname. 186 smtpd_helo_restrictions = reject_unknown_helo_hostname 187 188 # Don't accept mail from domains that don't exist. 189 smtpd_sender_restrictions = reject_unknown_sender_domain 190 191 # Spam control: exclude local clients and authenticated clients 192 # from DNSBL lookups. 193 smtpd_recipient_restrictions = permit_mynetworks, 194 permit_sasl_authenticated, 195 # reject_unauth_destination is not needed here if the mail 196 # relay policy is specified under smtpd_relay_restrictions 197 # (available with Postfix 2.10 and later). 198 reject_unauth_destination 199 reject_rbl_client zen.spamhaus.org, 200 reject_rhsbl_reverse_client dbl.spamhaus.org, 201 reject_rhsbl_helo dbl.spamhaus.org, 202 reject_rhsbl_sender dbl.spamhaus.org 203 204 # Relay control (Postfix 2.10 and later): local clients and 205 # authenticated clients may specify any destination domain. 206 smtpd_relay_restrictions = permit_mynetworks, 207 permit_sasl_authenticated, 208 reject_unauth_destination 209 210 # Block clients that speak too early. 211 smtpd_data_restrictions = reject_unauth_pipelining 212 213 # Enforce mail volume quota via policy service callouts. 214 smtpd_end_of_data_restrictions = check_policy_service unix:private/policy 215</pre> 216 217<p> Each restriction list is evaluated from left to right until 218some restriction produces a result of PERMIT, REJECT or DEFER (try 219again later). The end of each list is equivalent to a PERMIT result. 220By placing a PERMIT restriction before a REJECT restriction you 221can make exceptions for specific clients or users. This is called 222allowlisting; the smtpd_relay_restrictions example above allows mail from local 223networks, and from SASL authenticated clients, but otherwise rejects mail 224to arbitrary destinations. </p> 225 226<p> The table below summarizes the purpose of each SMTP access 227restriction list. All lists use the exact same syntax; they differ 228only in the time of evaluation and in the effect of a REJECT or 229DEFER result. </p> 230 231<blockquote> 232 233<table border="1"> 234 235<tr> <th> Restriction list name </th> <th> Version </th> <th> Status 236</th> <th> Effect 237of REJECT or DEFER result </th> </tr> 238 239<tr> <td> smtpd_client_restrictions </td> <td> All </td> <td> 240Optional </td> <td> 241Reject all client commands </td> </tr> 242 243<tr> <td> smtpd_helo_restrictions </td> <td> All </td> <td> Optional 244</td> <td> 245Reject HELO/EHLO information </td> </tr> 246 247<tr> <td> smtpd_sender_restrictions </td> <td> All </td> <td> 248Optional </td> <td> 249Reject MAIL FROM information </td> </tr> 250 251<tr> <td rowspan="2"> smtpd_recipient_restrictions </td> <td> ≥ 2522.10 </td> <td> Required if smtpd_relay_restrictions does not enforce 253relay policy</td> 254<td rowspan="2"> Reject RCPT TO information </td> </tr> 255 256<tr> <td> < 2.10</td> <td> Required </td> </tr> 257 258<tr> <td rowspan="2"> smtpd_relay_restrictions </td> <td> ≥ 2.10 259</td> <td> Required if smtpd_recipient_restrictions does not enforce 260relay policy</td> 261<td rowspan="2"> Reject RCPT TO information </td> </tr> 262 263<tr> <td> < 2.10</td> <td> Not available </td> 264</tr> 265 266<tr> <td> smtpd_data_restrictions </td> <td> ≥ 2.0 </td> <td> 267Optional </td> <td> 268Reject DATA command </td> </tr> 269 270<tr> <td> smtpd_end_of_data_restrictions </td> <td> ≥ 2.2 </td> 271<td> Optional </td> <td> 272Reject END-OF-DATA command </td> </tr> 273 274<tr> <td> smtpd_etrn_restrictions </td> <td> All </td> <td> Optional 275</td> <td> 276Reject ETRN command </td> </tr> 277 278</table> 279 280</blockquote> 281 282<h2> <a name="timing"> Delayed evaluation of SMTP access restriction lists 283</a> </h2> 284 285<p> Early Postfix versions evaluated SMTP access restrictions lists 286as early as possible. The client restriction list was evaluated 287before Postfix sent the "220 $myhostname..." greeting banner to 288the SMTP client, the helo restriction list was evaluated before 289Postfix replied to the HELO (EHLO) command, the sender restriction 290list was evaluated before Postfix replied to the MAIL FROM command, 291and so on. This approach turned out to be difficult to use. </p> 292 293<p> Current Postfix versions postpone the evaluation of client, 294helo and sender restriction lists until the RCPT TO or ETRN command. 295This behavior is controlled by the smtpd_delay_reject parameter. 296Restriction lists are still evaluated in the proper order of (client, 297helo, etrn) or (client, helo, sender, relay, recipient, data, or 298end-of-data) restrictions. 299When a restriction list (example: client) evaluates to REJECT or 300DEFER the restriction lists that follow (example: helo, sender, etc.) 301are skipped. </p> 302 303<p> Around the time that smtpd_delay_reject was introduced, Postfix 304was also changed to support mixed restriction lists that combine 305information about the client, helo, sender and recipient or etrn 306command. </p> 307 308<p> Benefits of delayed restriction evaluation, and of restriction 309mixing: </p> 310 311<ul> 312 313<li> <p> Some SMTP clients do not expect a negative reply early in 314the SMTP session. When the bad news is postponed until the RCPT TO 315reply, the client goes away as it is supposed to, instead of hanging 316around until a timeout happens, or worse, going into an endless 317connect-reject-connect loop. </p> 318 319<li> <p> Postfix can log more useful information. For example, when 320Postfix rejects a client name or address and delays the action 321until the RCPT TO command, it can log the sender and the recipient 322address. This is more useful than logging only the client hostname 323and IP address and not knowing whose mail was being blocked. </p> 324 325<li> <p> Mixing is needed for complex allowlisting policies. For 326example, in order to reject local sender addresses in mail from 327non-local clients, you need to be able to mix restrictions on client 328information with restrictions on sender information in the same 329restriction list. Without this ability, many per-user access 330restrictions would be impossible to express. </p> 331 332</ul> 333 334<h2> <a name="danger"> Dangerous use of smtpd_recipient_restrictions </a> </h2> 335 336<p> By now the reader may wonder why we need smtpd client, helo 337or sender restrictions, when their evaluation is postponed until 338the RCPT TO or ETRN command. Some people recommend placing ALL the 339access restrictions in the smtpd_recipient_restrictions list. 340Unfortunately, this can result in too permissive access. How is 341this possible? </p> 342 343<p> The purpose of the smtpd_recipient_restrictions feature is to 344control how Postfix replies to the RCPT TO command. If the restriction 345list evaluates to REJECT or DEFER, the recipient address is rejected; 346no surprises here. If the result is PERMIT, then the recipient 347address is accepted. And this is where surprises can happen. </p> 348 349<p> The problem is that Postfix versions before 2.10 did not have 350smtpd_relay_restrictions. They combined the mail relay and spam 351blocking policies, under smtpd_recipient_restrictions. The result 352is that a permissive spam blocking policy could unexpectedly result 353in a permissive mail relay policy. </p> 354 355<p> Here is an example that shows when a PERMIT result can result 356in too much access permission: </p> 357 358<pre> 3591 /etc/postfix/main.cf: 3602 smtpd_recipient_restrictions = 3613 permit_mynetworks 3624 check_helo_access hash:/etc/postfix/helo_access 3635 reject_unknown_helo_hostname 3646 <b>reject_unauth_destination</b> 3657 3668 /etc/postfix/helo_access: 3679 localhost.localdomain PERMIT 368</pre> 369 370<p> Line 5 rejects mail from hosts that don't specify a proper 371hostname in the HELO command (with Postfix < 2.3, specify 372reject_unknown_hostname). Lines 4 and 9 make an exception to 373allow mail from some machine that announces itself with "HELO 374localhost.localdomain". </p> 375 376<p> The problem with this configuration is that 377smtpd_recipient_restrictions evaluates to PERMIT for EVERY host 378that announces itself as "localhost.localdomain", making Postfix 379an open relay for all such hosts. </p> 380 381<p> With Postfix before version 2.10 you should place non-recipient 382restrictions AFTER the reject_unauth_destination restriction, not 383before. In the above example, the HELO based restrictions should 384be placed AFTER reject_unauth_destination, or better, the HELO 385based restrictions should be placed under smtpd_helo_restrictions 386where they can do no harm. </p> 387 388<pre> 3891 /etc/postfix/main.cf: 3902 smtpd_recipient_restrictions = 3913 permit_mynetworks 3924 <b>reject_unauth_destination</b> 3935 check_helo_access hash:/etc/postfix/helo_access 3946 reject_unknown_helo_hostname 3957 3968 /etc/postfix/helo_access: 3979 localhost.localdomain PERMIT 398</pre> 399 400<p> The above mistake will not happen with Postfix 2.10 and later, 401when the relay policy is specified under smtpd_relay_restrictions, 402and the spam blocking policy under smtpd_recipient_restrictions. 403Then, a permissive spam blocking policy will not result in a 404permissive mail relay policy. </p> 405 406<h2> <a name="testing"> SMTP access rule testing </a> </h2> 407 408<p> Postfix has several features that aid in SMTP access rule 409testing: </p> 410 411<dl> 412 413<dt> soft_bounce </dt> <dd> <p> This is a safety net that changes 414SMTP server REJECT actions into DEFER (try again later) actions. 415This keeps mail queued that would otherwise be returned to the 416sender. Specify "soft_bounce = yes" in the main.cf file to prevent 417the Postfix SMTP server from rejecting mail permanently, by changing 418all 5xx SMTP reply codes into 4xx. </p> </dd> 419 420<dt> warn_if_reject </dt> <dd> <p> When placed before a reject-type 421restriction, access table query, or check_policy_service query, 422this logs a "reject_warning" message instead of rejecting a request 423(when a reject-type restriction fails due to a temporary error, 424this logs a "reject_warning" message for any implicit "defer_if_permit" 425actions that would normally prevent mail from being accepted by 426some later access restriction). This feature has no effect on 427defer_if_reject restrictions. </p> </dd> 428 429<dt> XCLIENT </dt> <dd> <p> With this feature, an authorized SMTP 430client can impersonate other systems and perform realistic SMTP 431access rule tests. Examples of how to impersonate other systems 432for access rule testing are given at the end of the XCLIENT_README 433document. <br> This feature is available in Postfix 2.1. </p> 434</dd> 435 436</dl> 437 438</body> 439 440</html> 441
