postfix-master/SMTPD_ACCESS_README.html

   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=us-ascii">
  11
  12 </head>
  13
  14 <body>
  15
  16 <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix
  17 SMTP 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
  24 exposed to the big bad world of junk email and viruses. This document
  25 introduces the built-in and external methods that control what SMTP
  26 mail Postfix will accept, what mistakes to avoid, and how to test
  27 your 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
  34 policies </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
  40 lists </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
  52 policies </a> </h2>
  53
  54 <p> In a distant past, the Internet was a friendly environment.
  55 Mail servers happily forwarded mail on behalf of anyone towards
  56 any destination.  On today's Internet, spammers abuse servers that
  57 forward mail from arbitrary systems, and abused systems end up on
  58 anti-spammer blacklists.  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
  62 mail relaying. Postfix forwards mail only from clients in trusted
  63 networks, or to domains that are configured as authorized relay
  64 destinations. For a description of the default policy, see the
  65 <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> parameter in the <a href="postconf.5.html">postconf(5)</a> manual
  66 page, and the information that is referenced from there.  </p>
  67
  68 <p> Most of the Postfix SMTP server access controls are targeted
  69 at stopping junk email. </p>
  70
  71 <ul>
  72
  73 <li> <p> Protocol oriented: some SMTP server access controls block
  74 mail by being very strict with respect to the SMTP protocol; these
  75 catch poorly implemented and/or poorly configured junk email
  76 software, as well as email worms that come with their own non-standard
  77 SMTP client implementations.  Protocol-oriented access controls
  78 become less useful over time as spammers and worm writers learn to
  79 read RFC documents.  </p>
  80
  81 <li> <p> Blacklist oriented: some SMTP server access controls
  82 query blacklists with known to be bad sites such as open mail
  83 relays, open web proxies, and home computers that have been
  84 compromised and that are under remote control by criminals. The
  85 effectiveness of these blacklists depends on how complete and how
  86 up to date they are. </p>
  87
  88 <li> <p> Threshold oriented: some SMTP server access controls attempt
  89 to raise the bar by either making the client do more work (greylisting)
  90 or by asking for a second opinion (SPF and sender/recipient address
  91 verification).  The greylisting and SPF policies are implemented
  92 externally, and are the subject of the <a href="SMTPD_POLICY_README.html">SMTPD_POLICY_README</a> document.
  93 Sender/recipient address verification is the subject of the
  94 <a href="ADDRESS_VERIFICATION_README.html">ADDRESS_VERIFICATION_README</a> document. </p>
  95
  96 </ul>
  97
  98 <p> Unfortunately, all junk mail controls have the possibility of
  99 falsely rejecting legitimate mail.  This can be a problem for sites
 100 with many different types of users.  For some users it is unacceptable
 101 when any junk email slips through, while for other users the world
 102 comes to an end when a single legitimate email message is blocked.
 103 Because there is no single policy that is "right" for all users,
 104 Postfix supports different SMTP access restrictions for different
 105 users.  This is described in the <a href="RESTRICTION_CLASS_README.html">RESTRICTION_CLASS_README</a> 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
 111 client or per user as described in the next section, Postfix
 112 implements a few restrictions that apply to all SMTP mail.  </p>
 113
 114 <ul>
 115
 116 <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
 117 restrictions, as described in the <a href="BUILTIN_FILTER_README.html">BUILTIN_FILTER_README</a> document.
 118 This happens while Postfix receives mail, before it is stored in
 119 the <a href="QSHAPE_README.html#incoming_queue">incoming queue</a>.  </p>
 120
 121 <li> <p> The external before-queue content restrictions, as described
 122 in the <a href="SMTPD_PROXY_README.html">SMTPD_PROXY_README</a> document.  This happens while Postfix
 123 receives mail, before it is stored in the <a href="QSHAPE_README.html#incoming_queue">incoming queue</a>.  </p>
 124
 125 <li> <p> Requiring that the client sends the HELO or EHLO command
 126 before sending the MAIL FROM or ETRN command. This may cause problems
 127 with home-grown applications that send mail.  For this reason, the
 128 requirement is disabled by default ("<a href="postconf.5.html#smtpd_helo_required">smtpd_helo_required</a> = no").
 129 </p>
 130
 131 <li> <p> Disallowing illegal syntax in MAIL FROM or RCPT TO commands.
 132 This may cause problems with home-grown applications that send
 133 mail, and with ancient PC mail clients.  For this reason, the
 134 requirement is disabled by default ("<a href="postconf.5.html#strict_rfc821_envelopes">strict_rfc821_envelopes</a> =
 135 no").  </p>
 136
 137 <ul>
 138
 139 <li> <p> Disallowing <a href="http://tools.ietf.org/html/rfc822">RFC 822</a> address syntax (example: "MAIL FROM: the
 140 dude &lt;dude@example.com&gt;"). </p>
 141
 142 <li> <p> Disallowing addresses that are not enclosed with &lt;&gt;
 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
 148 of egress filtering helps to slow down worms and other malware, but
 149 may cause problems with home-grown software that sends out mail
 150 software with an unreplyable address. For this reason the requirement
 151 is disabled by default ("<a href="postconf.5.html#smtpd_reject_unlisted_sender">smtpd_reject_unlisted_sender</a> = no").  </p>
 152
 153 <li> <p> Rejecting mail for a non-existent recipient address.  This
 154 form of ingress filtering helps to keep the mail queue free of
 155 undeliverable MAILER-DAEMON messages. This requirement is enabled
 156 by default ("<a href="postconf.5.html#smtpd_reject_unlisted_recipient">smtpd_reject_unlisted_recipient</a> = yes"). </p>
 157
 158 </ul>
 159
 160 <h2> <a name="lists"> Getting selective with SMTP access restriction
 161 lists </a> </h2>
 162
 163 <p> Postfix allows you to specify lists of access restrictions for
 164 each stage of the SMTP conversation. Individual restrictions are
 165 described in the <a href="postconf.5.html">postconf(5)</a> manual page. </p>
 166
 167 <p> Examples of simple restriction lists are: </p>
 168
 169 <pre>
 170 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 171     # Allow connections from trusted networks only.
 172     <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> = <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, reject
 173
 174     # Don't talk to mail systems that don't know their own hostname.
 175     # With Postfix &lt; 2.3, specify <a href="postconf.5.html#reject_unknown_helo_hostname">reject_unknown_hostname</a>.
 176     <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>
 177
 178     # Don't accept mail from domains that don't exist.
 179     <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>
 180
 181     # Whitelisting: local clients may specify any destination domain.
 182     <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
 183
 184     # Block clients that speak too early.
 185     <a href="postconf.5.html#smtpd_data_restrictions">smtpd_data_restrictions</a> = <a href="postconf.5.html#reject_unauth_pipelining">reject_unauth_pipelining</a>
 186
 187     # Enforce mail volume quota via policy service callouts.
 188     <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
 189 </pre>
 190
 191 <p> Each restriction list is evaluated from left to right until
 192 some restriction produces a result of PERMIT, REJECT or DEFER (try
 193 again later).  The end of the list is equivalent to a PERMIT result.
 194 By placing a PERMIT restriction before a REJECT restriction you
 195 can make exceptions for specific clients or users. This is called
 196 whitelisting; the fourth example above allows mail from local
 197 networks but otherwise rejects mail to arbitrary destinations. </p>
 198
 199 <p> The table below summarizes the purpose of each SMTP access
 200 restriction list. All lists use the exact same syntax; they differ
 201 only in the time of evaluation and in the effect of a REJECT or
 202 DEFER result. </p>
 203
 204 <blockquote>
 205
 206 <table border="1">
 207
 208 <tr> <th> Restriction list name </th> <th> Status </th> <th> Effect
 209 of REJECT or DEFER result </th> </tr>
 210
 211 <tr> <td> <a href="postconf.5.html#smtpd_client_restrictions">smtpd_client_restrictions</a> </td> <td> Optional </td> <td>
 212 Reject all client commands </td> </tr>
 213
 214 <tr> <td> <a href="postconf.5.html#smtpd_helo_restrictions">smtpd_helo_restrictions</a> </td> <td> Optional </td> <td>
 215 Reject HELO/EHLO information </td> </tr>
 216
 217 <tr> <td> <a href="postconf.5.html#smtpd_sender_restrictions">smtpd_sender_restrictions</a> </td> <td> Optional </td> <td>
 218 Reject MAIL FROM information </td> </tr>
 219
 220 <tr> <td> <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> </td> <td> Required </td>
 221 <td> Reject RCPT TO information </td> </tr>
 222
 223 <tr> <td> <a href="postconf.5.html#smtpd_data_restrictions">smtpd_data_restrictions</a> </td> <td> Optional </td> <td>
 224 Reject DATA command </td> </tr>
 225
 226 <tr> <td> <a href="postconf.5.html#smtpd_end_of_data_restrictions">smtpd_end_of_data_restrictions</a> </td> <td> Optional </td> <td>
 227 Reject END-OF-DATA command </td> </tr>
 228
 229 <tr> <td> <a href="postconf.5.html#smtpd_etrn_restrictions">smtpd_etrn_restrictions</a> </td> <td> Optional </td> <td>
 230 Reject 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
 240 as early as possible. The client restriction list was evaluated
 241 before Postfix sent the "220 $<a href="postconf.5.html#myhostname">myhostname</a>..." greeting banner to
 242 the SMTP client, the helo restriction list was evaluated before
 243 Postfix replied to the HELO (EHLO) command, the sender restriction
 244 list was evaluated before Postfix replied to the MAIL FROM command,
 245 and so on. This approach turned out to be difficult to use. </p>
 246
 247 <p> Current Postfix versions postpone the evaluation of client,
 248 helo and sender restriction lists until the RCPT TO or ETRN command.
 249 This behavior is controlled by the <a href="postconf.5.html#smtpd_delay_reject">smtpd_delay_reject</a> parameter.
 250 Restriction lists are still evaluated in the proper order of (client,
 251 helo, etrn) or (client, helo, sender, recipient, data, or end-of-data)
 252 restrictions.
 253 When a restriction list (example: client) evaluates to REJECT or
 254 DEFER the other restriction lists (example: helo, sender, etc.)
 255 are skipped.  </p>
 256
 257 <p> Around the time that <a href="postconf.5.html#smtpd_delay_reject">smtpd_delay_reject</a> was introduced, Postfix
 258 was also changed to support mixed restriction lists that combine
 259 information about the client, helo, sender and recipient or etrn
 260 command.  </p>
 261
 262 <p> Benefits of delayed restriction evaluation, and of restriction
 263 mixing: </p>
 264
 265 <ul>
 266
 267 <li> <p> Some SMTP clients do not expect a negative reply early in
 268 the SMTP session. When the bad news is postponed until the RCPT TO
 269 reply, the client goes away as it is supposed to, instead of hanging
 270 around until a timeout happens, or worse, going into an endless
 271 connect-reject-connect loop. </p>
 272
 273 <li> <p> Postfix can log more useful information. For example, when
 274 Postfix rejects a client name or address and delays the action
 275 until the RCPT TO command, it can log the sender and the recipient
 276 address.  This is more useful than logging only the client hostname
 277 and IP address and not knowing whose mail was being blocked.  </p>
 278
 279 <li> <p> Mixing is needed for complex whitelisting policies.  For
 280 example, in order to reject local sender addresses in mail from
 281 non-local clients, you need to be able to mix restrictions on client
 282 information with restrictions on sender information in the same
 283 restriction list. Without this ability, many per-user access
 284 restrictions 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
 291 or sender restrictions, when their evaluation is postponed until
 292 the RCPT TO or ETRN command. Some people recommend placing ALL the
 293 access restrictions in the <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> list.
 294 Unfortunately, this can result in too permissive access.  How is
 295 this possible? </p>
 296
 297 <p> The purpose of the <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> feature is to
 298 control how Postfix replies to the RCPT TO command. If the restriction
 299 list evaluates to REJECT or DEFER, the recipient address is rejected;
 300 no surprises here. If the result is PERMIT, then the recipient
 301 address 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
 304 in too much access permission: </p>
 305
 306 <pre>
 307 1 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 308 2     <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
 309 3         <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
 310 4         <a href="postconf.5.html#check_helo_access">check_helo_access</a> hash:/etc/postfix/helo_access
 311 5         <a href="postconf.5.html#reject_unknown_helo_hostname">reject_unknown_helo_hostname</a>
 312 6         <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
 313 7
 314 8 /etc/postfix/helo_access:
 315 9     localhost.localdomain PERMIT
 316 </pre>
 317
 318 <p> Line 5 rejects mail from hosts that don't specify a proper
 319 hostname in the HELO command (with Postfix &lt; 2.3, specify
 320 <a href="postconf.5.html#reject_unknown_helo_hostname">reject_unknown_hostname</a>). Lines 4 and 9 make an exception to
 321 allow mail from some machine that announces itself with "HELO
 322 localhost.localdomain".  </p>
 323
 324 <p> The problem with this configuration is that
 325 <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> evaluates to PERMIT for EVERY host
 326 that announces itself as "localhost.localdomain", making Postfix
 327 an open relay for all such hosts. </p>
 328
 329 <p> In order to avoid surprises like these with
 330 <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a>, you should place non-recipient
 331 restrictions AFTER the <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a> restriction, not
 332 before. In the above example, the HELO based restrictions should
 333 be placed AFTER <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>, or better, the HELO
 334 based restrictions should be placed under <a href="postconf.5.html#smtpd_helo_restrictions">smtpd_helo_restrictions</a>
 335 where 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
 340 testing: </p>
 341
 342 <dl>
 343
 344 <dt> <a href="postconf.5.html#soft_bounce">soft_bounce</a> </dt> <dd> <p> This is a safety net that changes
 345 SMTP server REJECT actions into DEFER (try again later) actions.
 346 This keeps mail queued that would otherwise be returned to the
 347 sender. 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
 348 the Postfix SMTP server from rejecting mail permanently, by changing
 349 all 5xx SMTP reply codes into 4xx. </p> </dd>
 350
 351 <dt> <a href="postconf.5.html#warn_if_reject">warn_if_reject</a> </dt> <dd> <p> This is a different safety net
 352 that changes SMTP server REJECT actions into warnings. Instead of
 353 rejecting a command, Postfix logs what it would reject. Specify
 354 "<a href="postconf.5.html#warn_if_reject">warn_if_reject</a>" in an SMTP access restriction list, before the
 355 restriction 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
 359 SMTP clients can impersonate other systems, so that you can do
 360 realistic SMTP access rule tests.  Examples of how to impersonate
 361 other systems for access rule testing are given at the end of the
 362 <a href="XCLIENT_README.html">XCLIENT_README</a> document.  </p> </dd>
 363
 364 </dl>
 365
 366 </body>
 367
 368 </html>