postfix-master/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> SQLite database</td> <td><a href="SQLITE_README.html">SQLITE_README</a></td> <td> Postfix
 265 2.8 </td> </tr>
 266
 267 <tr> <td> STARTTLS session encryption </td> <td><a href="TLS_README.html">TLS_README</a></td> <td>
 268 Postfix 2.2 </td> </tr>
 269
 270 </table>
 271
 272 </blockquote>
 273
 274 <p> Note: IP version 6 support is compiled into Postfix on operating
 275 systems that have IPv6 support. See the <a href="IPV6_README.html">IPV6_README</a> file for details.
 276 </p>
 277
 278 <h3>4.4 - Overriding built-in parameter default settings</h3>
 279
 280 <p> All Postfix configuration parameters can be changed by editing
 281 a Postfix configuration file, except for one: the parameter that
 282 specifies the location of Postfix configuration files. In order to
 283 build Postfix with a configuration directory other than /etc/postfix,
 284 use: </p>
 285
 286 <blockquote>
 287 <pre>
 288 % make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"'
 289 % make
 290 </pre>
 291 </blockquote>
 292
 293 <p> IMPORTANT: Be sure to get the quotes right. These details matter
 294 a lot. </p>
 295
 296 <p> Parameters whose defaults can be specified in this way are: </p>
 297
 298 <blockquote>
 299
 300 <table border="1">
 301
 302 <tr><th> Macro name </th> <th>default value for</th>  <th>typical
 303 default</th> </tr>
 304
 305 <tr> <td>DEF_COMMAND_DIR</td> <td><a href="postconf.5.html#command_directory">command_directory</a></td>
 306 <td>/usr/sbin</td> </tr>
 307
 308 <tr> <td>DEF_CONFIG_DIR</td> <td><a href="postconf.5.html#config_directory">config_directory</a></td>
 309 <td>/etc/postfix</td> </tr>
 310
 311 <tr> <td>DEF_DAEMON_DIR</td> <td><a href="postconf.5.html#daemon_directory">daemon_directory</a></td>
 312 <td>/usr/libexec/postfix</td> </tr>
 313
 314 <tr> <td>DEF_DATA_DIR</td> <td><a href="postconf.5.html#data_directory">data_directory</a></td>
 315 <td>/var/lib/postfix</td> </tr>
 316
 317 <tr> <td>DEF_MAILQ_PATH</td> <td><a href="postconf.5.html#mailq_path">mailq_path</a></td> <td>/usr/bin/mailq</td>
 318 </tr>
 319
 320 <tr> <td>DEF_HTML_DIR</td> <td><a href="postconf.5.html#html_directory">html_directory</a></td>
 321 <td>no</td> </tr>
 322
 323 <tr> <td>DEF_MANPAGE_DIR</td> <td><a href="postconf.5.html#manpage_directory">manpage_directory</a></td>
 324 <td>/usr/local/man</td> </tr>
 325
 326 <tr> <td>DEF_NEWALIAS_PATH</td> <td><a href="postconf.5.html#newaliases_path">newaliases_path</a></td>
 327 <td>/usr/bin/newaliases</td> </tr>
 328
 329 <tr> <td>DEF_QUEUE_DIR</td> <td><a href="postconf.5.html#queue_directory">queue_directory</a></td>
 330 <td>/var/spool/postfix</td> </tr>
 331
 332 <tr> <td>DEF_README_DIR</td> <td><a href="postconf.5.html#readme_directory">readme_directory</a></td>
 333 <td>no</td> </tr>
 334
 335 <tr> <td>DEF_SENDMAIL_PATH</td> <td><a href="postconf.5.html#sendmail_path">sendmail_path</a></td>
 336 <td>/usr/sbin/sendmail</td> </tr>
 337
 338 </table>
 339
 340 </blockquote>
 341
 342 <p> Note: the <a href="postconf.5.html#data_directory">data_directory</a> parameter (for caches and pseudo-random
 343 numbers) was introduced with Postfix version 2.5. </p>
 344
 345 <h3>4.5 - Support for thousands of processes</h3>
 346
 347 <p> The number of connections that Postfix can manage simultaneously
 348 is limited by the number of processes that it can run.  This number
 349 in turn is limited by the number of files and sockets that a single
 350 process can open. For example, the Postfix queue manager has a
 351 separate connection to each delivery process, and the <a href="anvil.8.html">anvil(8)</a>
 352 server has one connection per <a href="smtpd.8.html">smtpd(8)</a> process. </p>
 353
 354 <p> Postfix version 2.4 and later have no built-in limits on the
 355 number of open files or sockets, when compiled on systems that
 356 support one of the following: </p>
 357
 358 <ul>
 359
 360 <li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9),
 361
 362 <li> Solaris 8 /dev/poll,
 363
 364 <li> Linux 2.6 epoll(4).
 365
 366 </ul>
 367
 368
 369 <p> With other Postfix versions or operating systems, the number
 370 of file descriptors per process is limited by the value of the
 371 FD_SETSIZE macro. If you expect to run more than 1000 mail delivery
 372 processes, you may need to override the definition of the FD_SETSIZE
 373 macro to make select() work correctly: </p>
 374
 375 <blockquote>
 376 <pre>
 377 % make makefiles CCARGS=-DFD_SETSIZE=2048
 378 </pre>
 379 </blockquote>
 380
 381 <p> Warning: the above has no effect on some Linux versions.
 382 Apparently, on these systems the FD_SETSIZE value can be changed
 383 only by using undocumented interfaces. Currently, that means
 384 including &lt;bits/types.h&gt; directly (which is not allowed) and
 385 overriding the __FD_SETSIZE macro. Beware, undocumented interfaces
 386 can change at any time and without warning. </p>
 387
 388 <p> But wait, there is more: none of this will work unless the
 389 operating system is configured to handle thousands of connections.
 390 See the <a href="TUNING_README.html">TUNING_README</a> guide for examples of how to increase the
 391 number of open sockets or files. </p>
 392
 393 <h3>4.6 - Compiling Postfix, at last</h3>
 394
 395 <p> If the command </p>
 396
 397 <blockquote>
 398 <pre>
 399 % make
 400 </pre>
 401 </blockquote>
 402
 403 <p> is successful, then you can proceed to <a href="#install">install</a>
 404 Postfix (section 6).
 405
 406 <p> If the command produces compiler error messages, it may be time
 407 to search the web or to ask the postfix-users@postfix.org mailing
 408 list, but be sure to search the mailing list archives first. Some
 409 mailing list archives are linked from <a href="http://www.postfix.org/">http://www.postfix.org/</a>. </p>
 410
 411 <h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2>
 412
 413 <p> Each system type that Postfix knows is identified by a unique
 414 name. Examples:  SUNOS5, FREEBSD4, and so on.  When porting Postfix
 415 to a new system, the first step is to choose a SYSTEMTYPE name for
 416 the new system. You must use a name that includes at least the
 417 major version of the operating system (such as SUNOS4 or LINUX2),
 418 so that different releases of the same system can be supported
 419 without confusion.  </p>
 420
 421 <p> Add a case statement to the "makedefs" shell script in the
 422 source code top-level directory that recognizes the new system
 423 reliably, and that emits the right system-specific information.
 424 Be sure to make the code robust against user PATH settings; if the
 425 system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to
 426 build for the native flavor, instead of the emulated one. </p>
 427
 428 <p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h
 429 include file.  You may have to invent new feature macro names.
 430 Please choose sensible feature macro names such as HAS_DBM or
 431 FIONREAD_IN_SYS_FILIO_H.
 432
 433 <p> I strongly recommend against using "#ifdef SYSTEMTYPE" in
 434 individual source files.  While this may look like the quickest
 435 solution, it will create a mess when newer versions of the same
 436 SYSTEMTYPE need to be supported.  You're likely to end up placing
 437 "#ifdef" sections all over the source code again.  </p>
 438
 439 <h2><a name="install">6 - Installing the software after successful
 440 compilation</a></h2>
 441
 442 <p> This text describes how to install Postfix from source code.
 443 See the <a href="PACKAGE_README.html">PACKAGE_README</a> file if you are building a package for
 444 distribution to other systems. </p>
 445
 446 <h3>6.1 - Save existing Sendmail binaries</h3>
 447
 448 <p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing
 449 Sendmail installation with Postfix, you may need to keep the old
 450 sendmail program running for some time in order to flush the mail
 451 queue. </p>
 452
 453 <ul>
 454
 455 <li> <p> Some systems implement a mail switch mechanism where
 456 different MTAs (Postfix, Sendmail, etc.) can be installed at the
 457 same time, while only one of them is actually being used. Examples
 458 of such switching mechanisms are the FreeBSD mailwrapper(8) or the
 459 Linux mail switch.  In this case you should try to "flip" the switch
 460 to "Postfix" before installing Postfix. </p>
 461
 462 <li> <p> If your system has no mail switch mechanism, execute the
 463 following commands (your sendmail, newaliases and mailq programs
 464 may be in a different place): </p>
 465
 466 <pre>
 467 # mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF
 468 # mv /usr/bin/newaliases /usr/bin/newaliases.OFF
 469 # mv /usr/bin/mailq /usr/bin/mailq.OFF
 470 # chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \
 471     /usr/bin/mailq.OFF
 472 </pre>
 473
 474 </ul>
 475
 476 <h3>6.2 - Create account and groups</h3>
 477
 478 <p> Before you install Postfix for the first time you need to
 479 create an account and a group:</p>
 480
 481 <ul>
 482
 483 <li> <p> Create a user account "postfix" with a user id and group
 484 id that are not used by any other user account.  Preferably, this
 485 is an account that no-one can log into.  The account does not need
 486 an executable login shell, and needs no existing home directory.
 487 My password and group file entries look like this: </p>
 488
 489 <blockquote>
 490 <pre>
 491 /etc/passwd:
 492     postfix:*:12345:12345:postfix:/no/where:/no/shell
 493
 494 /etc/group:
 495     postfix:*:12345:
 496 </pre>
 497 </blockquote>
 498
 499 <p> Note: there should be no whitespace before "postfix:". </p>
 500
 501 <li> <p> Create a group "postdrop" with a group id that is not used
 502 by any other user account. Not even by the postfix user account.
 503 My group file entry looks like:
 504
 505 <blockquote>
 506 <pre>
 507 /etc/group:
 508     postdrop:*:54321:
 509 </pre>
 510 </blockquote>
 511
 512 <p> Note: there should be no whitespace before "postdrop:". </p>
 513
 514 </ul>
 515
 516 <h3>6.3 - Install Postfix</h3>
 517
 518 <p> To install or upgrade Postfix from compiled source code, run
 519 one of the following commands as the super-user:</p>
 520
 521 <blockquote>
 522 <pre>
 523 # make install       (interactive version, first time install)
 524
 525 # make upgrade       (non-interactive version, for upgrades)
 526 </pre>
 527 </blockquote>
 528
 529 <ul>
 530
 531 <li> <p> The interactive version ("make install") asks for pathnames
 532 for Postfix data and program files, and stores your preferences in
 533 the <a href="postconf.5.html">main.cf</a> file. <b> If you don't want Postfix to overwrite
 534 non-Postfix "sendmail", "mailq" and "newaliases" files, specify
 535 pathnames that end in ".postfix"</b>. </p>
 536
 537 <li> <p> The non-interactive version ("make upgrade") needs the
 538 /etc/postfix/<a href="postconf.5.html">main.cf</a> file from a previous installation. If the file
 539 does not exist, use interactive installation ("make install")
 540 instead. </p>
 541
 542 </ul>
 543
 544 <h3>6.4 - Configure Postfix</h3>
 545
 546 <p> Proceed to the section on how you wish to run Postfix on
 547 your particular machine: </p>
 548
 549 <ul>
 550
 551 <li> <p> <a href="#send_only">Send</a> mail only, without changing
 552 an existing Sendmail installation (section 7). </p>
 553
 554 <li> <p> <a href="#send_receive">Send and receive</a> mail via a
 555 virtual host interface, still without any change to an existing
 556 Sendmail installation (section 8). </p>
 557
 558 <li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail
 559 (section 9). </p>
 560
 561 </ul>
 562
 563 <h2><a name="send_only">7 - Configuring Postfix to send mail
 564 only</a></h2>
 565
 566 <p> If you are going to use Postfix to send mail only, there is no
 567 need to change your existing sendmail setup. Instead, set up your
 568 mail user agent so that it calls the Postfix sendmail program
 569 directly. </p>
 570
 571 <p> Follow the instructions in the "<a href="#mandatory">Mandatory
 572 configuration file edits</a>" in section 10, and review the "<a
 573 href="#hamlet">To chroot or not to chroot</a>" text in section
 574 11. </p>
 575
 576 <p> You MUST comment out the "smtp inet" entry in /etc/postfix/<a href="master.5.html">master.cf</a>,
 577 in order to avoid conflicts with the real sendmail. Put a "#"
 578 character in front of the line that defines the smtpd service: </p>
 579
 580 <blockquote>
 581 <pre>
 582 /etc/postfix/<a href="master.5.html">master.cf</a>:
 583     #smtp      inet  n       -       n       -       -       smtpd
 584 </pre>
 585 </blockquote>
 586
 587 <p> Start the Postfix system: </p>
 588
 589 <blockquote>
 590 <pre>
 591 # postfix start
 592 </pre>
 593 </blockquote>
 594
 595 <p> or, if you feel nostalgic, use the Postfix sendmail command: </p>
 596
 597 <blockquote>
 598 <pre>
 599 # sendmail -bd -qwhatever
 600 </pre>
 601 </blockquote>
 602
 603 <p> and watch your maillog file for any error messages. The pathname
 604 is /var/log/maillog, /var/log/mail, /var/log/syslog, or something
 605 else. Typically, the pathname is defined in the /etc/syslog.conf
 606 file. </p>
 607
 608 <blockquote>
 609 <pre>
 610 % egrep '(reject|warning|error|fatal|panic):' /some/log/file
 611 </pre>
 612 </blockquote>
 613
 614 <p> Note: the most important error message is logged first. Later
 615 messages are not as useful. </p>
 616
 617 <p> In order to inspect the mail queue, use one of the following
 618 commands: </p>
 619
 620 <blockquote>
 621 <pre>
 622 % mailq
 623
 624 % sendmail -bp
 625
 626 % postqueue -p
 627 </pre>
 628 </blockquote>
 629
 630 <p> See also the "<a href="#care">Care and feeding</a>" section 12
 631 below.  </p>
 632
 633 <h2><a name="send_receive">8 - Configuring Postfix to send and
 634 receive mail via virtual interface</a></h2>
 635
 636 <p> Alternatively, you can use the Postfix system to send AND
 637 receive mail while leaving your Sendmail setup intact, by running
 638 Postfix on a virtual interface address.  Simply configure your mail
 639 user agent to directly invoke the Postfix sendmail program.  </p>
 640
 641 <p> To create a virtual network interface address, study your
 642 system ifconfig manual page. The command syntax could be any
 643 of: </p>
 644
 645 <blockquote>
 646 <pre>
 647 # <b>ifconfig le0:1 &lt;address&gt; netmask &lt;mask&gt; up</b>
 648 # <b>ifconfig en0 alias &lt;address&gt; netmask 255.255.255.255</b>
 649 </pre>
 650 </blockquote>
 651
 652 <p> In the /etc/postfix/<a href="postconf.5.html">main.cf</a> file, I would specify </p>
 653
 654 <blockquote>
 655 <pre>
 656 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 657     <a href="postconf.5.html#myhostname">myhostname</a> = virtual.host.tld
 658     <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 659     <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 660 </pre>
 661 </blockquote>
 662
 663 <p> Follow the instructions in the "<a href="#mandatory">Mandatory
 664 configuration file edits</a>" in section 10, and review the "<a
 665 name="#hamlet">To chroot or not to chroot</a>" text in section
 666 11. </p>
 667
 668 <p> Start the Postfix system: </p>
 669
 670 <blockquote>
 671 <pre>
 672 # postfix start
 673 </pre>
 674 </blockquote>
 675
 676 <p> or, if you feel nostalgic, use the Postfix sendmail command: </p>
 677
 678 <blockquote>
 679 <pre>
 680 # sendmail -bd -qwhatever
 681 </pre>
 682 </blockquote>
 683
 684 <p> and watch your maillog file for any error messages. The pathname
 685 is /var/log/maillog, /var/log/mail, /var/log/syslog, or something
 686 else. Typically, the pathname is defined in the /etc/syslog.conf
 687 file. </p>
 688
 689 <blockquote>
 690 <pre>
 691 % egrep '(reject|warning|error|fatal|panic):' /some/log/file
 692 </pre>
 693 </blockquote>
 694
 695 <p> Note: the most important error message is logged first. Later
 696 messages are not as useful. </p>
 697
 698 <p> In order to inspect the mail queue, use one of the following
 699 commands: </p>
 700
 701 <blockquote>
 702 <pre>
 703 % mailq
 704
 705 % sendmail -bp
 706
 707 % postqueue -p
 708 </pre>
 709 </blockquote>
 710
 711 <p> See also the "<a href="#care">Care and feeding</a>" section 12
 712 below.  </p>
 713
 714 <h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2>
 715
 716 <p> Prior to installing Postfix you should <a href="#save">save</a>
 717 any existing sendmail program files as described in section 6.  Be
 718 sure to keep the old sendmail running for at least a couple days
 719 to flush any unsent mail. To do so, stop the sendmail daemon and
 720 restart it as: </p>
 721
 722 <blockquote>
 723 <pre>
 724 # /usr/sbin/sendmail.OFF -q
 725 </pre>
 726 </blockquote>
 727
 728 <p> Note: this is old sendmail syntax. Newer versions use separate
 729 processes for mail submission and for running the queue. </p>
 730
 731 <p> After you have visited the "<a href="#mandatory">Mandatory
 732 configuration file edits</a>" section below, you can start the
 733 Postfix system with: </p>
 734
 735 <blockquote>
 736 <pre>
 737 # postfix start
 738 </pre>
 739 </blockquote>
 740
 741 <p> or, if you feel nostalgic, use the Postfix sendmail command: </p>
 742
 743 <blockquote>
 744 <pre>
 745 # sendmail -bd -qwhatever
 746 </pre>
 747 </blockquote>
 748
 749 <p> and watch your maillog file for any error messages. The pathname
 750 is /var/log/maillog, /var/log/mail, /var/log/syslog, or something
 751 else. Typically, the pathname is defined in the /etc/syslog.conf
 752 file. </p>
 753
 754 <blockquote>
 755 <pre>
 756 % egrep '(reject|warning|error|fatal|panic):' /some/log/file
 757 </pre>
 758 </blockquote>
 759
 760 <p> Note: the most important error message is logged first. Later
 761 messages are not as useful. </p>
 762
 763 <p> In order to inspect the mail queue, use one of the following
 764 commands: </p>
 765
 766 <blockquote>
 767 <pre>
 768 % mailq
 769
 770 % sendmail -bp
 771
 772 % postqueue -p
 773 </pre>
 774 </blockquote>
 775
 776 <p> See also the "<a href="#care">Care and feeding</a>" section 12
 777 below.  </p>
 778
 779 <h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2>
 780
 781 <p> Note: the material covered in this section is covered in more
 782 detail in the <a href="BASIC_CONFIGURATION_README.html">BASIC_CONFIGURATION_README</a> document. The information
 783 presented below is targeted at experienced system administrators.
 784 </p>
 785
 786 <h3>10.1 - Postfix configuration files</h3>
 787
 788 <p> By default, Postfix configuration files are in /etc/postfix.
 789 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
 790 must be owned by root.  Giving someone else write permission to
 791 <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a> (or to their parent directories) means giving
 792 root privileges to that person. </p>
 793
 794 <p> In /etc/postfix/<a href="postconf.5.html">main.cf</a>, you will have to set up a minimal number
 795 of configuration parameters.  Postfix configuration parameters
 796 resemble shell variables, with two important differences: the first
 797 one is that Postfix does not know about quotes like the UNIX shell
 798 does.</p>
 799
 800 <p> You specify a configuration parameter as: </p>
 801
 802 <blockquote>
 803 <pre>
 804 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 805     parameter = value
 806 </pre>
 807 </blockquote>
 808
 809 <p> and you use it by putting a "$" character in front of its name: </p>
 810
 811 <blockquote>
 812 <pre>
 813 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 814     other_parameter = $parameter
 815 </pre>
 816 </blockquote>
 817
 818 <p> You can use $parameter before it is given a value (that is the
 819 second main difference with UNIX shell variables). The Postfix
 820 configuration language uses lazy evaluation, and does not look at
 821 a parameter value until it is needed at runtime.  </p>
 822
 823 <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,
 824 execute the following command in order to refresh a running mail
 825 system: </p>
 826
 827 <blockquote>
 828 <pre>
 829 # postfix reload
 830 </pre>
 831 </blockquote>
 832
 833 <h3>10.2 - Default domain for unqualified addresses</h3>
 834
 835 <p> First of all, you must specify what domain will be appended to an
 836 unqualified address (i.e. an address without @domain.tld). The
 837 "<a href="postconf.5.html#myorigin">myorigin</a>" parameter defaults to the local hostname, but that is
 838 probably OK only for very small sites.  </p>
 839
 840 <p> Some examples (use only one): </p>
 841
 842 <blockquote>
 843 <pre>
 844 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 845     <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>")
 846     <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>")
 847 </pre>
 848 </blockquote>
 849
 850 <h3>10.3 - What domains to receive locally</h3>
 851
 852 <p> Next you need to specify what mail addresses Postfix should deliver
 853 locally. </p>
 854
 855 <p> Some examples (use only one): </p>
 856
 857 <blockquote>
 858 <pre>
 859 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 860     <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
 861     <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>
 862     <a href="postconf.5.html#mydestination">mydestination</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
 863 </pre>
 864 </blockquote>
 865
 866 <p>The first example is appropriate for a workstation, the second
 867 is appropriate for the mailserver for an entire domain. The third
 868 example should be used when running on a virtual host interface.</p>
 869
 870 <h3>10.4 - Proxy/NAT interface addresses </h3>
 871
 872 <p> The <a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> parameter specifies all network addresses
 873 that Postfix receives mail on by way of a proxy or network address
 874 translation unit. You may specify symbolic hostnames instead of
 875 network addresses. </p>
 876
 877 <p> IMPORTANT: You must specify your proxy/NAT external addresses
 878 when your system is a backup MX host for other domains, otherwise
 879 mail delivery loops will happen when the primary MX host is down.
 880 </p>
 881
 882 <p> Example: host behind NAT box running a backup MX host. </p>
 883
 884 <blockquote>
 885 <pre>
 886 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 887     <a href="postconf.5.html#proxy_interfaces">proxy_interfaces</a> = 1.2.3.4 (the proxy/NAT external network address)
 888 </pre>
 889 </blockquote>
 890
 891 <h3>10.5 - What local clients to relay mail from </h3>
 892
 893 <p> If your machine is on an open network then you must specify
 894 what client IP addresses are authorized to relay their mail through
 895 your machine into the Internet.  The default setting includes all
 896 subnetworks that the machine is attached to. This may give relay
 897 permission to too many clients.  My own settings are: </p>
 898
 899 <blockquote>
 900 <pre>
 901 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 902     <a href="postconf.5.html#mynetworks">mynetworks</a> = 168.100.189.0/28, 127.0.0.0/8
 903 </pre>
 904 </blockquote>
 905
 906 <h3>10.6 - What relay destinations to accept from strangers </h3>
 907
 908 <p> If your machine is on an open network then you must also specify
 909 whether Postfix will forward mail from strangers.  The default
 910 setting will forward mail to all domains (and subdomains of) what
 911 is listed in $<a href="postconf.5.html#mydestination">mydestination</a>.  This may give relay permission for
 912 too many destinations.  Recommended settings (use only one): </p>
 913
 914 <blockquote>
 915 <pre>
 916 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 917     <a href="postconf.5.html#relay_domains">relay_domains</a> =            (do not forward mail from strangers)
 918     <a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydomain">mydomain</a>  (my domain and subdomains)
 919     <a href="postconf.5.html#relay_domains">relay_domains</a> = $<a href="postconf.5.html#mydomain">mydomain</a>, other.domain.tld, ...
 920 </pre>
 921 </blockquote>
 922
 923 <h3>10.7 - Optional: configure a smart host for remote delivery</h3>
 924
 925 <p> If you're behind a firewall, you should set up a <a href="postconf.5.html#relayhost">relayhost</a>.  If
 926 you can, specify the organizational domain name so that Postfix
 927 can use DNS lookups, and so that it can fall back to a secondary
 928 MX host when the primary MX host is down. Otherwise just specify
 929 a hard-coded hostname.  </p>
 930
 931 <p> Some examples (use only one): </p>
 932
 933 <blockquote>
 934 <pre>
 935 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 936     <a href="postconf.5.html#relayhost">relayhost</a> = $<a href="postconf.5.html#mydomain">mydomain</a>
 937     <a href="postconf.5.html#relayhost">relayhost</a> = [mail.$<a href="postconf.5.html#mydomain">mydomain</a>]
 938 </pre>
 939 </blockquote>
 940
 941 <p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p>
 942
 943 <p> By default, the SMTP client will do DNS lookups even when you
 944 specify a <a href="postconf.5.html#relayhost">relay host</a>. If your machine has no access to a DNS server,
 945 turn off SMTP client DNS lookups like this: </p>
 946
 947 <blockquote>
 948 <pre>
 949 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 950     <a href="postconf.5.html#disable_dns_lookups">disable_dns_lookups</a> = yes
 951 </pre>
 952 </blockquote>
 953
 954 <p> The <a href="STANDARD_CONFIGURATION_README.html">STANDARD_CONFIGURATION_README</a> file has more hints and tips for
 955 firewalled and/or dial-up networks. </p>
 956
 957 <h3>10.8 - Create the aliases database</h3>
 958
 959 <p> Postfix uses a Sendmail-compatible <a href="aliases.5.html">aliases(5)</a> table to redirect
 960 mail for <a href="local.8.html">local(8)</a> recipients.  Typically, this information is kept
 961 in two files: in a text file /etc/aliases and in an indexed file
 962 /etc/aliases.db.  The command "postconf <a href="postconf.5.html#alias_maps">alias_maps</a>" will tell you
 963 the exact location of the text file.  </p>
 964
 965 <p> First, be sure to update the text file with aliases for root,
 966 postmaster and "postfix" that forward mail to a real person.  Postfix
 967 has a sample aliases file /etc/postfix/aliases that you can adapt
 968 to local conditions.  </p>
 969
 970 <blockquote>
 971 <pre>
 972 /etc/aliases:
 973     root: you
 974     postmaster: root
 975     postfix: root
 976     bin: root
 977     <i>etcetera...</i>
 978 </pre>
 979 </blockquote>
 980
 981 <p> Note: there should be no whitespace before the ":". </p>
 982
 983 <p> Finally, build the indexed aliases file with one of the
 984 following commands: </p>
 985
 986 <blockquote>
 987 <pre>
 988 # newaliases
 989 # sendmail -bi
 990 </pre>
 991 </blockquote>
 992
 993 <h2><a name="hamlet">11 - To chroot or not to chroot</a></h2>
 994
 995 <p> Postfix daemon processes can be configured (via <a href="master.5.html">master.cf</a>) to
 996 run in a chroot jail.  The processes run at a fixed low privilege
 997 and with access only to the Postfix queue directories (/var/spool/postfix).
 998 This provides a significant barrier against intrusion. The barrier
 999 is not impenetrable, but every little bit helps. </p>
