external/ibm-public/postfix/dist/html/SASL_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 SASL Howto</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 SASL Howto</h1>
  17
  18 <hr>
  19
  20 <h2>WARNING</h2>
  21
  22 <p> People who go to the trouble of installing Postfix may have the
  23 expectation that Postfix is more secure than some other mailers.
  24 The Cyrus SASL library is a lot of code. With this, Postfix becomes
  25 as secure as other mail systems that use the Cyrus SASL library.
  26 Dovecot provides an alternative that may be worth considering.
  27 </p>
  28
  29 <h2><a name="intro">How Postfix uses SASL authentication information</a></h2>
  30
  31 <p> Postfix SASL support (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>, formerly RFC 2554) can be used
  32 to authenticate
  33 remote SMTP clients to the Postfix SMTP server, and to authenticate
  34 the Postfix SMTP client to a remote SMTP server.  </p>
  35
  36 <p> When receiving mail, the Postfix SMTP server logs the client-provided
  37 username,
  38 authentication method, and sender address to the maillog file, and
  39 optionally grants mail access via the <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>
  40 UCE restriction. </p>
  41
  42 <p> When sending mail, the Postfix SMTP client can look up the
  43 remote SMTP server hostname or
  44 destination domain (the address right-hand part) in a SASL password
  45 table, and if a username/password is found, it will use that username
  46 and password to authenticate to the remote SMTP server.  And as of
  47 version 2.3,
  48 Postfix can be configured to search its SASL password table by the
  49 sender email address. </p>
  50
  51 <p>This document covers the following topics: </p>
  52
  53 <ul>
  54
  55 <li><a href="#versions">What SASL implementations are supported</a>
  56
  57 <li><a href="#build_dovecot">Building Postfix with Dovecot SASL
  58 support</a></li>
  59
  60 <li><a href="#build_sasl">Building the Cyrus SASL library</a>
  61
  62 <li><a href="#build_postfix">Building Postfix with Cyrus SASL
  63 support</a></li>
  64
  65 <li><a href="#server_sasl">Enabling SASL authentication in the
  66 Postfix SMTP server</a></li>
  67
  68 <li><a href="#server_dovecot">Dovecot SASL configuration for the Postfix
  69 SMTP server</a></li>
  70
  71 <li><a href="#server_cyrus">Cyrus SASL configuration for the Postfix
  72 SMTP server</a></li>
  73
  74 <li><a href="#server_test">Testing SASL authentication in the
  75 Postfix SMTP server</a></li>
  76
  77 <li><a href="#debugging">Trouble shooting the SASL internals</a>
  78
  79 <li><a href="#client_sasl">Enabling SASL authentication in the
  80 Postfix SMTP client</a></li>
  81
  82 <li><a href="#client_sasl_sender">Supporting multiple ISP accounts
  83 in the Postfix SMTP client</a></li>
  84
  85 <li><a href="#credits">Credits</a>
  86
  87 </ul>
  88
  89 <h2><a name="versions">What SASL implementations are supported</a></h2>
  90
  91 <p> This document describes Postfix with the following SASL
  92 implementations: </p>
  93
  94 <ul>
  95
  96 <li> <p> Cyrus SASL version 1 (client and server). </p>
  97
  98 <li> <p> Cyrus SASL version 2 (client and server). </p>
  99
 100 <li> <p> Dovecot protocol version 1 (server only, Postfix version
 101 2.3 and later) </p>
 102
 103 </ul>
 104
 105 <p> Postfix version 2.3 introduces a plug-in mechanism that provides
 106 support for multiple SASL implementations.  To find out what
 107 implementations are built into Postfix, use the following commands:
 108 </p>
 109
 110 <blockquote>
 111 <pre>
 112 % postconf -a (SASL support in the SMTP server)
 113 % postconf -A (SASL support in the SMTP+LMTP client)
 114 </pre>
 115 </blockquote>
 116
 117 <p> Needless to say, these commands are not available in earlier
 118 Postfix versions. </p>
 119
 120 <h2><a name="build_dovecot">Building Postfix with Dovecot SASL
 121 support</a></h2>
 122
 123 <p> These instructions assume that you build Postfix from source
 124 code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
 125 be required if you build Postfix from a vendor-specific source
 126 package.  </p>
 127
 128 <p> Support for the Dovecot version 1 SASL protocol is available
 129 in Postfix 2.3 and later.  At the time
 130 of writing, only server-side SASL support is available, so you can't
 131 use it to authenticate to your network provider's server. Dovecot
 132 uses its own daemon process for authentication. This keeps the
 133 Postfix build process simple, because there is no need to link extra
 134 libraries into Postfix. </p>
 135
 136 <p> To generate the necessary Makefiles, execute the following
 137 in the Postfix top-level directory: </p>
 138
 139 <blockquote>
 140 <pre>
 141 % make makefiles CCARGS='-DUSE_SASL_AUTH -DDEF_SERVER_SASL_TYPE=\"dovecot\"'
 142 </pre>
 143 </blockquote>
 144
 145 <p> After this, proceed with "<tt>make</tt>" as described in the
 146 <a href="INSTALL.html">INSTALL</a> document. </p>
 147
 148 <p> Notes: </p>
 149
 150 <ul>
 151
 152 <li> <p> The "-DDEF_SERVER_SASL_TYPE" stuff is not necessary; it just
 153 makes Postfix configuration a little more convenient because you
 154 don't have to specify the SASL plug-in type in the Postfix <a href="postconf.5.html">main.cf</a>
 155 file.  </p>
 156
 157 <li> <p> If you also want support for LDAP or TLS, you will have to merge
 158 their CCARGS and AUXLIBS into the above command line. </p>
 159
 160 </ul>
 161
 162 <h2><a name="build_sasl">Building the Cyrus SASL library</a></h2>
 163
 164 <p> Postfix appears to work with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x,
 165 which are available from: </p>
 166
 167 <blockquote>
 168 <pre>
 169 <a href="ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/">ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/</a>
 170 </pre>
 171 </blockquote>
 172
 173 <p> IMPORTANT: if you install the Cyrus SASL libraries as per the
 174 default, you will have to symlink /usr/lib/sasl -&gt; /usr/local/lib/sasl
 175 for version 1.5.x or /usr/lib/sasl2 -&gt; /usr/local/lib/sasl2 for
 176 version 2.1.x. </p>
 177
 178 <p> Reportedly, Microsoft Outlook (Express) requires the
 179 non-standard LOGIN authentication method. To enable this
 180 authentication method, specify ``./configure --enable-login''. </p>
 181
 182 <h2><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h2>
 183
 184 <p> These instructions assume that you build Postfix from source
 185 code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
 186 be required if you build Postfix from a vendor-specific source
 187 package.  </p>
 188
 189 <p> The following
 190 assumes that the Cyrus SASL include files are in /usr/local/include,
 191 and that the Cyrus SASL libraries are in /usr/local/lib. </p>
 192
 193 <p> On some systems this generates the necessary Makefile definitions:
 194 </p>
 195
 196 <dl>
 197
 198 <dt> (for Cyrus SASL version 1.5.x):
 199 <dd>
 200 <pre>
 201 % make tidy # if you have left-over files from a previous build
 202 % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
 203     -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"
 204 </pre>
 205
 206 <dt> (for Cyrus SASL version 2.1.x):
 207 <dd>
 208 <pre>
 209 % make tidy # if you have left-over files from a previous build
 210 % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
 211     -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"
 212 </pre>
 213
 214 </dl>
 215
 216 <p> On Solaris 2.x you need to specify run-time link information,
 217 otherwise ld.so will not find the SASL shared library: </p>
 218
 219 <dl>
 220
 221 <dt> (for Cyrus SASL version 1.5.x):
 222 <dd>
 223 <pre>
 224 % make tidy # if you have left-over files from a previous build
 225 % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
 226     -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
 227     -R/usr/local/lib -lsasl"
 228 </pre>
 229
 230 <dt> (for Cyrus SASL version 2.1.x):
 231 <dd>
 232 <pre>
 233 % make tidy # if you have left-over files from a previous build
 234 % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
 235     -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
 236     -R/usr/local/lib -lsasl2"
 237 </pre>
 238
 239 </dl>
 240
 241 <h2><a name="server_sasl">Enabling SASL authentication in the Postfix
 242 SMTP server</a></h2>
 243
 244 <p> In order to enable SASL support in the Postfix SMTP server: </p>
 245
 246 <blockquote>
 247 <pre>
 248 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 249     <a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a> = yes
 250 </pre>
 251 </blockquote>
 252
 253 <p> In order to allow mail relaying by authenticated remote SMTP
 254 clients: </p>
 255
 256 <blockquote>
 257 <pre>
 258 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 259     <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
 260         <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
 261         <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>
 262         <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
 263 </pre>
 264 </blockquote>
 265
 266 <p> To report SASL login names in Received: message headers
 267 (Postfix version 2.3 and later): </p>
 268
 269 <blockquote>
 270 <pre>
 271 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 272     <a href="postconf.5.html#smtpd_sasl_authenticated_header">smtpd_sasl_authenticated_header</a> = yes
 273 </pre>
 274 </blockquote>
 275
 276 <p> Note: the SASL login names will be shared with the entire world.
 277 </p>
 278
 279 <p> Older Microsoft SMTP client software implements a non-standard
 280 version of the AUTH protocol syntax, and expects that the SMTP
 281 server replies to EHLO with "250 AUTH=mechanism-list" instead of
 282 "250 AUTH mechanism-list".  To accommodate such clients (in addition
 283 to conformant
 284 clients) use the following: </p>
 285
 286 <blockquote>
 287 <pre>
 288 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 289     <a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> = yes
 290 </pre>
 291 </blockquote>
 292
 293 <h2><a name="server_dovecot">Dovecot SASL configuration for the
 294 Postfix SMTP server</a></h2>
 295
 296 <p> Dovecot SASL support is available in Postfix 2.3 and later.  On
 297 the Postfix side you need to specify the location of the
 298 Dovecot authentication daemon socket. We use a pathname relative
 299 to the Postfix queue directory, so that it will work whether or not
 300 the Postfix SMTP server runs chrooted: </p>
 301
 302 <blockquote>
 303 <pre>
 304 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 305     <a href="postconf.5.html#smtpd_sasl_type">smtpd_sasl_type</a> = dovecot
 306     <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = private/auth
 307 </pre>
 308 </blockquote>
 309
 310 <p> On the Dovecot side you also need to specify the Dovecot
 311 authentication daemon socket. In this case we specify an
 312 absolute pathname. In the example we assume that the
 313 Postfix queue is under /var/spool/postfix/. </p>
 314
 315 <blockquote>
 316 <pre>
 317 /some/where/dovecot.conf:
 318     auth default {
 319       mechanisms = plain login
 320       passdb pam {
 321       }
 322       userdb passwd {
 323       }
 324       socket listen {
 325         client {
 326           path = /var/spool/postfix/private/auth
 327           mode = 0660
 328           user = postfix
 329           group = postfix
 330         }
 331       }
 332     }
 333 </pre>
 334 </blockquote>
 335
 336 <p> See the Dovecot documentation for how to configure and operate
 337 the Dovecot authentication server. </p>
 338
 339 <h2><a name="server_cyrus">Cyrus SASL configuration for the Postfix
 340 SMTP server</a></h2>
 341
 342 <p> You need to configure how the Cyrus SASL library should
 343 authenticate a remote SMTP client's username and password. These
 344 settings must
 345 be stored in a separate configuration file. </p>
 346
 347 <p> The name of the configuration file (default: smtpd.conf) will
 348 be constructed from a value that the Postfix SMTP server sends to
 349 the Cyrus SASL
 350 library, which adds the suffix .conf. The value is configured using
 351 one of the following variables: </p>
 352
 353 <blockquote>
 354 <pre>
 355 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 356     # Postfix 2.3 and later
 357     <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = smtpd
 358     # Postfix < 2.3
 359     smtpd_sasl_application_name = smtpd
 360 </pre>
 361 </blockquote>
 362
 363 <p> Cyrus SASL searches for the configuration file in /usr/local/lib/sasl/
 364 (Cyrus SASL version 1.5.5) or /usr/local/lib/sasl2/ (Cyrus SASL
 365 version 2.1.x). </p>
 366
 367 <p> Note: some Postfix distributions are modified and look for
 368 the smtpd.conf file in /etc/postfix/sasl. </p>
 369
 370 <p> Note: some Cyrus SASL distributions look for the smtpd.conf
 371 file in /etc/sasl2. </p>
 372
 373 <ul>
 374
 375 <li> <p> To authenticate against the UNIX password database, use: </p>
 376
 377 <dl>
 378 <dt> (Cyrus SASL version 1.5.x)
 379 <dd>
 380 <pre>
 381 /usr/local/lib/sasl/smtpd.conf:
 382     pwcheck_method: pwcheck
 383
 384 </pre>
 385
 386 <p> IMPORTANT: pwcheck establishes a UNIX domain socket in /var/pwcheck
 387 and waits for authentication requests. The Postfix SMTP server must have
 388 read+execute permission to this directory or authentication attempts
 389 will fail. </p>
 390
 391 <p> The pwcheck daemon is contained in the cyrus-sasl source tarball. </p>
 392
 393 <dt> (Cyrus SASL version 1.5.26)
 394 <dd>
 395 <pre>
 396 /usr/local/lib/sasl/smtpd.conf:
 397     pwcheck_method: saslauthd
 398 </pre>
 399
 400 <dt> (Cyrus SASL version 2.1.x)
 401 <dd>
 402 <pre>
 403 /usr/local/lib/sasl2/smtpd.conf:
 404     pwcheck_method: saslauthd
 405     mech_list: PLAIN LOGIN
 406 </pre>
 407
 408 </dl>
 409
 410 <p> The saslauthd daemon is also contained in the cyrus-sasl source
 411 tarball.  It is more flexible than the pwcheck daemon, in that it
 412 can authenticate against PAM and various other sources. To use PAM,
 413 start saslauthd with "-a pam". </p>
 414
 415 <p> IMPORTANT: saslauthd usually establishes a UNIX domain socket
 416 in /var/run/saslauthd and waits for authentication requests. The Postfix
 417 SMTP server must have read+execute permission to this directory or
 418 authentication attempts will fail. </p>
 419
 420 <p> Note: The directory where saslauthd puts the socket is configurable.
 421 See the command-line option "-m /path/to/socket" in the saslauthd
 422 --help listing. </p>
 423
 424 <li> <p> To authenticate against Cyrus SASL's own password database: </p>
 425
 426 <dl>
 427 <dt> (Cyrus SASL version 1.5.x)
 428 <dd>
 429 <pre>
 430 /usr/local/lib/sasl/smtpd.conf:
 431     pwcheck_method: sasldb
 432 </pre>
 433
 434 <dt> (Cyrus SASL version 2.1.x)
 435 <dd>
 436 <pre>
 437 /usr/local/lib/sasl2/smtpd.conf:
 438     pwcheck_method: auxprop
 439     auxprop_plugin: sasldb
 440     mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5
 441 </pre>
 442
 443 </dl>
 444
 445 <p> This will use the Cyrus SASL password file (default: /etc/sasldb in
 446 version 1.5.x, or /etc/sasldb2 in version 2.1.x), which is maintained
 447 with the saslpasswd or saslpasswd2 command (part of the Cyrus SASL
 448 software). On some poorly-supported systems the saslpasswd command needs
 449 to be run multiple times before it stops complaining.  The Postfix SMTP
 450 server needs read access to the sasldb file - you may have to play games
 451 with group access permissions.  With the OTP authentication mechanism,
 452 the Postfix SMTP server also needs WRITE access to /etc/sasldb2 or
 453 /etc/sasldb
 454 (or the back end SQL database, if used). </p>
 455
 456 <p> IMPORTANT: To get sasldb running, make sure that you set the SASL
 457 domain (realm) to a fully qualified domain name. </p>
 458
 459 <p> EXAMPLE: </p>
 460
 461 <dl>
 462 <dt> (Cyrus SASL version 1.5.x)
 463 <dd>
 464 <pre>
 465 % saslpasswd -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
 466 </pre>
 467
 468 <dt> (Cyrus SASL version 2.1.x)
 469 <dd>
 470 <pre>
 471 % saslpasswd2 -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
 472 </pre>
 473
 474 </dl>
 475
 476 <p> You can find out SASL's idea about the realms of the users
 477 in sasldb with <i>sasldblistusers</i> (Cyrus SASL version 1.5.x) or
 478 <i>sasldblistusers2</i> (Cyrus SASL version 2.1.x). </p>
 479
 480 <p> On the Postfix side, you can have only one realm per <a href="smtpd.8.html">smtpd(8)</a>
 481 instance, and only the users belonging to that realm would be able to
 482 authenticate.  The Postfix variable <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> controls the
 483 realm used by <a href="smtpd.8.html">smtpd(8)</a>: </p>
 484
 485 <blockquote>
 486 <pre>
 487 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 488     <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 489 </pre>
 490 </blockquote>
 491
 492 </ul>
 493
 494 <p> IMPORTANT: The Cyrus SASL password verification services pwcheck
 495 and saslauthd can only support the plaintext mechanisms PLAIN or
 496 LOGIN.  However, the Cyrus SASL library doesn't know this, and will
 497 happily advertise other authentication mechanisms that the SASL
 498 library implements, such as DIGEST-MD5. As a result, if a remote SMTP
 499 client chooses any mechanism other than PLAIN or LOGIN while pwcheck
 500 or saslauthd are used, authentication will fail. Thus you may need
 501 to limit the list of mechanisms advertised by the Postfix SMTP
 502 server. </p>
 503
 504 <ul>
 505
 506 <li> <p> With older Cyrus SASL versions you remove the corresponding
 507 library files from the SASL plug-in directory (and again whenever
 508 the system is updated). </p>
 509
 510 <li> <p> With Cyrus SASL version 2.1.x or later the mech_list variable
 511 can specify a list of authentication mechanisms that Cyrus SASL may
 512 offer: </p>
 513
 514 <blockquote>
 515 <pre>
 516 /usr/local/lib/sasl2/smtpd.conf:
 517     mech_list: plain login
 518 </pre>
 519 </blockquote>
 520
 521 </ul>
 522
 523 <p> For the same reasons you might want to limit the list of plugins
 524 used for authentication. </p>
 525
 526 <ul>
 527
 528 <li> <p> With Cyrus SASL version 1.5.x your only choice is to
 529 delete the corresponding library files from the SASL plug-in
 530 directory. </p>
 531
 532 <li> <p> With SASL version 2.1.x: </p>
 533
 534 <blockquote>
 535 <pre>
 536 /usr/local/lib/sasl2/smtpd.conf:
 537     pwcheck_method: auxprop
 538     auxprop_plugin: sql
 539 </pre>
 540 </blockquote>
 541
 542 </ul>
 543
 544 <p> To run software chrooted with SASL support is an interesting
 545 exercise.  It probably is not worth the trouble. </p>
 546
 547 <h2><a name="server_test">Testing SASL authentication in the Postfix
 548 SMTP server</a></h2>
 549
 550 <p> To test the server side, connect (for example, with telnet) to the
 551 Postfix SMTP server port and you should
 552 be able to have a conversation as shown below. Information sent by the
 553 client (that is, you) is shown in bold font. </p>
 554
 555 <blockquote>
 556 <pre>
 557 $ <b>telnet server.example.com 25</b>
 558 . . .
 559 220 server.example.com ESMTP Postfix
 560 <b>EHLO client.example.com</b>
 561 250-server.example.com
 562 250-PIPELINING
 563 250-SIZE 10240000
 564 250-ETRN
 565 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
 566 250 8BITMIME
 567 <b>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</b>
 568 235 Authentication successful
 569 </pre>
 570 </blockquote>
 571
 572 <p> Instead of AHRlc3QAdGVzdHBhc3M=, specify the base64 encoded
 573 form of \0username\0password (the \0 is a null byte). The
 574 example above is for a user named `test' with password `testpass'.
 575 </p>
 576
 577 <p> In order to generate base64 encoded authentication information
 578 you can use one of the following commands: </p>
 579
 580 <blockquote>
 581 <pre>
 582 % printf '\0username\0password' | mmencode
 583 </pre>
 584 </blockquote>
 585
 586 <blockquote>
 587 <pre>
 588 % perl -MMIME::Base64 -e \
 589     'print encode_base64("\0username\0password");'
 590 </pre>
 591 </blockquote>
 592
 593 <p> The mmencode command is part of the metamail software.
 594 MIME::Base64 is available from <a href="http://www.cpan.org/">http://www.cpan.org/</a>. </p>
 595
 596 <p> Caution: when posting logs of the SASL negotiations to public
 597 lists,
 598 please keep in mind that username/password information is trivial
 599 to recover from the base64-encoded form. </p>
 600
 601 <h2><a name="debugging">Trouble shooting the SASL internals</a></h2>
 602
 603 <p> In the Cyrus SASL sources you'll find a subdirectory named
 604 "sample".  Run make there, then create a symbolic link from sample.conf
 605 to smtpd.conf in your Cyrus SASL library directory /usr/local/lib/sasl2.
 606 "su" to the user <i>postfix</i> (or whatever your <i><a href="postconf.5.html#mail_owner">mail_owner</a></i>
 607 directive is set to): </p>
 608
 609 <blockquote>
 610 <pre>
 611 % su postfix
 612 </pre>
 613 </blockquote>
 614
 615 <p> then run the resulting sample Cyrus SASL server and client in
 616 separate terminals.  The sample applications send log messages to
 617 the syslog
 618 facility auth.  Check the log to fix the problem or run strace /
 619 ktrace / truss on the server to see what makes it unhappy. Repeat
 620 the previous step until you can successfully authenticate with the
 621 sample Cyrus SASL client. Only then get back to Postfix. </p>
 622
 623 <h2><a name="client_sasl">Enabling SASL authentication in the
 624 Postfix SMTP client</a></h2>
 625
 626 <p> Turn on client-side SASL authentication, and specify a table
 627 with per-host or per-destination username and password information.
 628 The Postfix SMTP client first searches the table for an entry with
 629 the remote SMTP server hostname; if no entry is found, then the
 630 Postfix SMTP client searches the table for
 631 an entry with the next-hop destination.  Usually, that is the
 632 right-hand part of an email address, but it can also be the information
 633 that is specified with the <a href="postconf.5.html#relayhost">relayhost</a> parameter or with a <a href="transport.5.html">transport(5)</a>
 634 table. </p>
 635
 636 <blockquote>
 637 <pre>
 638 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 639     <a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
 640     <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
 641     <a href="postconf.5.html#smtp_sasl_type">smtp_sasl_type</a> = cyrus
 642     <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]
 643     # Alternative form:
 644     # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]:submission
 645
 646 /etc/postfix/sasl_passwd:
 647     [mail.myisp.net]            username:password
 648     [mail.myisp.net]:submission username:password
 649 </pre>
 650 </blockquote>
 651
 652 <p> Notes: </p>
 653
 654 <ul>
 655
 656 <li> <p> The "submission" destination port tells Postfix to send
 657 mail via TCP network port 587, which is normally reserved for email
 658 clients. The default is to send mail to the "smtp" destination port
 659 (TCP port 25), which is used for receiving mail across the internet.
 660 If you use an explicit destination port in <a href="postconf.5.html">main.cf</a>, then you must
 661 use the same form also in the <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> file.  </p>
 662
 663 <li> <p> Postfix does not deliver mail via TCP port 465 (the obsolete
 664 "wrappermode" protocol). See <a href="TLS_README.html">TLS_README</a> for a solution that uses the
 665 "stunnel" command. </p>
 666
 667 <li> <p> The "[" and "]" prevent Postfix from looking up the MX
 668 (mail exchanger) records for the enclosed name.  If you use this
 669 form in <a href="postconf.5.html">main.cf</a>, then you must use the same form also in the
 670 <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> file. </p>
 671
 672 <li> <p> The Postfix SMTP client opens the SASL client password
 673 file before entering the optional chroot jail, so you can keep the
 674 file in /etc/postfix and set permissions read / write only for root
 675 to keep the username:password combinations away from other system
 676 users. </p>
 677
 678 <li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
 679 uses <b>dbm</b> files instead of <b>db</b> files. To find out what
 680 lookup tables Postfix supports, use the command "<b>postconf -m</b>".
 681 </p>
 682
 683 <li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
 684 whenever you change the sasl_passwd table. </p>
 685
 686 </ul>
 687
 688 <p> Workarounds: </p>
 689
 690 <ul>
 691
 692 <li> <p> Some remote SMTP servers support PLAIN or LOGIN authentication only.
 693 By default, the Postfix SMTP client does not use authentication
 694 methods that send plaintext passwords, and defers delivery with
 695 the following error message:  "Authentication failed: cannot SASL
 696 authenticate to server". To enable plaintext authentication specify,
 697 for example: </p>
 698
 699 <blockquote>
 700 <pre>
 701 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 702     <a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> = noanonymous
 703 </pre>
 704 </blockquote>
 705
 706 <li> <p> Some remote SMTP servers announce authentication mechanisms
 707 that don't actually work. It is possible via the <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a>
 708 parameter to restrict the list of server mechanisms that the Postfix
 709 SMTP client will take into consideration:  </p>
 710
 711 <blockquote>
 712 <pre>
 713 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 714     <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> = !gssapi, !external, static:all
 715 </pre>
 716 </blockquote>
 717
 718 <p> In the above example, the Postfix SMTP client will decline to
 719 use mechanisms
 720 that require special infrastructure such as Kerberos or TLS. </p>
 721
 722 <li> <p> The Postfix SMTP client is backwards compatible with SMTP
 723 servers that use the non-standard "AUTH=method..." syntax in response
 724 to the EHLO command; there is no Postfix client configuration needed
 725 to work around it. </p>
 726
 727 </ul>
 728
 729 <h2><a name="client_sasl_sender">Supporting multiple ISP accounts
 730 in the Postfix SMTP client</a></h2>
 731
 732 <p> Postfix version 2.3 supports multiple ISP accounts. This can
 733 be useful when one person uses the same machine for work and for
 734 personal use, or when people with different ISP accounts share the
 735 same Postfix server.  To make this possible, Postfix 2.3 supports
 736 per-sender SASL passwords and per-sender relay hosts. In the example
 737 below, Postfix will search the SASL password file by sender before
 738 it searches that same file by destination. Likewise, Postfix will
 739 search the per-sender <a href="postconf.5.html#relayhost">relayhost</a> file, and use the default <a href="postconf.5.html#relayhost">relayhost</a>
 740 only as a final resort.  </p>
 741
 742 <blockquote>
 743 <pre>
 744 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 745     <a href="postconf.5.html#smtp_sender_dependent_authentication">smtp_sender_dependent_authentication</a> = yes
 746     <a href="postconf.5.html#sender_dependent_relayhost_maps">sender_dependent_relayhost_maps</a> = hash:/etc/postfix/sender_relay
 747     <a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
 748     <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
 749     <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]
 750     # Alternative form:
 751     # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]:submission
 752
 753 /etc/postfix/sasl_passwd:
 754     # Per-sender authentication; see also /etc/postfix/sender_relay.
 755     user1@example.com           username2:password2
 756     user2@example.net           username2:password2
 757     # Login information for the default <a href="postconf.5.html#relayhost">relayhost</a>.
 758     [mail.myisp.net]            username:password
 759     [mail.myisp.net]:submission username:password
 760
 761 /etc/postfix/sender_relay:
 762     # Per-sender provider; see also /etc/postfix/sasl_passwd.
 763     user1@example.com           [mail.example.com]:submission
 764     user2@example.net           [mail.example.net]
 765 </pre>
 766 </blockquote>
 767
 768 <p> Notes: </p>
 769
 770 <ul>
 771
 772 <li> <p> If you are creative, then you can try to combine the two
 773 tables into one single MySQL database, and configure different
 774 Postfix queries to extract the appropriate information. </p>
 775
 776 <li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
 777 uses <b>dbm</b> files instead of <b>db</b> files. To find out what
 778 lookup tables Postfix supports, use the command "<b>postconf -m</b>".
 779 </p>
 780
 781 <li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
 782 whenever you change the sasl_passwd table. </p>
 783
 784 <li> <p> Execute the command "<b>postmap /etc/postfix/sender_relay</b>"
 785 whenever you change the sender_relay table. </p>
 786
 787 </ul>
 788
 789 <h2><a name="credits">Credits</a></h2>
 790
 791 <ul>
 792
 793 <li> Postfix SASL support was originally implemented by Till Franke
 794 of SuSE Rhein/Main AG.
 795
 796 <li> Wietse trimmed down the code to only the bare necessities.
 797
 798 <li> Support for Cyrus SASL version 2 was contributed by Jason Hoos.
 799
 800 <li> Liviu Daia added smtpd_sasl_application_name, split
 801 <a href="postconf.5.html#reject_sender_login_mismatch">reject_sender_login_mismatch</a> into
 802 <a href="postconf.5.html#reject_authenticated_sender_login_mismatch">reject_authenticated_sender_login_mismatch</a> and
 803 <a href="postconf.5.html#reject_unauthenticated_sender_login_mismatch">reject_unauthenticated_sender_login_mismatch</a>, and revised the docs.
 804
 805 <li> Wietse made another iteration through the code to add plug-in
 806 support for multiple SASL implementations, and changed
 807 smtpd_sasl_application_name into <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a>.
 808
 809 <li> The Dovecot SMTP server-only plug-in was originally implemented by
 810 Timo Sirainen of Procontrol, Finland.
 811
 812 <li> Patrick Ben Koetter revised this document for Postfix 2.4 and
 813 made much needed updates.
 814
 815 </ul>
 816
 817 </body>
 818
 819 </html>