external/ibm-public/postfix/dist/html/INSTALL.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 Installation From Source Code </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 Installation From Source Code </h1>
  18
  19 <hr>
  20
  21 <h2> <a name="1">1 - Purpose of this document</a> </h2>
  22
  23 <p> If you are using a pre-compiled version of Postfix, you should
  24 start with <a href="BASIC_CONFIGURATION_README.html">BASIC_CONFIGURATION_README</a> and the general documentation
  25 referenced by it.  <a href="INSTALL.html">INSTALL</a> is only a bootstrap document to get
  26 Postfix up and running from scratch with the minimal number of
  27 steps; it should not be considered part of the general documentation.
  28 </p>
  29
  30 <p> This document describes how to build, install and configure a
  31 Postfix system so that it can do one of the following: </p>
  32
  33 <ul>
  34
  35 <li> Send mail only, without changing an existing Sendmail
  36 installation.
  37
  38 <li> Send and receive mail via a virtual host interface, still
  39 without any change to an existing Sendmail installation.
  40
  41 <li> Run Postfix instead of Sendmail.
  42
  43 </ul>
  44
  45 <p> Topics covered in this document: </p>
  46
  47 <ol>
  48
  49 <li> <a href="#1">Purpose of this document</a>
  50
  51 <li> <a href="#2">Typographical conventions</a>
  52
  53 <li> <a href="#3">Documentation</a>
  54
  55 <li> <a href="#4">Building on a supported system</a>
  56
  57 <li> <a href="#5">Porting Postfix to an unsupported system</a>
  58
  59 <li> <a href="#install">Installing the software after successful
  60 compilation </a>
  61
  62 <li> <a href="#send_only">Configuring Postfix to send mail
  63 only </a>
  64
  65 <li> <a href="#send_receive">Configuring Postfix to send and
  66 receive mail via virtual interface </a>
  67
  68 <li> <a href="#replace">Running Postfix instead of Sendmail</a>
  69
  70 <li> <a href="#mandatory">Mandatory configuration file edits</a>
  71
  72 <li> <a href="#hamlet">To chroot or not to chroot</a>
  73
  74 <li> <a href="#care">Care and feeding of the Postfix system</a>
  75
  76 </ol>
  77
  78 <h2> <a name="2">2 - Typographical conventions</a> </h2>
  79
  80 <p> In the instructions below, a command written as </p>
  81
  82 <blockquote>
  83 <pre>
  84 # command
  85 </pre>
  86 </blockquote>
  87
  88 <p> should be executed as the superuser. </p>
  89
  90 <p> A command written as </p>
  91
  92 <blockquote>
  93 <pre>
  94 % command
  95 </pre>
  96 </blockquote>
  97
  98 <p> should be executed as an unprivileged user.  </p>
  99
 100 <h2> <a name="3">3 - Documentation</a> </h2>
 101
 102 <p> Documentation is available as README files (start with the file
 103 README_FILES/AAAREADME), as HTML web pages (point your browser to
 104 "html/index.html") and as UNIX-style manual pages. </p>
 105
 106 <p> You should view the README files with a pager such as more(1)
 107 or less(1), because the files use backspace characters in order to
 108 produce <b>bold</b> font. To print a README file without backspace
 109 characters, use the col(1) command.  For example: </p>
 110
 111 <blockquote>
 112 <pre>
 113 % col -bx &lt;file | lpr
 114 </pre>
 115 </blockquote>
 116
 117 <p> In order to view the manual pages before installing Postfix,
 118 point your MANPATH environment variable to the "man" subdirectory;
 119 be sure to use an absolute path.  </p>
 120
 121 <blockquote>
 122 <pre>
 123 % export MANPATH; MANPATH="`pwd`/man:$MANPATH"
 124 % setenv MANPATH "`pwd`/man:$MANPATH"
 125 </pre>
 126 </blockquote>
 127
 128 <p> Of particular interest is the <a href="postconf.5.html">postconf(5)</a> manual page that
 129 lists all the 500+ configuration parameters. The HTML version of
 130 this text makes it easy to navigate around.  </p>
 131
 132 <p> All Postfix source files have their own built-in manual page.
 133 Tools to extract those embedded manual pages are available in the
 134 mantools directory. </p>
 135
 136 <h2> <a name="4">4 - Building on a supported system</a> </h2>
 137
 138 <p> At some point in time, a version of Postfix was supported on: </p>
 139
 140 <blockquote>
 141 <p>
 142 AIX 3.2.5, 4.1.x, 4.2.0, 4.3.x, 5.2 <br>
 143 BSD/OS 2.x, 3.x, 4.x <br>
 144 Darwin 1.x <br>
 145 FreeBSD 2.x, 3.x, 4.x, 5.x <br>
 146 HP-UX  9.x, 10.x, 11.x <br>
 147 IRIX 5.x, 6.x <br>
 148 Linux Debian 1.3.1, 2.x, 3.x <br>
 149 Linux RedHat 3.x (January 2004) - 9.x <br>
 150 Linux Slackware 3.x, 4.x, 7.x <br>
 151 Linux SuSE 5.x, 6.x, 7.x <br>
 152 Linux Ubuntu 4.10..7.04<br>
 153 Mac OS X <br>
 154 NEXTSTEP 3.x <br>
 155 NetBSD 1.x <br>
 156 OPENSTEP 4.x <br>
 157 OSF1.V3 - OSF1.V5 (Digital UNIX) <br>
 158 Reliant UNIX 5.x <br>
 159 Rhapsody 5.x <br>
 160 SunOS 4.1.4 (March 2007) <br>
 161 SunOS 5.4 - 5.10 (Solaris 2.4..10) <br>
 162 Ultrix 4.x (well, that was long ago) <br>
 163 </p>
 164 </blockquote>
 165
 166 <p> or something closely resemblant. </p>
 167
 168 <h3>4.1 - Getting started</h3>
 169
 170 <p> On Solaris, the "make" command and other utilities for software
 171 development are in /usr/ccs/bin, so you MUST have /usr/ccs/bin in
 172 your command search path. If these files do not exist, install the
 173 development packages first. See the Solaris FAQ item "<a
 174 href="http://www.science.uva.nl/pub/solaris/solaris2.html#q6.2">Which
 175 packages do I need to install to support a C compiler?</a>". </p>
 176
 177 <p> If you need to build Postfix for multiple architectures, use the
 178 "lndir" command to build a shadow tree with symbolic links to the
 179 source files. "lndir" is part of X11R6. </p>
 180
 181 <p> If at any time in the build process you get messages like: "make:
 182 don't know how to ..." you should be able to recover by running
 183 the following command from the Postfix top-level directory: </p>
 184
 185 <blockquote>
 186 <pre>
 187 % make -f Makefile.init makefiles
 188 </pre>
 189 </blockquote>
 190
 191 <p> If you copied the Postfix source code after building it on another
 192 machine, it is a good idea to cd into the top-level directory and
 193 first do this:</p>
 194
 195 <blockquote>
 196 <pre>
 197 % make tidy
 198 </pre>
 199 </blockquote>
 200
 201 <p> This will get rid of any system dependencies left over from
 202 compiling the software elsewhere. </p>
 203
 204 <h3>4.2 - What compiler to use</h3>
 205
 206 <p> To build with GCC, or with the native compiler if people told me
 207 that is better for your system, just cd into the top-level Postfix
 208 directory of the source tree and type: </p>
 209
 210 <blockquote>
 211 <pre>
 212 % make
 213 </pre>
 214 </blockquote>
 215
 216 <p> To build with a non-default compiler, you need to specify the name
 217 of the compiler. Here are a few examples: </p>
 218
 219 <blockquote>
 220 <pre>
 221 % make makefiles CC=/opt/SUNWspro/bin/cc        (Solaris)
 222 % make
 223
 224 % make makefiles CC="/opt/ansic/bin/cc -Ae"     (HP-UX)
 225 % make
 226
 227 % make makefiles CC="purify cc"
 228 % make
 229 </pre>
 230 </blockquote>
 231
 232 <p> and so on. In some cases, optimization is turned off automatically. </p>
 233
 234 <h3>4.3 - Building with optional extensions</h3>
 235
 236 By default, Postfix builds as a mail system with relatively few
 237 bells and whistles. Support for third-party databases etc.
 238 must be configured when Postfix is compiled.  The following documents describe how to build Postfix with support for extensions:
 239
 240 <blockquote>
 241 <table border="1">
 242
 243 <tr> <th>Postfix extension </th> <th>Document </th> <th>Availability</th>
 244 </tr>
 245
 246 <tr> <td> Berkeley DB database</td> <td><a href="DB_README.html">DB_README</a></td> <td> Postfix
 247 1.0 </td> </tr>
 248
 249 <tr> <td> LDAP database</td> <td><a href="LDAP_README.html">LDAP_README</a></td> <td> Postfix
 250 1.0 </td> </tr>
 251
 252 <tr> <td> MySQL database</td> <td><a href="MYSQL_README.html">MYSQL_README</a></td> <td> Postfix
 253 1.0 </td> </tr>
 254
 255 <tr> <td> Perl compatible regular expression</td> <td><a href="PCRE_README.html">PCRE_README</a></td>
 256 <td> Postfix 1.0 </td> </tr>
 257
 258 <tr> <td> PostgreSQL database</td> <td><a href="PGSQL_README.html">PGSQL_README</a></td> <td>
 259 Postfix 2.0 </td> </tr>
 260
 261 <tr> <td> SASL authentication </td> <td><a href="SASL_README.html">SASL_README</a></td> <td>
 262 Postfix 1.0 </td> </tr>
 263
 264 <tr> <td> STARTTLS session encryption </td> <td><a href="TLS_README.html">TLS_README</a></td> <td>
 265 Postfix 2.2 </td> </tr>
 266
 267 </table>
 268
 269 </blockquote>
 270
 271 <p> Note: IP version 6 support is compiled into Postfix on operating
 272 systems that have IPv6 support. See the <a href="IPV6_README.html">IPV6_README</a> file for details.
 273 </p>
 274
 275 <h3>4.4 - Overriding built-in parameter default settings</h3>
 276
 277 <p> All Postfix configuration parameters can be changed by editing
 278 a Postfix configuration file, except for one: the parameter that
 279 specifies the location of Postfix configuration files. In order to
 280 build Postfix with a configuration directory other than /etc/postfix,
 281 use: </p>
 282
 283 <blockquote>
 284 <pre>
 285 % make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"'
 286 % make
 287 </pre>
 288 </blockquote>
 289
 290 <p> IMPORTANT: Be sure to get the quotes right. These details matter
 291 a lot. </p>
 292
 293 <p> Parameters whose defaults can be specified in this way are: </p>
 294
 295 <blockquote>
 296
 297 <table border="1">
 298
 299 <tr><th> Macro name </th> <th>default value for</th>  <th>typical
 300 default</th> </tr>
 301
 302 <tr> <td>DEF_COMMAND_DIR</td> <td><a href="postconf.5.html#command_directory">command_directory</a></td>
 303 <td>/usr/sbin</td> </tr>
 304
 305 <tr> <td>DEF_CONFIG_DIR</td> <td><a href="postconf.5.html#config_directory">config_directory</a></td>
 306 <td>/etc/postfix</td> </tr>
 307
 308 <tr> <td>DEF_DAEMON_DIR</td> <td><a href="postconf.5.html#daemon_directory">daemon_directory</a></td>
 309 <td>/usr/libexec/postfix</td> </tr>
 310
 311 <tr> <td>DEF_DATA_DIR</td> <td><a href="postconf.5.html#data_directory">data_directory</a></td>
 312 <td>/var/db/postfix</td> </tr>
 313
 314 <tr> <td>DEF_MAILQ_PATH</td> <td><a href="postconf.5.html#mailq_path">mailq_path</a></td> <td>/usr/bin/mailq</td>
 315 </tr>
 316
 317 <tr> <td>DEF_HTML_DIR</td> <td><a href="postconf.5.html#html_directory">html_directory</a></td>
 318 <td>no</td> </tr>
 319
 320 <tr> <td>DEF_MANPAGE_DIR</td> <td><a href="postconf.5.html#manpage_directory">manpage_directory</a></td>
 321 <td>/usr/local/man</td> </tr>
 322
 323 <tr> <td>DEF_NEWALIAS_PATH</td> <td><a href="postconf.5.html#newaliases_path">newaliases_path</a></td>
 324 <td>/usr/bin/newaliases</td> </tr>
 325
 326 <tr> <td>DEF_QUEUE_DIR</td> <td><a href="postconf.5.html#queue_directory">queue_directory</a></td>
 327 <td>/var/spool/postfix</td> </tr>
 328
 329 <tr> <td>DEF_README_DIR</td> <td><a href="postconf.5.html#readme_directory">readme_directory</a></td>
 330 <td>no</td> </tr>
 331
 332 <tr> <td>DEF_SENDMAIL_PATH</td> <td><a href="postconf.5.html#sendmail_path">sendmail_path</a></td>
 333 <td>/usr/sbin/sendmail</td> </tr>
 334
 335 </table>
 336
 337 </blockquote>
 338
 339 <p> Note: the <a href="postconf.5.html#data_directory">data_directory</a> parameter (for caches and pseudo-random
 340 numbers) was introduced with Postfix version 2.5. </p>
 341
 342 <h3>4.5 - Support for thousands of processes</h3>
 343
 344 <p> The number of connections that Postfix can manage simultaneously
 345 is limited by the number of processes that it can run.  This number
 346 in turn is limited by the number of files and sockets that a single
 347 process can open. For example, the Postfix queue manager has a
 348 separate connection to each delivery process, and the <a href="anvil.8.html">anvil(8)</a>
 349 server has one connection per <a href="smtpd.8.html">smtpd(8)</a> process. </p>
 350
 351 <p> Postfix version 2.4 and later have no built-in limits on the
 352 number of open files or sockets, when compiled on systems that
 353 support one of the following: </p>
 354
 355 <ul>
 356
 357 <li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9),
 358
 359 <li> Solaris 8 /dev/poll,
 360
 361 <li> Linux 2.6 epoll(4).
 362
 363 </ul>
 364
 365
 366 <p> With other Postfix versions or operating systems, the number
 367 of file descriptors per process is limited by the value of the
 368 FD_SETSIZE macro. If you expect to run more than 1000 mail delivery
 369 processes, you may need to override the definition of the FD_SETSIZE
 370 macro to make select() work correctly: </p>
 371
 372 <blockquote>
 373 <pre>
 374 % make makefiles CCARGS=-DFD_SETSIZE=2048
 375 </pre>
 376 </blockquote>
 377
 378 <p> Warning: the above has no effect on some Linux versions.
 379 Apparently, on these systems the FD_SETSIZE value can be changed
 380 only by using undocumented interfaces. Currently, that means
 381 including &lt;bits/types.h&gt; directly (which is not allowed) and
 382 overriding the __FD_SETSIZE macro. Beware, undocumented interfaces
 383 can change at any time and without warning. </p>
 384
 385 <p> But wait, there is more: none of this will work unless the
 386 operating system is configured to handle thousands of connections.
 387 See the <a href="TUNING_README.html">TUNING_README</a> guide for examples of how to increase the
 388 number of open sockets or files. </p>
 389
 390 <h3>4.6 - Compiling Postfix, at last</h3>
 391
 392 <p> If the command </p>
 393
 394 <blockquote>
 395 <pre>
 396 % make
 397 </pre>
 398 </blockquote>
 399
 400 <p> is successful, then you can proceed to <a href="#install">install</a>
 401 Postfix (section 6).
 402
 403 <p> If the command produces compiler error messages, it may be time
 404 to search the web or to ask the postfix-users@postfix.org mailing
 405 list, but be sure to search the mailing list archives first. Some
 406 mailing list archives are linked from <a href="http://www.postfix.org/">http://www.postfix.org/</a>. </p>
 407
 408 <h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2>
 409
 410 <p> Each system type that Postfix knows is identified by a unique
 411 name. Examples:  SUNOS5, FREEBSD4, and so on.  When porting Postfix
 412 to a new system, the first step is to choose a SYSTEMTYPE name for
 413 the new system. You must use a name that includes at least the
 414 major version of the operating system (such as SUNOS4 or LINUX2),
 415 so that different releases of the same system can be supported
 416 without confusion.  </p>
 417
 418 <p> Add a case statement to the "makedefs" shell script in the
 419 source code top-level directory that recognizes the new system
 420 reliably, and that emits the right system-specific information.
 421 Be sure to make the code robust against user PATH settings; if the
 422 system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to
 423 build for the native flavor, instead of the emulated one. </p>
 424
 425 <p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h
 426 include file.  You may have to invent new feature macro names.
 427 Please choose sensible feature macro names such as HAS_DBM or
 428 FIONREAD_IN_SYS_FILIO_H.
 429
 430 <p> I strongly recommend against using "#ifdef SYSTEMTYPE" in
 431 individual source files.  While this may look like the quickest
 432 solution, it will create a mess when newer versions of the same
 433 SYSTEMTYPE need to be supported.  You're likely to end up placing
 434 "#ifdef" sections all over the source code again.  </p>
 435
 436 <h2><a name="install">6 - Installing the software after successful
 437 compilation</a></h2>
 438
 439 <p> This text describes how to install Postfix from source code.
 440 See the <a href="PACKAGE_README.html">PACKAGE_README</a> file if you are building a package for
 441 distribution to other systems. </p>
 442
 443 <h3>6.1 - Save existing Sendmail binaries</h3>
 444
 445 <p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing
 446 Sendmail installation with Postfix, you may need to keep the old
 447 sendmail program running for some time in order to flush the mail
 448 queue. </p>
 449
 450 <ul>
 451
 452 <li> <p> Some systems implement a mail switch mechanism where
 453 different MTAs (Postfix, Sendmail, etc.) can be installed at the
 454 same time, while only one of them is actually being used. Examples
 455 of such switching mechanisms are the FreeBSD mailwrapper(8) or the
 456 Linux mail switch.  In this case you should try to "flip" the switch
 457 to "Postfix" before installing Postfix. </p>
 458
 459 <li> <p> If your system has no mail switch mechanism, execute the
 460 following commands (your sendmail, newaliases and mailq programs
 461 may be in a different place): </p>
 462
 463 <pre>
 464 # mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF
 465 # mv /usr/bin/newaliases /usr/bin/newaliases.OFF
 466 # mv /usr/bin/mailq /usr/bin/mailq.OFF
 467 # chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \
 468     /usr/bin/mailq.OFF
 469 </pre>
 470
 471 </ul>
 472
 473 <h3>6.2 - Create account and groups</h3>
 474
 475 <p> Before you install Postfix for the first time you need to
 476 create an account and a group:</p>
 477
 478 <ul>
 479
 480 <li> <p> Create a user account "postfix" with a user id and group
 481 id that are not used by any other user account.  Preferably, this
 482 is an account that no-one can log into.  The account does not need
 483 an executable login shell, and needs no existing home directory.
 484 My password and group file entries look like this: </p>
 485
 486 <blockquote>
 487 <pre>
 488 /etc/passwd:
 489     postfix:*:12345:12345:postfix:/no/where:/no/shell
 490
 491 /etc/group:
 492     postfix:*:12345:
 493 </pre>
 494 </blockquote>
 495
 496 <p> Note: there should be no whitespace before "postfix:". </p>
 497
 498 <li> <p> Create a group "postdrop" with a group id that is not used
 499 by any other user account. Not even by the postfix user account.
 500 My group file entry looks like:
 501
 502 <blockquote>
 503 <pre>
 504 /etc/group:
 505     postdrop:*:54321:
 506 </pre>
 507 </blockquote>
 508
 509 <p> Note: there should be no whitespace before "postdrop:". </p>
 510
 511 </ul>
 512
 513 <h3>6.3 - Install Postfix</h3>
 514
 515 <p> To install or upgrade Postfix from compiled source code, run
 516 one of the following commands as the super-user:</p>
 517
 518 <blockquote>
 519 <pre>
 520 # make install       (interactive version, first time install)
 521
 522 # make upgrade       (non-interactive version, for upgrades)
 523 </pre>
 524 </blockquote>
 525
 526 <ul>
 527
 528 <li> <p> The interactive version ("make install") asks for pathnames
 529 for Postfix data and program files, and stores your preferences in
 530 the <a href="postconf.5.html">main.cf</a> file. <b> If you don't want Postfix to overwrite
 531 non-Postfix "sendmail", "mailq" and "newaliases" files, specify
 532 pathnames that end in ".postfix"</b>. </p>
 533
 534 <li> <p> The non-interactive version ("make upgrade") needs the
 535 /etc/postfix/<a href="postconf.5.html">main.cf</a> file from a previous installation. If the file
 536 does not exist, use interactive installation ("make install")
 537 instead. </p>
 538
 539 </ul>
 540
 541 <h3>6.4 - Configure Postfix</h3>
 542
 543 <p> Proceed to the section on how you wish to run Postfix on
 544 your particular machine: </p>
 545
 546 <ul>
 547
 548 <li> <p> <a href="#send_only">Send</a> mail only, without changing
 549 an existing Sendmail installation (section 7). </p>
 550
 551 <li> <p> <a href="#send_receive">Send and receive</a> mail via a
 552 virtual host interface, still without any change to an existing
 553 Sendmail installation (section 8). </p>
 554
 555 <li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail
 556 (section 9). </p>
 557
 558 </ul>
 559
 560 <h2><a name="send_only">7 - Configuring Postfix to send mail
 561 only</a></h2>
 562
 563 <p> If you are going to use Postfix to send mail only, there is no
 564 need to change your existing sendmail setup. Instead, set up your
 565 mail user agent so that it calls the Postfix sendmail program
 566 directly. </p>
 567
 568 <p> Follow the instructions in the "<a href="#mandatory">Mandatory
 569 configuration file edits</a>" in section 10, and review the "<a
 570 href="#hamlet">To chroot or not to chroot</a>" text in section
 571 11. </p>
 572
 573 <p> You MUST comment out the "smtp inet" entry in /etc/postfix/<a href="master.5.html">master.cf</a>,
 574 in order to avoid conflicts with the real sendmail. Put a "#"
 575 character in front of the line that defines the smtpd service: </p>
 576
 577 <blockquote>
 578 <pre>
 579 /etc/postfix/<a href="master.5.html">master.cf</a>:
 580     #smtp      inet  n       -       n       -       -       smtpd
 581 </pre>
 582 </blockquote>
 583
 584 <p> Start the Postfix system: </p>
 585
 586 <blockquote>
 587 <pre>
 588 # postfix start
 589 </pre>
 590 </blockquote>
 591
 592 <p> or, if you feel nostalgic, use the Postfix sendmail command: </p>
 593
 594 <blockquote>
 595 <pre>
 596 # sendmail -bd -qwhatever
 597 </pre>
 598 </blockquote>
 599
 600 <p> and watch your maillog file for any error messages. The pathname
 601 is /var/log/maillog, /var/log/mail, /var/log/syslog, or something
 602 else. Typically, the pathname is defined in the /etc/syslog.conf
 603 file. </p>
 604
 605 <blockquote>
 606 <pre>
 607 % egrep '(reject|warning|error|fatal|panic):' /some/log/file
 608 </pre>
 609 </blockquote>
 610
 611 <p> Note: the most important error message is logged first. Later
 612 messages are not as useful. </p>
 613
 614 <p> In order to inspect the mail queue, use one of the following
 615 commands: </p>
 616
 617 <blockquote>
 618 <pre>
 619 % mailq
 620
 621 % sendmail -bp
 622
 623 % postqueue -p
 624 </pre>
 625 </blockquote>
 626
 627 <p> See also the "<a href="#care">Care and feeding</a>" section 12
 628 below.  </p>
 629
 630 <h2><a name="send_receive">8 - Configuring Postfix to send and
 631 receive mail via virtual interface</a></h2>
 632
 633 <p> Alternatively, you can use the Postfix system to send AND
 634 receive mail while leaving your Sendmail setup intact, by running
 635 Postfix on a virtual interface address.  Simply configure your mail
 636 user agent to directly invoke the Postfix sendmail program.  </p>
 637
 638 <p> To create a virtual network interface address, study your
 639 system ifconfig manual page. The command syntax could be any
 640 of: </p>
 641
 642 <blockquote>
 643 <pre>
 644 # <b>ifconfig le0:1 &lt;address&gt; netmask &lt;mask&gt; up</b>
 645 # <b>ifconfig en0 alias &lt;address&gt; netmask 255.255.255.255</b>
 646 </pre>
 647 </blockquote>
 648
 649 <p> In the /etc/postfix/<a href="postconf.5.html">main.cf</a> file, I would specify </p>
 650
 651 <blockquote>
 652 <pre>
 653 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 654     <a href="postconf.5.html#myhostname">myhostname</a> = virtual.host.tld
 655     <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 656     <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 657 </pre>
 658 </blockquote>
 659
 660 <p> Follow the instructions in the "<a href="#mandatory">Mandatory
 661 configuration file edits</a>" in section 10, and review the "<a
 662 name="#hamlet">To chroot or not to chroot</a>" text in section
 663 11. </p>
 664
 665 <p> Start the Postfix system: </p>
 666
 667 <blockquote>
 668 <pre>
 669 # postfix start
 670 </pre>
 671 </blockquote>
 672
 673 <p> or, if you feel nostalgic, use the Postfix sendmail command: </p>
 674
 675 <blockquote>
 676 <pre>
 677 # sendmail -bd -qwhatever
 678 </pre>
 679 </blockquote>
 680
 681 <p> and watch your maillog file for any error messages. The pathname
 682 is /var/log/maillog, /var/log/mail, /var/log/syslog, or something
 683 else. Typically, the pathname is defined in the /etc/syslog.conf
 684 file. </p>
 685
 686 <blockquote>
 687 <pre>
 688 % egrep '(reject|warning|error|fatal|panic):' /some/log/file
 689 </pre>
 690 </blockquote>
 691
 692 <p> Note: the most important error message is logged first. Later
 693 messages are not as useful. </p>
 694
 695 <p> In order to inspect the mail queue, use one of the following
 696 commands: </p>
 697
 698 <blockquote>
 699 <pre>
 700 % mailq
 701
 702 % sendmail -bp
 703
 704 % postqueue -p
 705 </pre>
 706 </blockquote>
 707
 708 <p> See also the "<a href="#care">Care and feeding</a>" section 12
 709 below.  </p>
 710
 711 <h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2>
 712
 713 <p> Prior to installing Postfix you should <a href="#save">save</a>
 714 any existing sendmail program files as described in section 6.  Be
 715 sure to keep the old sendmail running for at least a couple days
 716 to flush any unsent mail. To do so, stop the sendmail daemon and
 717 restart it as: </p>
 718
 719 <blockquote>
 720 <pre>
 721 # /usr/sbin/sendmail.OFF -q
 722 </pre>
 723 </blockquote>
 724
 725 <p> Note: this is old sendmail syntax. Newer versions use separate
 726 processes for mail submission and for running the queue. </p>
 727
 728 <p> After you have visited the "<a href="#mandatory">Mandatory
 729 configuration file edits</a>" section below, you can start the
 730 Postfix system with: </p>
 731
 732 <blockquote>
 733 <pre>
 734 # postfix start
 735 </pre>
 736 </blockquote>
 737
 738 <p> or, if you feel nostalgic, use the Postfix sendmail command: </p>
 739
 740 <blockquote>
 741 <pre>
 742 # sendmail -bd -qwhatever
 743 </pre>
 744 </blockquote>
 745
 746 <p> and watch your maillog file for any error messages. The pathname
 747 is /var/log/maillog, /var/log/mail, /var/log/syslog, or something
 748 else. Typically, the pathname is defined in the /etc/syslog.conf
 749 file. </p>
 750
 751 <blockquote>
 752 <pre>
 753 % egrep '(reject|warning|error|fatal|panic):' /some/log/file
 754 </pre>
 755 </blockquote>
 756
 757 <p> Note: the most important error message is logged first. Later
 758 messages are not as useful. </p>
 759
 760 <p> In order to inspect the mail queue, use one of the following
 761 commands: </p>
 762
 763 <blockquote>
 764 <pre>
 765 % mailq
 766
 767 % sendmail -bp
 768
 769 % postqueue -p
 770 </pre>
 771 </blockquote>
 772
 773 <p> See also the "<a href="#care">Care and feeding</a>" section 12
 774 below.  </p>
 775
 776 <h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2>
 777
 778 <p> Note: the material covered in this section is covered in more
 779 detail in the <a href="BASIC_CONFIGURATION_README.html">BASIC_CONFIGURATION_README</a> document. The information
 780 presented below is targeted at experienced system administrators.
 781 </p>
 782
 783 <h3>10.1 - Postfix configuration files</h3>
 784
 785 <p> By default, Postfix configuration files are in /etc/postfix.
 786 The two most important files are <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a>; these files
 787 must be owned by root.  Giving someone else write permission to
 788 <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a> (or to their parent directories) means giving
 789 root privileges to that person. </p>
 790
 791 <p> In /etc/postfix/<a href="postconf.5.html">main.cf</a>, you will have to set up a minimal number
 792 of configuration parameters.  Postfix configuration parameters
 793 resemble shell variables, with two important differences: the first
 794 one is that Postfix does not know about quotes like the UNIX shell
 795 does.</p>
 796
 797 <p> You specify a configuration parameter as: </p>
 798
 799 <blockquote>
 800 <pre>
 801 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 802     parameter = value
 803 </pre>
 804 </blockquote>
 805
 806 <p> and you use it by putting a "$" character in front of its name: </p>
 807
 808 <blockquote>
 809 <pre>
 810 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 811     other_parameter = $parameter
 812 </pre>
 813 </blockquote>
 814
 815 <p> You can use $parameter before it is given a value (that is the
 816 second main difference with UNIX shell variables). The Postfix
 817 configuration language uses lazy evaluation, and does not look at
 818 a parameter value until it is needed at runtime.  </p>
 819
 820 <p> Whenever you make a change to the <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a> file,
 821 execute the following command in order to refresh a running mail
 822 system: </p>
 823
 824 <blockquote>
 825 <pre>
 826 # postfix reload
 827 </pre>
 828 </blockquote>
 829
 830 <h3>10.2 - Default domain for unqualified addresses</h3>
 831
 832 <p> First of all, you must specify what domain will be appended to an
 833 unqualified address (i.e. an address without @domain.tld). The
 834 "<a href="postconf.5.html#myorigin">myorigin</a>" parameter defaults to the local hostname, but that is
 835 probably OK only for very small sites.  </p>
 836
 837 <p> Some examples (use only one): </p>
 838
 839 <blockquote>
 840 <pre>
 841 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 842     <a href="postconf.5.html#myorigin">myorigin</a> = $<a href="postconf.5.html#myhostname">myhostname</a>    (send mail as "user@$<a href="postconf.5.html#myhostname">myhostname</a>")
 843     <a href="postconf.5.html#myorigin">myorigin</a> = $<a href="postconf.5.html#mydomain">mydomain</a>      (send mail as "user@$<a href="postconf.5.html#mydomain">mydomain</a>")
 844 </pre>
 845 </blockquote>
 846
 847 <h3>10.3 - What domains to receive locally</h3>
 848
 849 <p> Next you need to specify what mail addresses Postfix should deliver
 850 locally. </p>
 851
 852 <p> Some examples (use only one): </p>
 853
 854 <blockquote>
 855 <pre>
 856 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 857     <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a>, localhost.$<a href="postconf.5.html#mydomain">mydomain</a>, localhost
 858     <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a>, localhost.$<a href="postconf.5.html#mydomain">mydomain</a>, localhost, $<a href="postconf.5.html#mydomain">mydomain</a>
 859     <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 860 </pre>
 861 </blockquote>
 862
 863 <p>The first example is appropriate for a workstation, the second
 864 is appropriate for the mailserver for an entire domain. The third
 865 example should be used when running on a virtual host interface.</p>
 866
 867 <h3>10.4 - Proxy/NAT interface addresses </h3>
 868
 869 <p> The <a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> parameter specifies all network addresses
 870 that Postfix receives mail on by way of a proxy or network address
 871 translation unit. You may specify symbolic hostnames instead of
 872 network addresses. </p>
 873
 874 <p> IMPORTANT: You must specify your proxy/NAT external addresses
 875 when your system is a backup MX host for other domains, otherwise
 876 mail delivery loops will happen when the primary MX host is down.
 877 </p>
 878
 879 <p> Example: host behind NAT box running a backup MX host. </p>
 880
 881 <blockquote>
 882 <pre>
 883 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 884     <a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> = 1.2.3.4 (the proxy/NAT external network address)
 885 </pre>
 886 </blockquote>
 887
 888 <h3>10.5 - What local clients to relay mail from </h3>
 889
 890 <p> If your machine is on an open network then you must specify
 891 what client IP addresses are authorized to relay their mail through
 892 your machine into the Internet.  The default setting includes all
 893 subnetworks that the machine is attached to. This may give relay
 894 permission to too many clients.  My own settings are: </p>
 895
 896 <blockquote>
 897 <pre>
 898 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 899     <a href="postconf.5.html#mynetworks">mynetworks</a> = 168.100.189.0/28, 127.0.0.0/8
 900 </pre>
 901 </blockquote>
 902
 903 <h3>10.6 - What relay destinations to accept from strangers </h3>
 904
 905 <p> If your machine is on an open network then you must also specify
 906 whether Postfix will forward mail from strangers.  The default
 907 setting will forward mail to all domains (and subdomains of) what
 908 is listed in $<a href="postconf.5.html#mydestination">mydestination</a>.  This may give relay permission for
 909 too many destinations.  Recommended settings (use only one): </p>
 910
 911 <blockquote>
 912 <pre>
 913 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 914     <a href="postconf.5.html#relay_domains">relay_domains</a> =            (do not forward mail from strangers)
 915     <a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydomain">mydomain</a>  (my domain and subdomains)
 916     <a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydomain">mydomain</a>, other.domain.tld, ...
 917 </pre>
 918 </blockquote>
 919
 920 <h3>10.7 - Optional: configure a smart host for remote delivery</h3>
 921
 922 <p> If you're behind a firewall, you should set up a <a href="postconf.5.html#relayhost">relayhost</a>.  If
 923 you can, specify the organizational domain name so that Postfix
 924 can use DNS lookups, and so that it can fall back to a secondary
 925 MX host when the primary MX host is down. Otherwise just specify
 926 a hard-coded hostname.  </p>
 927
 928 <p> Some examples (use only one): </p>
 929
 930 <blockquote>
 931 <pre>
 932 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 933     <a href="postconf.5.html#relayhost">relayhost</a> = $<a href="postconf.5.html#mydomain">mydomain</a>
 934     <a href="postconf.5.html#relayhost">relayhost</a> = [mail.$<a href="postconf.5.html#mydomain">mydomain</a>]
 935 </pre>
 936 </blockquote>
 937
 938 <p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p>
 939
 940 <p> By default, the SMTP client will do DNS lookups even when you
 941 specify a <a href="postconf.5.html#relayhost">relay host</a>. If your machine has no access to a DNS server,
 942 turn off SMTP client DNS lookups like this: </p>
 943
 944 <blockquote>
 945 <pre>
 946 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 947     <a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> = yes
 948 </pre>
 949 </blockquote>
 950
 951 <p> The <a href="STANDARD_CONFIGURATION_README.html">STANDARD_CONFIGURATION_README</a> file has more hints and tips for
 952 firewalled and/or dial-up networks. </p>
 953
 954 <h3>10.8 - Create the aliases database</h3>
 955
 956 <p> Postfix uses a Sendmail-compatible <a href="aliases.5.html">aliases(5)</a> table to redirect
 957 mail for <a href="local.8.html">local(8)</a> recipients.  Typically, this information is kept
 958 in two files: in a text file /etc/aliases and in an indexed file
 959 /etc/aliases.db.  The command "postconf <a href="postconf.5.html#alias_maps">alias_maps</a>" will tell you
 960 the exact location of the text file.  </p>
 961
 962 <p> First, be sure to update the text file with aliases for root,
 963 postmaster and "postfix" that forward mail to a real person.  Postfix
 964 has a sample aliases file /etc/postfix/aliases that you can adapt
 965 to local conditions.  </p>
 966
 967 <blockquote>
 968 <pre>
 969 /etc/aliases:
 970     root: you
 971     postmaster: root
 972     postfix: root
 973     bin: root
 974     <i>etcetera...</i>
 975 </pre>
 976 </blockquote>
 977
 978 <p> Note: there should be no whitespace before the ":". </p>
 979
 980 <p> Finally, build the indexed aliases file with one of the
 981 following commands: </p>
 982
 983 <blockquote>
 984 <pre>
 985 # newaliases
 986 # sendmail -bi
 987 </pre>
 988 </blockquote>
 989
 990 <h2><a name="hamlet">11 - To chroot or not to chroot</a></h2>
 991
 992 <p> Postfix daemon processes can be configured (via <a href="master.5.html">master.cf</a>) to
 993 run in a chroot jail.  The processes run at a fixed low privilege
 994 and with access only to the Postfix queue directories (/var/spool/postfix).
 995 This provides a significant barrier against intrusion. The barrier
 996 is not impenetrable, but every little bit helps. </p>
 997
 998 <p> With the exception of Postfix daemons that deliver mail locally
 999 and/or that execute non-Postfix commands, every Postfix daemon can
1000 run chrooted. </p>
1001
1002 <p> Sites with high security requirements should consider to chroot
1003 all daemons that talk to the network:  the <a href="smtp.8.html">smtp(8)</a> and <a href="smtpd.8.html">smtpd(8)</a>
1004 processes, and perhaps also the <a href="lmtp.8.html">lmtp(8)</a> client. The author's own
1005 porcupine.org mail server runs all daemons chrooted that can be
1006 chrooted. </p>
1007
1008 <p> The default /etc/postfix/<a href="master.5.html">master.cf</a> file specifies that no
1009 Postfix daemon runs chrooted.  In order to enable chroot operation,
1010 edit the file /etc/postfix/<a href="master.5.html">master.cf</a>. Instructions are in the file.
1011 </p>
1012
1013 <p> Note that a chrooted daemon resolves all filenames relative to
1014 the Postfix queue directory (/var/spool/postfix). For successful
1015 use of a chroot jail,  most UNIX systems require you to bring in
1016 some files or device nodes.  The examples/chroot-setup directory
1017 in the source code distribution has a collection of scripts that
1018 help you set up Postfix chroot environments on different operating
1019 systems. </p>
1020
1021 <p> Additionally, you almost certainly need to configure syslogd
1022 so that it listens on a socket inside the Postfix queue directory.
1023 Examples for specific systems: </p>
1024
1025 <dl>
1026
1027 <dt> FreeBSD: </dt>
1028
1029 <dd> <pre>
1030 # mkdir -p /var/spool/postfix/var/run
1031 # syslogd -l /var/spool/postfix/var/run/log
1032 </pre> </dd>
1033
1034 <dt> Linux, OpenBSD: </dt>
1035
1036 <dd> <pre>
1037 # mkdir -p /var/spool/postfix/dev
1038 # syslogd -a /var/spool/postfix/dev/log
1039 </pre> </dd>
1040
1041 </dl>
1042
1043 <h2><a name="care">12 - Care and feeding of the Postfix system</a></h2>
1044
1045 <p> Postfix daemon processes run in the background, and log problems
1046 and normal activity to the syslog daemon. The names of logfiles
1047 are specified in /etc/syslog.conf. At the very least you need
1048 something like:  </p>
1049
1050 <blockquote>
1051 <pre>
1052 /etc/syslog.conf:
1053     mail.err                                    /dev/console
1054     mail.debug                                  /var/log/maillog
1055 </pre>
1056 </blockquote>
1057
1058 <p> IMPORTANT: the syslogd will not create files. You must create
1059 them before (re)starting syslogd. </p>
1060
1061 <p> IMPORTANT: on Linux you need to put a "-" character before
1062 the pathname, e.g., -/var/log/maillog, otherwise the syslogd
1063 will use more system resources than Postfix does. </p>
1064
1065 <p> Hopefully, the number of problems will be small, but it is a good
1066 idea to run every night before the syslog files are rotated: </p>
1067
1068 <blockquote>
1069 <pre>
1070 # postfix check
1071 # egrep '(reject|warning|error|fatal|panic):' /some/log/file
1072 </pre>
1073 </blockquote>
1074
1075 <ul>
1076
1077 <li> <p> The first line (postfix check) causes Postfix to report
1078 file permission/ownership discrepancies. </p>
1079
1080 <li> <p> The second line looks for problem reports from the mail
1081 software, and reports how effective the relay and junk mail access
1082 blocks are.  This may produce a lot of output.  You will want to
1083 apply some postprocessing to eliminate uninteresting information.
1084 </p>
1085
1086 </ul>
1087
1088 <p>  The <a href="DEBUG_README.html#logging"> DEBUG_README </a>
1089 document describes the meaning of the "warning" etc. labels in
1090 Postfix logging. </p>
1091
1092 </body>
1093
1094 </html>