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