SMTPD_ACCESS_README.html revision 1.1.1.1
1193323Sed<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2193323Sed "http://www.w3.org/TR/html4/loose.dtd"> 3193323Sed 4193323Sed<html> 5193323Sed 6193323Sed<head> 7193323Sed 8193323Sed<title>Postfix SMTP relay and access control </title> 9193323Sed 10193323Sed<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 11193323Sed 12193323Sed</head> 13193323Sed 14193323Sed<body> 15193323Sed 16193323Sed<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 17193323SedSMTP relay and access control </h1> 18193323Sed 19193323Sed<hr> 20195340Sed 21193323Sed<h2> Introduction </h2> 22193323Sed 23193323Sed<p> The Postfix SMTP server receives mail from the network and is 24193323Sedexposed to the big bad world of junk email and viruses. This document 25193323Sedintroduces the built-in and external methods that control what SMTP 26195340Sedmail Postfix will accept, what mistakes to avoid, and how to test 27198090Srdivackyyour configuration. </p> 28193323Sed 29193323Sed<p> Topics covered in this document: </p> 30193323Sed 31193323Sed<ul> 32195340Sed 33195340Sed<li> <a href="#relay"> Relay control, junk mail control, and per-user 34198090Srdivackypolicies </a> 35193323Sed 36193323Sed<li> <a href="#global"> Restrictions that apply to all SMTP mail 37193323Sed</a> 38193323Sed 39193323Sed<li> <a href="#lists"> Getting selective with SMTP access restriction 40193323Sedlists </a> 41193323Sed 42193323Sed<li> <a href="#timing"> Delayed evaluation of SMTP access restriction lists </a> 43193323Sed 44193323Sed<li> <a href="#danger"> Dangerous use of smtpd_recipient_restrictions 45193323Sed</a> 46193323Sed 47198090Srdivacky<li> <a href="#testing"> SMTP access rule testing </a> 48198090Srdivacky 49193323Sed</ul> 50193323Sed 51193323Sed<h2> <a name="relay"> Relay control, junk mail control, and per-user 52193323Sedpolicies </a> </h2> 53193323Sed 54193323Sed<p> In a distant past, the Internet was a friendly environment. 55195340SedMail servers happily forwarded mail on behalf of anyone towards 56195340Sedany destination. On today's Internet, spammers abuse servers that 57193323Sedforward mail from arbitrary systems, and abused systems end up on 58206083Srdivackyanti-spammer blacklists. See, for example, the information on 59193323Sedhttp://www.mail-abuse.org/ and other websites. </p> 60193323Sed 61193323Sed<p> By default, Postfix has a moderately restrictive approach to 62193323Sedmail relaying. Postfix forwards mail only from clients in trusted 63193323Sednetworks, or to domains that are configured as authorized relay 64193323Seddestinations. For a description of the default policy, see the 65193323Sedsmtpd_recipient_restrictions parameter in the postconf(5) manual 66195340Sedpage, and the information that is referenced from there. </p> 67193323Sed 68193323Sed<p> Most of the Postfix SMTP server access controls are targeted 69193323Sedat stopping junk email. </p> 70193323Sed 71193323Sed<ul> 72193323Sed 73193323Sed<li> <p> Protocol oriented: some SMTP server access controls block 74193323Sedmail by being very strict with respect to the SMTP protocol; these 75193323Sedcatch poorly implemented and/or poorly configured junk email 76193323Sedsoftware, as well as email worms that come with their own non-standard 77193323SedSMTP client implementations. Protocol-oriented access controls 78201360Srdivackybecome less useful over time as spammers and worm writers learn to 79193323Sedread RFC documents. </p> 80193323Sed 81193323Sed<li> <p> Blacklist oriented: some SMTP server access controls 82193323Sedquery blacklists with known to be bad sites such as open mail 83193323Sedrelays, open web proxies, and home computers that have been 84193323Sedcompromised and that are under remote control by criminals. The 85193323Sedeffectiveness of these blacklists depends on how complete and how 86193323Sedup to date they are. </p> 87193323Sed 88193323Sed<li> <p> Threshold oriented: some SMTP server access controls attempt 89193323Sedto raise the bar by either making the client do more work (greylisting) 90193323Sedor by asking for a second opinion (SPF and sender/recipient address 91verification). The greylisting and SPF policies are implemented 92externally, and are the subject of the SMTPD_POLICY_README document. 93Sender/recipient address verification is the subject of the 94ADDRESS_VERIFICATION_README document. </p> 95 96</ul> 97 98<p> Unfortunately, all junk mail controls have the possibility of 99falsely rejecting legitimate mail. This can be a problem for sites 100with many different types of users. For some users it is unacceptable 101when any junk email slips through, while for other users the world 102comes to an end when a single legitimate email message is blocked. 103Because there is no single policy that is "right" for all users, 104Postfix supports different SMTP access restrictions for different 105users. This is described in the RESTRICTION_CLASS_README document. 106</p> 107 108<h2> <a name="global"> Restrictions that apply to all SMTP mail </a> </h2> 109 110<p> Besides the restrictions that can be made configurable per 111client or per user as described in the next section, Postfix 112implements a few restrictions that apply to all SMTP mail. </p> 113 114<ul> 115 116<li> <p> The built-in header_checks and body_checks content 117restrictions, as described in the BUILTIN_FILTER_README document. 118This happens while Postfix receives mail, before it is stored in 119the incoming queue. </p> 120 121<li> <p> The external before-queue content restrictions, as described 122in the SMTPD_PROXY_README document. This happens while Postfix 123receives mail, before it is stored in the incoming queue. </p> 124 125<li> <p> Requiring that the client sends the HELO or EHLO command 126before sending the MAIL FROM or ETRN command. This may cause problems 127with home-grown applications that send mail. For this reason, the 128requirement is disabled by default ("smtpd_helo_required = no"). 129</p> 130 131<li> <p> Disallowing illegal syntax in MAIL FROM or RCPT TO commands. 132This may cause problems with home-grown applications that send 133mail, and with ancient PC mail clients. For this reason, the 134requirement is disabled by default ("strict_rfc821_envelopes = 135no"). </p> 136 137<ul> 138 139<li> <p> Disallowing RFC 822 address syntax (example: "MAIL FROM: the 140dude <dude@example.com>"). </p> 141 142<li> <p> Disallowing addresses that are not enclosed with <> 143(example: "MAIL FROM: dude@example.com"). </p> 144 145</ul> 146 147<li> <p> Rejecting mail from a non-existent sender address. This form 148of egress filtering helps to slow down worms and other malware, but 149may cause problems with home-grown software that sends out mail 150software with an unreplyable address. For this reason the requirement 151is disabled by default ("smtpd_reject_unlisted_sender = no"). </p> 152 153<li> <p> Rejecting mail for a non-existent recipient address. This 154form of ingress filtering helps to keep the mail queue free of 155undeliverable MAILER-DAEMON messages. This requirement is enabled 156by default ("smtpd_reject_unlisted_recipient = yes"). </p> 157 158</ul> 159 160<h2> <a name="lists"> Getting selective with SMTP access restriction 161lists </a> </h2> 162 163<p> Postfix allows you to specify lists of access restrictions for 164each stage of the SMTP conversation. Individual restrictions are 165described in the postconf(5) manual page. </p> 166 167<p> Examples of simple restriction lists are: </p> 168 169<pre> 170/etc/postfix/main.cf: 171 # Allow connections from trusted networks only. 172 smtpd_client_restrictions = permit_mynetworks, reject 173 174 # Don't talk to mail systems that don't know their own hostname. 175 # With Postfix < 2.3, specify reject_unknown_hostname. 176 smtpd_helo_restrictions = reject_unknown_helo_hostname 177 178 # Don't accept mail from domains that don't exist. 179 smtpd_sender_restrictions = reject_unknown_sender_domain 180 181 # Whitelisting: local clients may specify any destination domain. 182 smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination 183 184 # Block clients that speak too early. 185 smtpd_data_restrictions = reject_unauth_pipelining 186 187 # Enforce mail volume quota via policy service callouts. 188 smtpd_end_of_data_restrictions = check_policy_service unix:private/policy 189</pre> 190 191<p> Each restriction list is evaluated from left to right until 192some restriction produces a result of PERMIT, REJECT or DEFER (try 193again later). The end of the list is equivalent to a PERMIT result. 194By placing a PERMIT restriction before a REJECT restriction you 195can make exceptions for specific clients or users. This is called 196whitelisting; the fourth example above allows mail from local 197networks but otherwise rejects mail to arbitrary destinations. </p> 198 199<p> The table below summarizes the purpose of each SMTP access 200restriction list. All lists use the exact same syntax; they differ 201only in the time of evaluation and in the effect of a REJECT or 202DEFER result. </p> 203 204<blockquote> 205 206<table border="1"> 207 208<tr> <th> Restriction list name </th> <th> Status </th> <th> Effect 209of REJECT or DEFER result </th> </tr> 210 211<tr> <td> smtpd_client_restrictions </td> <td> Optional </td> <td> 212Reject all client commands </td> </tr> 213 214<tr> <td> smtpd_helo_restrictions </td> <td> Optional </td> <td> 215Reject HELO/EHLO information </td> </tr> 216 217<tr> <td> smtpd_sender_restrictions </td> <td> Optional </td> <td> 218Reject MAIL FROM information </td> </tr> 219 220<tr> <td> smtpd_recipient_restrictions </td> <td> Required </td> 221<td> Reject RCPT TO information </td> </tr> 222 223<tr> <td> smtpd_data_restrictions </td> <td> Optional </td> <td> 224Reject DATA command </td> </tr> 225 226<tr> <td> smtpd_end_of_data_restrictions </td> <td> Optional </td> <td> 227Reject END-OF-DATA command </td> </tr> 228 229<tr> <td> smtpd_etrn_restrictions </td> <td> Optional </td> <td> 230Reject ETRN command </td> </tr> 231 232</table> 233 234</blockquote> 235 236<h2> <a name="timing"> Delayed evaluation of SMTP access restriction lists 237</a> </h2> 238 239<p> Early Postfix versions evaluated SMTP access restrictions lists 240as early as possible. The client restriction list was evaluated 241before Postfix sent the "220 $myhostname..." greeting banner to 242the SMTP client, the helo restriction list was evaluated before 243Postfix replied to the HELO (EHLO) command, the sender restriction 244list was evaluated before Postfix replied to the MAIL FROM command, 245and so on. This approach turned out to be difficult to use. </p> 246 247<p> Current Postfix versions postpone the evaluation of client, 248helo and sender restriction lists until the RCPT TO or ETRN command. 249This behavior is controlled by the smtpd_delay_reject parameter. 250Restriction lists are still evaluated in the proper order of (client, 251helo, etrn) or (client, helo, sender, recipient, data, or end-of-data) 252restrictions. 253When a restriction list (example: client) evaluates to REJECT or 254DEFER the other restriction lists (example: helo, sender, etc.) 255are skipped. </p> 256 257<p> Around the time that smtpd_delay_reject was introduced, Postfix 258was also changed to support mixed restriction lists that combine 259information about the client, helo, sender and recipient or etrn 260command. </p> 261 262<p> Benefits of delayed restriction evaluation, and of restriction 263mixing: </p> 264 265<ul> 266 267<li> <p> Some SMTP clients do not expect a negative reply early in 268the SMTP session. When the bad news is postponed until the RCPT TO 269reply, the client goes away as it is supposed to, instead of hanging 270around until a timeout happens, or worse, going into an endless 271connect-reject-connect loop. </p> 272 273<li> <p> Postfix can log more useful information. For example, when 274Postfix rejects a client name or address and delays the action 275until the RCPT TO command, it can log the sender and the recipient 276address. This is more useful than logging only the client hostname 277and IP address and not knowing whose mail was being blocked. </p> 278 279<li> <p> Mixing is needed for complex whitelisting policies. For 280example, in order to reject local sender addresses in mail from 281non-local clients, you need to be able to mix restrictions on client 282information with restrictions on sender information in the same 283restriction list. Without this ability, many per-user access 284restrictions would be impossible to express. </p> 285 286</ul> 287 288<h2> <a name="danger"> Dangerous use of smtpd_recipient_restrictions </a> </h2> 289 290<p> By now the reader may wonder why we need smtpd client, helo 291or sender restrictions, when their evaluation is postponed until 292the RCPT TO or ETRN command. Some people recommend placing ALL the 293access restrictions in the smtpd_recipient_restrictions list. 294Unfortunately, this can result in too permissive access. How is 295this possible? </p> 296 297<p> The purpose of the smtpd_recipient_restrictions feature is to 298control how Postfix replies to the RCPT TO command. If the restriction 299list evaluates to REJECT or DEFER, the recipient address is rejected; 300no surprises here. If the result is PERMIT, then the recipient 301address is accepted. And this is where surprises can happen. </p> 302 303<p> Here is an example that shows when a PERMIT result can result 304in too much access permission: </p> 305 306<pre> 3071 /etc/postfix/main.cf: 3082 smtpd_recipient_restrictions = 3093 permit_mynetworks 3104 check_helo_access hash:/etc/postfix/helo_access 3115 reject_unknown_helo_hostname 3126 reject_unauth_destination 3137 3148 /etc/postfix/helo_access: 3159 localhost.localdomain PERMIT 316</pre> 317 318<p> Line 5 rejects mail from hosts that don't specify a proper 319hostname in the HELO command (with Postfix < 2.3, specify 320reject_unknown_hostname). Lines 4 and 9 make an exception to 321allow mail from some machine that announces itself with "HELO 322localhost.localdomain". </p> 323 324<p> The problem with this configuration is that 325smtpd_recipient_restrictions evaluates to PERMIT for EVERY host 326that announces itself as "localhost.localdomain", making Postfix 327an open relay for all such hosts. </p> 328 329<p> In order to avoid surprises like these with 330smtpd_recipient_restrictions, you should place non-recipient 331restrictions AFTER the reject_unauth_destination restriction, not 332before. In the above example, the HELO based restrictions should 333be placed AFTER reject_unauth_destination, or better, the HELO 334based restrictions should be placed under smtpd_helo_restrictions 335where they can do no harm. </p> 336 337<h2> <a name="testing"> SMTP access rule testing </a> </h2> 338 339<p> Postfix has several features that aid in SMTP access rule 340testing: </p> 341 342<dl> 343 344<dt> soft_bounce </dt> <dd> <p> This is a safety net that changes 345SMTP server REJECT actions into DEFER (try again later) actions. 346This keeps mail queued that would otherwise be returned to the 347sender. Specify "soft_bounce = yes" in the main.cf file to prevent 348the Postfix SMTP server from rejecting mail permanently, by changing 349all 5xx SMTP reply codes into 4xx. </p> </dd> 350 351<dt> warn_if_reject </dt> <dd> <p> This is a different safety net 352that changes SMTP server REJECT actions into warnings. Instead of 353rejecting a command, Postfix logs what it would reject. Specify 354"warn_if_reject" in an SMTP access restriction list, before the 355restriction that you want to test without actually rejecting mail. 356</p> </dd> 357 358<dt> XCLIENT </dt> <dd> <p> With this Postfix 2.1 feature, authorized 359SMTP clients can impersonate other systems, so that you can do 360realistic SMTP access rule tests. Examples of how to impersonate 361other systems for access rule testing are given at the end of the 362XCLIENT_README document. </p> </dd> 363 364</dl> 365 366</body> 367 368</html> 369