1000
1001 <p> With the exception of Postfix daemons that deliver mail locally
1002 and/or that execute non-Postfix commands, every Postfix daemon can
1003 run chrooted. </p>
1004
1005 <p> Sites with high security requirements should consider to chroot
1006 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>
1007 processes, and perhaps also the <a href="lmtp.8.html">lmtp(8)</a> client. The author's own
1008 porcupine.org mail server runs all daemons chrooted that can be
1009 chrooted. </p>
1010
1011 <p> The default /etc/postfix/<a href="master.5.html">master.cf</a> file specifies that no
1012 Postfix daemon runs chrooted.  In order to enable chroot operation,
1013 edit the file /etc/postfix/<a href="master.5.html">master.cf</a>. Instructions are in the file.
1014 </p>
1015
1016 <p> Note that a chrooted daemon resolves all filenames relative to
1017 the Postfix queue directory (/var/spool/postfix). For successful
1018 use of a chroot jail,  most UNIX systems require you to bring in
1019 some files or device nodes.  The examples/chroot-setup directory
1020 in the source code distribution has a collection of scripts that
1021 help you set up Postfix chroot environments on different operating
1022 systems. </p>
1023
1024 <p> Additionally, you almost certainly need to configure syslogd
1025 so that it listens on a socket inside the Postfix queue directory.
1026 Examples for specific systems: </p>
1027
1028 <dl>
1029
1030 <dt> FreeBSD: </dt>
1031
1032 <dd> <pre>
1033 # mkdir -p /var/spool/postfix/var/run
1034 # syslogd -l /var/spool/postfix/var/run/log
1035 </pre> </dd>
1036
1037 <dt> Linux, OpenBSD: </dt>
1038
1039 <dd> <pre>
1040 # mkdir -p /var/spool/postfix/dev
1041 # syslogd -a /var/spool/postfix/dev/log
1042 </pre> </dd>
1043
1044 </dl>
1045
1046 <h2><a name="care">12 - Care and feeding of the Postfix system</a></h2>
1047
1048 <p> Postfix daemon processes run in the background, and log problems
1049 and normal activity to the syslog daemon. The names of logfiles
1050 are specified in /etc/syslog.conf. At the very least you need
1051 something like:  </p>
1052
1053 <blockquote>
1054 <pre>
1055 /etc/syslog.conf:
1056     mail.err                                    /dev/console
1057     mail.debug                                  /var/log/maillog
1058 </pre>
1059 </blockquote>
1060
1061 <p> IMPORTANT: the syslogd will not create files. You must create
1062 them before (re)starting syslogd. </p>
1063
1064 <p> IMPORTANT: on Linux you need to put a "-" character before
1065 the pathname, e.g., -/var/log/maillog, otherwise the syslogd
1066 will use more system resources than Postfix does. </p>
1067
1068 <p> Hopefully, the number of problems will be small, but it is a good
1069 idea to run every night before the syslog files are rotated: </p>
1070
1071 <blockquote>
1072 <pre>
1073 # postfix check
1074 # egrep '(reject|warning|error|fatal|panic):' /some/log/file
1075 </pre>
1076 </blockquote>
1077
1078 <ul>
1079
1080 <li> <p> The first line (postfix check) causes Postfix to report
1081 file permission/ownership discrepancies. </p>
1082
1083 <li> <p> The second line looks for problem reports from the mail
1084 software, and reports how effective the relay and junk mail access
1085 blocks are.  This may produce a lot of output.  You will want to
1086 apply some postprocessing to eliminate uninteresting information.
1087 </p>
1088
1089 </ul>
1090
1091 <p>  The <a href="DEBUG_README.html#logging"> DEBUG_README </a>
1092 document describes the meaning of the "warning" etc. labels in
1093 Postfix logging. </p>
1094
1095 </body>
1096
1097 </html>