INSTALL.html revision 1.9
1 1.1 tron <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 1.1 tron "http://www.w3.org/TR/html4/loose.dtd"> 3 1.1 tron 4 1.1 tron <html> 5 1.1 tron 6 1.1 tron <head> 7 1.1 tron 8 1.1 tron <title>Postfix Installation From Source Code </title> 9 1.1 tron 10 1.9 christos <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11 1.1 tron 12 1.1 tron </head> 13 1.1 tron 14 1.1 tron <body> 15 1.1 tron 16 1.1 tron <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 17 1.1 tron Installation From Source Code </h1> 18 1.1 tron 19 1.1 tron <hr> 20 1.1 tron 21 1.1 tron <h2> <a name="1">1 - Purpose of this document</a> </h2> 22 1.1 tron 23 1.1 tron <p> If you are using a pre-compiled version of Postfix, you should 24 1.1 tron start with BASIC_CONFIGURATION_README and the general documentation 25 1.1 tron referenced by it. INSTALL is only a bootstrap document to get 26 1.1 tron Postfix up and running from scratch with the minimal number of 27 1.1 tron steps; it should not be considered part of the general documentation. 28 1.1 tron </p> 29 1.1 tron 30 1.1 tron <p> This document describes how to build, install and configure a 31 1.1 tron Postfix system so that it can do one of the following: </p> 32 1.1 tron 33 1.1 tron <ul> 34 1.1 tron 35 1.1 tron <li> Send mail only, without changing an existing Sendmail 36 1.1 tron installation. 37 1.1 tron 38 1.1 tron <li> Send and receive mail via a virtual host interface, still 39 1.1 tron without any change to an existing Sendmail installation. 40 1.1 tron 41 1.1 tron <li> Run Postfix instead of Sendmail. 42 1.1 tron 43 1.1 tron </ul> 44 1.1 tron 45 1.1 tron <p> Topics covered in this document: </p> 46 1.1 tron 47 1.1 tron <ol> 48 1.1 tron 49 1.1 tron <li> <a href="#1">Purpose of this document</a> 50 1.1 tron 51 1.1 tron <li> <a href="#2">Typographical conventions</a> 52 1.1 tron 53 1.1 tron <li> <a href="#3">Documentation</a> 54 1.1 tron 55 1.1 tron <li> <a href="#4">Building on a supported system</a> 56 1.1 tron 57 1.1 tron <li> <a href="#5">Porting Postfix to an unsupported system</a> 58 1.1 tron 59 1.1 tron <li> <a href="#install">Installing the software after successful 60 1.1 tron compilation </a> 61 1.1 tron 62 1.1 tron <li> <a href="#send_only">Configuring Postfix to send mail 63 1.1 tron only </a> 64 1.1 tron 65 1.1 tron <li> <a href="#send_receive">Configuring Postfix to send and 66 1.1 tron receive mail via virtual interface </a> 67 1.1 tron 68 1.1 tron <li> <a href="#replace">Running Postfix instead of Sendmail</a> 69 1.1 tron 70 1.1 tron <li> <a href="#mandatory">Mandatory configuration file edits</a> 71 1.1 tron 72 1.1 tron <li> <a href="#hamlet">To chroot or not to chroot</a> 73 1.1 tron 74 1.1 tron <li> <a href="#care">Care and feeding of the Postfix system</a> 75 1.1 tron 76 1.1 tron </ol> 77 1.1 tron 78 1.1 tron <h2> <a name="2">2 - Typographical conventions</a> </h2> 79 1.1 tron 80 1.1 tron <p> In the instructions below, a command written as </p> 81 1.1 tron 82 1.1 tron <blockquote> 83 1.1 tron <pre> 84 1.1 tron # command 85 1.1 tron </pre> 86 1.1 tron </blockquote> 87 1.1 tron 88 1.1 tron <p> should be executed as the superuser. </p> 89 1.1 tron 90 1.1 tron <p> A command written as </p> 91 1.1 tron 92 1.1 tron <blockquote> 93 1.1 tron <pre> 94 1.5 tron $ command 95 1.1 tron </pre> 96 1.1 tron </blockquote> 97 1.1 tron 98 1.1 tron <p> should be executed as an unprivileged user. </p> 99 1.1 tron 100 1.1 tron <h2> <a name="3">3 - Documentation</a> </h2> 101 1.1 tron 102 1.1 tron <p> Documentation is available as README files (start with the file 103 1.1 tron README_FILES/AAAREADME), as HTML web pages (point your browser to 104 1.1 tron "html/index.html") and as UNIX-style manual pages. </p> 105 1.1 tron 106 1.1 tron <p> You should view the README files with a pager such as more(1) 107 1.1 tron or less(1), because the files use backspace characters in order to 108 1.1 tron produce <b>bold</b> font. To print a README file without backspace 109 1.1 tron characters, use the col(1) command. For example: </p> 110 1.1 tron 111 1.1 tron <blockquote> 112 1.1 tron <pre> 113 1.5 tron $ col -bx <file | lpr 114 1.1 tron </pre> 115 1.1 tron </blockquote> 116 1.1 tron 117 1.1 tron <p> In order to view the manual pages before installing Postfix, 118 1.1 tron point your MANPATH environment variable to the "man" subdirectory; 119 1.1 tron be sure to use an absolute path. </p> 120 1.1 tron 121 1.1 tron <blockquote> 122 1.1 tron <pre> 123 1.5 tron $ export MANPATH; MANPATH="`pwd`/man:$MANPATH" 124 1.5 tron $ setenv MANPATH "`pwd`/man:$MANPATH" 125 1.1 tron </pre> 126 1.1 tron </blockquote> 127 1.1 tron 128 1.1 tron <p> Of particular interest is the postconf(5) manual page that 129 1.1 tron lists all the 500+ configuration parameters. The HTML version of 130 1.1 tron this text makes it easy to navigate around. </p> 131 1.1 tron 132 1.1 tron <p> All Postfix source files have their own built-in manual page. 133 1.1 tron Tools to extract those embedded manual pages are available in the 134 1.1 tron mantools directory. </p> 135 1.1 tron 136 1.1 tron <h2> <a name="4">4 - Building on a supported system</a> </h2> 137 1.1 tron 138 1.7 christos <p> Postfix development happens on FreeBSD and MacOS X, with regular 139 1.7 christos tests on Linux (Fedora, Ubuntu) and Solaris. Support for other 140 1.7 christos systems relies on feedback from their users, and may not always be 141 1.7 christos up-to-date. </p> 142 1.7 christos 143 1.7 christos <p> OpenBSD is partially supported. The libc resolver does not 144 1.7 christos implement the documented "internal resolver options which are [...] 145 1.7 christos set by changing fields in the _res structure" (documented in the 146 1.7 christos OpenBSD 5.6 resolver(3) manpage). This results in too many DNS 147 1.7 christos queries, and false positives for queries that should fail. </p> 148 1.7 christos 149 1.7 christos <!-- 150 1.7 christos 151 1.1 tron <p> At some point in time, a version of Postfix was supported on: </p> 152 1.1 tron 153 1.1 tron <blockquote> 154 1.1 tron <p> 155 1.1 tron AIX 3.2.5, 4.1.x, 4.2.0, 4.3.x, 5.2 <br> 156 1.1 tron BSD/OS 2.x, 3.x, 4.x <br> 157 1.5 tron FreeBSD 2.x .. 9.x <br> 158 1.1 tron HP-UX 9.x, 10.x, 11.x <br> 159 1.1 tron IRIX 5.x, 6.x <br> 160 1.5 tron Linux Debian 1.3.1 and later <br> 161 1.5 tron Linux RedHat 3.x (January 2004) and later <br> 162 1.5 tron Linux Slackware 3.x and later <br> 163 1.5 tron Linux SuSE 5.x and later <br> 164 1.5 tron Linux Ubuntu 4.10 and later<br> 165 1.1 tron Mac OS X <br> 166 1.1 tron NEXTSTEP 3.x <br> 167 1.5 tron NetBSD 1.x and later <br> 168 1.1 tron OPENSTEP 4.x <br> 169 1.1 tron OSF1.V3 - OSF1.V5 (Digital UNIX) <br> 170 1.1 tron Reliant UNIX 5.x <br> 171 1.1 tron SunOS 4.1.4 (March 2007) <br> 172 1.1 tron SunOS 5.4 - 5.10 (Solaris 2.4..10) <br> 173 1.1 tron Ultrix 4.x (well, that was long ago) <br> 174 1.1 tron </p> 175 1.1 tron </blockquote> 176 1.1 tron 177 1.1 tron <p> or something closely resemblant. </p> 178 1.1 tron 179 1.7 christos --> 180 1.7 christos 181 1.7 christos <p> Overview of topics: </p> 182 1.7 christos 183 1.7 christos <ul> 184 1.7 christos 185 1.7 christos <li><a href="#build_first">4.1 - Getting started</a> 186 1.7 christos 187 1.7 christos <li><a href="#build_cc">4.2 - What compiler to use</a> 188 1.7 christos 189 1.7 christos <li><a href="#build_pie">4.3 - Building with Postfix position-independent 190 1.7 christos executables (Postfix ≥ 3.0)</a> 191 1.7 christos 192 1.7 christos <li><a href="#build_dll">4.4 - Building with Postfix dynamically-linked 193 1.7 christos libraries and database plugins (Postfix ≥ 3.0)</a> 194 1.7 christos 195 1.7 christos <li><a href="#build_opt">4.5 - Building with optional features</a> 196 1.7 christos 197 1.7 christos <li><a href="#build_over">4.6 - Overriding built-in parameter default 198 1.7 christos settings</a> 199 1.7 christos 200 1.7 christos <li><a href="#build_other">4.7 - Overriding other compile-time 201 1.7 christos features</a> 202 1.1 tron 203 1.7 christos <li><a href="#build_proc">4.8 - Support for thousands of processes</a> 204 1.7 christos 205 1.7 christos <li><a href="#build_final">4.9 - Compiling Postfix, at last</a> 206 1.7 christos 207 1.7 christos </ul> 208 1.7 christos 209 1.7 christos 210 1.7 christos <h3><a name="build_first">4.1 - Getting started</a> </h3> 211 1.7 christos 212 1.7 christos <p> On Solaris, the "make" command and other development utilities 213 1.7 christos are in /usr/ccs/bin, so you MUST have /usr/ccs/bin in your command 214 1.7 christos search path. If these files do not exist, you need to install the 215 1.7 christos development packages first. </p> 216 1.7 christos 217 1.7 christos <p> If you need to build Postfix for multiple architectures from a 218 1.7 christos single source-code tree, use the "lndir" command to build a shadow 219 1.7 christos tree with symbolic links to the source files. </p> 220 1.1 tron 221 1.1 tron <p> If at any time in the build process you get messages like: "make: 222 1.1 tron don't know how to ..." you should be able to recover by running 223 1.1 tron the following command from the Postfix top-level directory: </p> 224 1.1 tron 225 1.1 tron <blockquote> 226 1.1 tron <pre> 227 1.5 tron $ make -f Makefile.init makefiles 228 1.1 tron </pre> 229 1.1 tron </blockquote> 230 1.1 tron 231 1.1 tron <p> If you copied the Postfix source code after building it on another 232 1.1 tron machine, it is a good idea to cd into the top-level directory and 233 1.1 tron first do this:</p> 234 1.1 tron 235 1.1 tron <blockquote> 236 1.1 tron <pre> 237 1.5 tron $ make tidy 238 1.1 tron </pre> 239 1.1 tron </blockquote> 240 1.1 tron 241 1.1 tron <p> This will get rid of any system dependencies left over from 242 1.1 tron compiling the software elsewhere. </p> 243 1.1 tron 244 1.7 christos <h3><a name="build_cc">4.2 - What compiler to use</a></h3> 245 1.1 tron 246 1.1 tron <p> To build with GCC, or with the native compiler if people told me 247 1.1 tron that is better for your system, just cd into the top-level Postfix 248 1.1 tron directory of the source tree and type: </p> 249 1.1 tron 250 1.1 tron <blockquote> 251 1.1 tron <pre> 252 1.5 tron $ make 253 1.1 tron </pre> 254 1.1 tron </blockquote> 255 1.1 tron 256 1.1 tron <p> To build with a non-default compiler, you need to specify the name 257 1.1 tron of the compiler. Here are a few examples: </p> 258 1.1 tron 259 1.1 tron <blockquote> 260 1.1 tron <pre> 261 1.5 tron $ make makefiles CC=/opt/SUNWspro/bin/cc (Solaris) 262 1.5 tron $ make 263 1.1 tron 264 1.5 tron $ make makefiles CC="/opt/ansic/bin/cc -Ae" (HP-UX) 265 1.5 tron $ make 266 1.1 tron 267 1.5 tron $ make makefiles CC="purify cc" 268 1.5 tron $ make 269 1.1 tron </pre> 270 1.1 tron </blockquote> 271 1.1 tron 272 1.7 christos <p> and so on. In some cases, optimization will be turned off 273 1.7 christos automatically. </p> 274 1.7 christos 275 1.7 christos <h3><a name="build_pie">4.3 - Building with Postfix position-independent 276 1.7 christos executables (Postfix ≥ 3.0)</a> </h3> 277 1.7 christos 278 1.7 christos <p> On some systems Postfix can be built with Position-Independent 279 1.7 christos Executables. PIE is used by the ASLR exploit mitigation technique 280 1.7 christos (ASLR = Address-Space Layout Randomization): </p> 281 1.7 christos 282 1.7 christos <blockquote> 283 1.7 christos <pre> 284 1.7 christos $ make makefiles pie=yes ...other arguments... 285 1.7 christos </pre> 286 1.7 christos </blockquote> 287 1.7 christos 288 1.7 christos <p> (Specify "make makefiles pie=no" to explicitly disable Postfix 289 1.7 christos position-independent executable support). </p> 290 1.7 christos 291 1.7 christos <p> Postfix PIE support appears to work on Fedora Core 20, Ubuntu 292 1.7 christos 14.04, FreeBSD 9 and 10, and NetBSD 6 (all with the default system 293 1.7 christos compilers). </p> 294 1.7 christos 295 1.7 christos <p> Whether the "pie=yes" above has any effect depends on the 296 1.7 christos compiler. Some compilers always produce PIE executables, and some 297 1.7 christos may even complain that the Postfix build option is redundant. </p> 298 1.7 christos 299 1.7 christos <h3><a name="build_dll">4.4 - Building with Postfix dynamically-linked 300 1.7 christos libraries and database plugins (Postfix ≥ 3.0)</a> </h3> 301 1.7 christos 302 1.7 christos <p> Postfix dynamically-linked library and database plugin support 303 1.7 christos exists for recent versions of Linux, FreeBSD and MacOS X. 304 1.7 christos Dynamically-linked library builds may become the default at some 305 1.7 christos point in the future. </p> 306 1.7 christos 307 1.7 christos <p> Overview of topics: </p> 308 1.7 christos 309 1.7 christos <ul> 310 1.7 christos 311 1.7 christos <li><a href="#shared_enable">4.4.1 Turning on Postfix dynamically-linked 312 1.7 christos library support</a> 313 1.7 christos 314 1.7 christos <li><a href="#dynamicmaps_enable">4.4.2 Turning on Postfix database-plugin 315 1.7 christos support</a> 316 1.7 christos 317 1.7 christos <li><a href="#shared_custom">4.4.3 Customizing Postfix dynamically-linked 318 1.7 christos libraries and database plugins</a> 319 1.7 christos 320 1.7 christos <li><a href="#shared_tips">4.4.4 Tips for distribution maintainers</a> 321 1.7 christos 322 1.7 christos </ul> 323 1.7 christos 324 1.7 christos <p> Note: directories with Postfix dynamically-linked libraries 325 1.7 christos or database plugins should contain only postfix-related files. 326 1.7 christos Postfix dynamically-linked libraries and database plugins should 327 1.7 christos not be installed in a "public" system directory such as /usr/lib 328 1.7 christos or /usr/local/lib. Linking Postfix dynamically-linked library or 329 1.7 christos database-plugin files into non-Postfix programs is not supported. 330 1.7 christos Postfix dynamically-linked libraries and database plugins implement 331 1.7 christos a Postfix-internal API that changes without maintaining compatibility. 332 1.7 christos </p> 333 1.7 christos 334 1.7 christos <h4><a name="shared_enable"> 4.4.1 Turning on Postfix dynamically-linked 335 1.7 christos library support </a></h4> 336 1.7 christos 337 1.7 christos <p> Postfix can be built with Postfix dynamically-linked libraries 338 1.7 christos (files typically named <tt>libpostfix-*.so</tt>). Postfix 339 1.7 christos dynamically-linked libraries add minor run-time overhead and result 340 1.7 christos in significantly-smaller Postfix executable files. </p> 341 1.7 christos 342 1.7 christos <p> Specify "shared=yes" on the "make makefiles" command line to 343 1.7 christos build Postfix with dynamically-linked library support. </p> 344 1.7 christos 345 1.7 christos <blockquote> 346 1.7 christos <pre> 347 1.7 christos $ make makefiles shared=yes ...other arguments... 348 1.7 christos $ make 349 1.7 christos </pre> 350 1.7 christos </blockquote> 351 1.7 christos 352 1.7 christos <p> (Specify "make makefiles shared=no" to explicitly disable Postfix 353 1.7 christos dynamically-linked library support). </p> 354 1.7 christos 355 1.7 christos <p> This installs dynamically-linked libraries in $shlib_directory, 356 1.7 christos typically /usr/lib/postfix or /usr/local/lib/postfix, with file 357 1.7 christos names libpostfix-<i>name</i>.so, where the <i>name</i> is a source-code 358 1.7 christos directory name such as "util" or "global". </p> 359 1.7 christos 360 1.7 christos <p> See section 4.4.3 "<a href="#shared_custom">Customizing Postfix 361 1.7 christos dynamically-linked libraries and database plugins</a>" below for 362 1.7 christos how to customize the Postfix dynamically-linked library location, 363 1.7 christos including support to upgrade a running mail system safely. </p> 364 1.7 christos 365 1.7 christos <h4><a name="dynamicmaps_enable"> 4.4.2 Turning on Postfix 366 1.7 christos database-plugin support </a></h4> 367 1.7 christos 368 1.7 christos <p> Additionally, Postfix can be built to support dynamic loading 369 1.7 christos of Postfix database clients (database plugins) with the Debian-style 370 1.7 christos dynamicmaps feature. Postfix 3.0 supports dynamic loading of cdb:, 371 1.7 christos ldap:, lmdb:, mysql:, pcre:, pgsql:, sdbm:, and sqlite: database 372 1.7 christos clients. Dynamic loading is useful when you distribute or install 373 1.7 christos pre-compiled Postfix packages. </p> 374 1.7 christos 375 1.7 christos <p> Specify "dynamicmaps=yes" on the "make makefiles" command line 376 1.7 christos to build Postfix with support to dynamically load Postfix database 377 1.7 christos clients with the Debian-style dynamicmaps feature. 378 1.7 christos </p> 379 1.7 christos 380 1.7 christos <blockquote> 381 1.7 christos <pre> 382 1.7 christos $ make makefiles dynamicmaps=yes ...other arguments... 383 1.7 christos $ make 384 1.7 christos </pre> 385 1.7 christos </blockquote> 386 1.7 christos 387 1.7 christos <p> (Specify "make makefiles dynamicmaps=no" to explicitly disable 388 1.7 christos Postfix database-plugin support). </p> 389 1.7 christos 390 1.7 christos <p> This implicitly enables dynamically-linked library support, 391 1.7 christos installs the configuration file dynamicmaps.cf in $meta_directory 392 1.7 christos (usually, /etc/postfix or /usr/local/etc/postfix), and installs 393 1.7 christos database plugins in $shlib_directory (see above). Database plugins 394 1.7 christos are named postfix-<i>type</i>.so where the <i>type</i> is a database 395 1.7 christos type such as "cdb" or "ldap". </p> 396 1.7 christos 397 1.7 christos <blockquote> 398 1.7 christos 399 1.7 christos <p> NOTE: The Postfix 3.0 build procedure expects that you specify 400 1.7 christos database library dependencies with variables named AUXLIBS_CDB, 401 1.7 christos AUXLIBS_LDAP, etc. With Postfix 3.0 and later, the old AUXLIBS 402 1.7 christos variable still supports building a statically-loaded database client, 403 1.7 christos but only the new AUXLIBS_CDB etc. variables support building a 404 1.7 christos dynamically-loaded or statically-loaded CDB etc. database client. 405 1.7 christos See CDB_README, LDAP_README, etc. for details. </p> 406 1.7 christos 407 1.7 christos <p> Failure to follow this advice will defeat the purpose of dynamic 408 1.7 christos database client loading. Every Postfix executable file will have 409 1.7 christos database library dependencies. And that was exactly what dynamic 410 1.7 christos database client loading was meant to avoid. </p> 411 1.7 christos 412 1.7 christos </blockquote> 413 1.7 christos 414 1.7 christos <p> See the next section for how to customize the location and 415 1.7 christos version of Postfix database plugins and the location of the file 416 1.7 christos dynamicmaps.cf. </p> 417 1.7 christos 418 1.7 christos <h4><a name="shared_custom"> 4.4.3 Customizing Postfix dynamically-linked 419 1.7 christos libraries and database plugins </a></h4> 420 1.7 christos 421 1.7 christos <h5> Customizing build-time and run-time options for Postfix 422 1.7 christos dynamically-linked libraries and database plugins </h5> 423 1.7 christos 424 1.7 christos <p> The build-time environment variables SHLIB_CFLAGS, SHLIB_RPATH, 425 1.7 christos and SHLIB_SUFFIX provide control over how Postfix libraries and 426 1.7 christos plugins are compiled, linked, and named. 427 1.7 christos 428 1.7 christos <blockquote> 429 1.7 christos <pre> 430 1.7 christos $ make makefiles SHLIB_CFLAGS=flags SHLIB_RPATH=rpath SHLIB_SUFFIX=suffix ...other arguments... 431 1.7 christos $ make 432 1.7 christos </pre> 433 1.7 christos </blockquote> 434 1.7 christos 435 1.7 christos <p> See section 4.7 "<a href="#build_other">Overriding other 436 1.7 christos compile-time features</a>" below for details. </p> 437 1.7 christos 438 1.7 christos <h5> Customizing the location of Postfix dynamically-linked libraries 439 1.7 christos and database plugins </h5> 440 1.7 christos 441 1.7 christos <p> As a reminder, the directories with Postfix dynamically-linked 442 1.7 christos libraries or database plugins should contain only Postfix-related 443 1.7 christos files. Linking these files into other programs is not supported. 444 1.7 christos </p> 445 1.7 christos 446 1.7 christos <p> To override the default location of Postfix dynamically-linked 447 1.7 christos libraries and database plugins specify, for example: </p> 448 1.7 christos 449 1.7 christos <blockquote> 450 1.7 christos <pre> 451 1.7 christos $ make makefiles shared=yes shlib_directory=/usr/local/lib/postfix ... 452 1.7 christos </pre> 453 1.7 christos </blockquote> 454 1.7 christos 455 1.7 christos <p> If you intend to upgrade Postfix without stopping the mail 456 1.7 christos system, then you should append the Postfix release version to the 457 1.7 christos shlib_directory pathname, to eliminate the possibility that programs 458 1.7 christos will link with dynamically-linked libraries or database plugins 459 1.7 christos from the wrong Postfix version. For example: </p> 460 1.7 christos 461 1.7 christos <blockquote> 462 1.7 christos <pre> 463 1.7 christos $ make makefiles shared=yes \ 464 1.7 christos shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... 465 1.7 christos </pre> 466 1.7 christos </blockquote> 467 1.7 christos 468 1.7 christos <p> The command "make makefiles name=value..." will replace the 469 1.7 christos string MAIL_VERSION at the end of a configuration parameter value 470 1.7 christos with the Postfix release version. Do not try to specify something 471 1.7 christos like $mail_version on this command line. This produces inconsistent 472 1.7 christos results with different versions of the make(1) command. </p> 473 1.7 christos 474 1.7 christos <p> You can change the shlib_directory setting after Postfix is 475 1.7 christos built, with "make install" or "make upgrade". However, you may have 476 1.7 christos to run ldconfig if you change shlib_directory after Postfix is built 477 1.7 christos (the symptom is that Postfix programs fail because the run-time 478 1.7 christos linker cannot find the files libpostfix-*.so). No ldconfig command 479 1.7 christos is needed if you keep the files libpostfix-*.so in the compiled-in 480 1.7 christos default $shlib_directory location. </p> 481 1.1 tron 482 1.7 christos <blockquote> 483 1.7 christos <pre> 484 1.7 christos # make upgrade shlib_directory=/usr/local/lib/postfix ... 485 1.7 christos # make install shlib_directory=/usr/local/lib/postfix ... 486 1.7 christos </pre> 487 1.7 christos </blockquote> 488 1.7 christos 489 1.7 christos <p> To append the Postfix release version to the pathname if you 490 1.7 christos intend to upgrade Postfix without stopping the mail system: </p> 491 1.7 christos 492 1.7 christos <blockquote> 493 1.7 christos <pre> 494 1.7 christos # make upgrade shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... 495 1.7 christos # make install shlib_directory=/usr/local/lib/postfix/MAIL_VERSION ... 496 1.7 christos </pre> 497 1.7 christos </blockquote> 498 1.7 christos 499 1.7 christos <p> See also the comments above for appending MAIL_VERSION with 500 1.7 christos the "make makefiles" command. </p> 501 1.7 christos 502 1.7 christos <h5> Customizing the location of dynamicmaps.cf and other files 503 1.7 christos </h5> 504 1.7 christos 505 1.7 christos <p> The meta_directory parameter has the same default setting as 506 1.7 christos the config_directory parameter, typically /etc/postfix or 507 1.7 christos /usr/local/etc/postfix. </p> 508 1.7 christos 509 1.7 christos <p> You can override the default meta_directory location at compile 510 1.7 christos time or after Postfix is built. To override the default location 511 1.7 christos at compile time specify, for example: </p> 512 1.7 christos 513 1.7 christos <blockquote> 514 1.7 christos <pre> 515 1.7 christos % make makefiles meta_directory=/usr/libexec/postfix ... 516 1.7 christos </pre> 517 1.7 christos </blockquote> 518 1.7 christos 519 1.7 christos <p> Here is a tip if you want to make a pathname dependent on the 520 1.7 christos Postfix release version: the command "make makefiles name=value..." 521 1.7 christos will replace the string MAIL_VERSION at the end of a configuration 522 1.7 christos parameter value with the Postfix release version. Do not try to 523 1.7 christos specify something like $mail_version on this command line. This 524 1.7 christos produces inconsistent results with different versions of the make(1) 525 1.7 christos command. </p> 526 1.7 christos 527 1.7 christos <p> You can override the meta_directory setting after Postfix is 528 1.7 christos built, with "make install" or "make upgrade". </p> 529 1.7 christos 530 1.7 christos <blockquote> 531 1.7 christos <pre> 532 1.7 christos # make upgrade meta_directory=/usr/libexec/postfix ... 533 1.7 christos # make install meta_directory=/usr/libexec/postfix ... 534 1.7 christos </pre> 535 1.7 christos </blockquote> 536 1.7 christos 537 1.9 christos <p> As with the command "make makefiles", the command "make 538 1.7 christos install/upgrade name=value..." will replace the string MAIL_VERSION 539 1.7 christos at the end of a configuration parameter value with the Postfix 540 1.7 christos release version. Do not try to specify something like $mail_version 541 1.7 christos on this command line. This produces inconsistent results with 542 1.7 christos different versions of the make(1) command. </p> 543 1.7 christos 544 1.7 christos <h4><a name="shared_tips"> 4.4.4 Tips for distribution maintainers 545 1.7 christos </a></h4> 546 1.7 christos 547 1.7 christos <ul> 548 1.7 christos 549 1.7 christos <li> <p> The shlib_directory parameter setting also provides the 550 1.7 christos default directory for database plugin files with a relative pathname 551 1.7 christos in the file dynamicmaps.cf. </p> 552 1.7 christos 553 1.7 christos <li> <p> The meta_directory parameter specifies the location of the 554 1.7 christos files dynamicmaps.cf, postfix-files, and some multi-instance template 555 1.7 christos files. The meta_directory parameter has the same default value as 556 1.7 christos the config_directory parameter (typically, /etc/postfix or 557 1.7 christos /usr/local/etc/postfix). For backwards compatibility with Postfix 558 1.7 christos 2.6 .. 2.11, specify "meta_directory = $daemon_directory" in main.cf 559 1.7 christos before installing or upgrading Postfix, or specify "meta_directory 560 1.7 christos = /path/name" on the "make makefiles", "make install" or "make 561 1.7 christos upgrade" command line. </p> 562 1.7 christos 563 1.7 christos <li> <p> The configuration file dynamicmaps.cf will automatically 564 1.7 christos include files under the directory dynamicmaps.cf.d, just like the 565 1.7 christos configuration file postfix-files will automatically include files 566 1.7 christos under the directory postfix-files.d. Thanks to this, you can install 567 1.7 christos or deinstall a database plugin package without having to edit 568 1.7 christos postfix-files or dynamicmaps.cf. Instead, you give that plugin its 569 1.8 christos own configuration files under dynamicmaps.cf.d and postfix-files.d, and 570 1.7 christos you add or remove those configuration files along with the database 571 1.7 christos plugin dynamically-linked object. </p> 572 1.7 christos 573 1.7 christos <li> <p> Each configuration file under the directory dynamicmaps.cf.d 574 1.7 christos must have the same format as the configuration file dynamicmaps.cf. 575 1.7 christos There is no requirement that these configuration file *names* have a 576 1.7 christos specific format. </p> 577 1.7 christos 578 1.7 christos <li> <p> Each configuration file under the directory postfix-files.d 579 1.7 christos must have the same format as the configuration file postfix-files. 580 1.7 christos There is no requirement that these configuration file *names* have a 581 1.7 christos specific format. </p> 582 1.7 christos 583 1.7 christos </ul> 584 1.7 christos 585 1.7 christos <h3><a name="build_opt">4.5 - Building with optional features</a></h3> 586 1.1 tron 587 1.1 tron By default, Postfix builds as a mail system with relatively few 588 1.1 tron bells and whistles. Support for third-party databases etc. 589 1.6 tron must be configured when Postfix is compiled. The following documents 590 1.6 tron describe how to build Postfix with support for optional features: 591 1.1 tron 592 1.1 tron <blockquote> 593 1.1 tron <table border="1"> 594 1.1 tron 595 1.6 tron <tr> <th>Optional feature </th> <th>Document </th> <th>Availability</th> 596 1.1 tron </tr> 597 1.1 tron 598 1.1 tron <tr> <td> Berkeley DB database</td> <td>DB_README</td> <td> Postfix 599 1.1 tron 1.0 </td> </tr> 600 1.1 tron 601 1.6 tron <tr> <td> LMDB database</td> <td>LMDB_README</td> <td> Postfix 602 1.6 tron 2.11 </td> </tr> 603 1.6 tron 604 1.1 tron <tr> <td> LDAP database</td> <td>LDAP_README</td> <td> Postfix 605 1.1 tron 1.0 </td> </tr> 606 1.1 tron 607 1.1 tron <tr> <td> MySQL database</td> <td>MYSQL_README</td> <td> Postfix 608 1.1 tron 1.0 </td> </tr> 609 1.1 tron 610 1.1 tron <tr> <td> Perl compatible regular expression</td> <td>PCRE_README</td> 611 1.1 tron <td> Postfix 1.0 </td> </tr> 612 1.1 tron 613 1.1 tron <tr> <td> PostgreSQL database</td> <td>PGSQL_README</td> <td> 614 1.1 tron Postfix 2.0 </td> </tr> 615 1.1 tron 616 1.1 tron <tr> <td> SASL authentication </td> <td>SASL_README</td> <td> 617 1.1 tron Postfix 1.0 </td> </tr> 618 1.1 tron 619 1.3 tron <tr> <td> SQLite database</td> <td>SQLITE_README</td> <td> Postfix 620 1.3 tron 2.8 </td> </tr> 621 1.3 tron 622 1.1 tron <tr> <td> STARTTLS session encryption </td> <td>TLS_README</td> <td> 623 1.1 tron Postfix 2.2 </td> </tr> 624 1.1 tron 625 1.1 tron </table> 626 1.1 tron 627 1.1 tron </blockquote> 628 1.1 tron 629 1.1 tron <p> Note: IP version 6 support is compiled into Postfix on operating 630 1.1 tron systems that have IPv6 support. See the IPV6_README file for details. 631 1.1 tron </p> 632 1.1 tron 633 1.7 christos <h3><a name="build_over">4.6 - Overriding built-in parameter default 634 1.7 christos settings</a></h3> 635 1.7 christos 636 1.7 christos <h4>4.6.1 - Postfix 3.0 and later </h4> 637 1.7 christos 638 1.7 christos <p> All Postfix configuration parameters can be changed by editing 639 1.7 christos a Postfix configuration file, except for one: the parameter that 640 1.7 christos specifies the location of Postfix configuration files. In order to 641 1.7 christos build Postfix with a configuration directory other than /etc/postfix, 642 1.7 christos use: </p> 643 1.7 christos 644 1.7 christos <blockquote> 645 1.7 christos <pre> 646 1.7 christos $ make makefiles config_directory=/some/where ...other arguments... 647 1.7 christos $ make 648 1.7 christos </pre> 649 1.7 christos </blockquote> 650 1.7 christos 651 1.7 christos <p> The command "make makefiles name=value ..." will replace the 652 1.7 christos string MAIL_VERSION at the end of a configuration parameter value 653 1.7 christos with the Postfix release version. Do not try to specify something 654 1.7 christos like $mail_version on this command line. This produces inconsistent 655 1.7 christos results with different versions of the make(1) command. </p> 656 1.7 christos 657 1.7 christos <p> Parameters whose defaults can be specified in this way are 658 1.7 christos listed below. See the postconf(5) manpage for a description 659 1.7 christos (command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> 660 1.7 christos 661 1.7 christos <blockquote> 662 1.7 christos 663 1.7 christos <table border="1"> 664 1.7 christos 665 1.7 christos <tr> <th>parameter name</th> <th>typical default</th> </tr> 666 1.7 christos 667 1.7 christos <tr> <td>command_directory</td> <td>/usr/sbin</td> </tr> 668 1.7 christos 669 1.7 christos <tr> <td>config_directory</td> <td>/etc/postfix</td> </tr> 670 1.7 christos 671 1.7 christos <tr> <td>default_database_type</td> <td>hash</td> </tr> 672 1.7 christos 673 1.7 christos <tr> <td>daemon_directory</td> <td>/usr/libexec/postfix</td> </tr> 674 1.7 christos 675 1.7 christos <tr> <td>data_directory</td> <td>/var/lib/postfix</td> </tr> 676 1.7 christos 677 1.7 christos <tr> <td>html_directory</td> <td>no</td> </tr> 678 1.7 christos 679 1.7 christos <tr> <td>mail_spool_directory</td> <td>/var/mail</td> </tr> 680 1.7 christos 681 1.7 christos <tr> <td>mailq_path</td> <td>/usr/bin/mailq</td> </tr> 682 1.7 christos 683 1.7 christos <tr> <td>manpage_directory</td> <td>/usr/local/man</td> </tr> 684 1.7 christos 685 1.7 christos <tr> <td>meta_directory</td> <td>/etc/postfix</td> </tr> 686 1.7 christos 687 1.7 christos <tr> <td>newaliases_path</td> <td>/usr/bin/newaliases</td> </tr> 688 1.7 christos 689 1.7 christos <tr> <td>openssl_path</td> <td>openssl</td> </tr> 690 1.7 christos 691 1.7 christos <tr> <td>queue_directory</td> <td>/var/spool/postfix</td> </tr> 692 1.7 christos 693 1.7 christos <tr> <td>readme_directory</td> <td>no</td> </tr> 694 1.7 christos 695 1.7 christos <tr> <td>sendmail_path</td> <td>/usr/sbin/sendmail</td> </tr> 696 1.7 christos 697 1.7 christos <tr> <td>shlib_directory</td> <td>/usr/lib/postfix</td> </tr> 698 1.7 christos 699 1.7 christos </table> 700 1.7 christos 701 1.7 christos </blockquote> 702 1.7 christos 703 1.7 christos <h4>4.6.2 - All Postfix versions </h4> 704 1.1 tron 705 1.1 tron <p> All Postfix configuration parameters can be changed by editing 706 1.1 tron a Postfix configuration file, except for one: the parameter that 707 1.1 tron specifies the location of Postfix configuration files. In order to 708 1.1 tron build Postfix with a configuration directory other than /etc/postfix, 709 1.1 tron use: </p> 710 1.1 tron 711 1.1 tron <blockquote> 712 1.1 tron <pre> 713 1.5 tron $ make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"' 714 1.5 tron $ make 715 1.1 tron </pre> 716 1.1 tron </blockquote> 717 1.1 tron 718 1.1 tron <p> IMPORTANT: Be sure to get the quotes right. These details matter 719 1.1 tron a lot. </p> 720 1.1 tron 721 1.7 christos <p> Parameters whose defaults can be specified in this way are 722 1.7 christos listed below. See the postconf(5) manpage for a description 723 1.7 christos (command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> 724 1.1 tron 725 1.1 tron <blockquote> 726 1.1 tron 727 1.1 tron <table border="1"> 728 1.1 tron 729 1.1 tron <tr><th> Macro name </th> <th>default value for</th> <th>typical 730 1.1 tron default</th> </tr> 731 1.1 tron 732 1.1 tron <tr> <td>DEF_COMMAND_DIR</td> <td>command_directory</td> 733 1.1 tron <td>/usr/sbin</td> </tr> 734 1.1 tron 735 1.1 tron <tr> <td>DEF_CONFIG_DIR</td> <td>config_directory</td> 736 1.1 tron <td>/etc/postfix</td> </tr> 737 1.1 tron 738 1.6 tron <tr> <td>DEF_DB_TYPE</td> <td>default_database_type</td> 739 1.6 tron <td>hash</td> </tr> 740 1.6 tron 741 1.1 tron <tr> <td>DEF_DAEMON_DIR</td> <td>daemon_directory</td> 742 1.1 tron <td>/usr/libexec/postfix</td> </tr> 743 1.1 tron 744 1.1 tron <tr> <td>DEF_DATA_DIR</td> <td>data_directory</td> 745 1.2 tron <td>/var/db/postfix</td> </tr> 746 1.1 tron 747 1.1 tron <tr> <td>DEF_MAILQ_PATH</td> <td>mailq_path</td> <td>/usr/bin/mailq</td> 748 1.1 tron </tr> 749 1.1 tron 750 1.1 tron <tr> <td>DEF_HTML_DIR</td> <td>html_directory</td> 751 1.1 tron <td>no</td> </tr> 752 1.1 tron 753 1.1 tron <tr> <td>DEF_MANPAGE_DIR</td> <td>manpage_directory</td> 754 1.1 tron <td>/usr/local/man</td> </tr> 755 1.1 tron 756 1.1 tron <tr> <td>DEF_NEWALIAS_PATH</td> <td>newaliases_path</td> 757 1.1 tron <td>/usr/bin/newaliases</td> </tr> 758 1.1 tron 759 1.1 tron <tr> <td>DEF_QUEUE_DIR</td> <td>queue_directory</td> 760 1.1 tron <td>/var/spool/postfix</td> </tr> 761 1.1 tron 762 1.1 tron <tr> <td>DEF_README_DIR</td> <td>readme_directory</td> 763 1.1 tron <td>no</td> </tr> 764 1.1 tron 765 1.1 tron <tr> <td>DEF_SENDMAIL_PATH</td> <td>sendmail_path</td> 766 1.1 tron <td>/usr/sbin/sendmail</td> </tr> 767 1.1 tron 768 1.1 tron </table> 769 1.1 tron 770 1.1 tron </blockquote> 771 1.1 tron 772 1.1 tron <p> Note: the data_directory parameter (for caches and pseudo-random 773 1.1 tron numbers) was introduced with Postfix version 2.5. </p> 774 1.1 tron 775 1.7 christos <h3><a name="build_other">4.7 - Overriding other compile-time 776 1.7 christos features</a></h3> 777 1.4 tron 778 1.4 tron <p> The general method to override Postfix compile-time features 779 1.4 tron is as follows: </p> 780 1.4 tron 781 1.4 tron <blockquote> 782 1.4 tron <pre> 783 1.5 tron $ make makefiles name=value name=value... 784 1.5 tron $ make 785 1.4 tron </pre> 786 1.4 tron </blockquote> 787 1.4 tron 788 1.4 tron <p> The following is an extensive list of names and values. </p> 789 1.4 tron 790 1.4 tron <table border="1"> 791 1.4 tron 792 1.4 tron <tr> <th colspan="2"> Name/Value </th> <th> Description </th> </tr> 793 1.4 tron 794 1.4 tron <tr> <td colspan="2"> AUXLIBS="object_library..."</td> <td> Specifies 795 1.7 christos one or more non-default object libraries. Postfix 3.0 and later 796 1.7 christos specify some of their database library dependencies with AUXLIBS_CDB, 797 1.7 christos AUXLIBS_LDAP, AUXLIBS_LMDB, AUXLIBS_MYSQL, AUXLIBS_PCRE, AUXLIBS_PGSQL, 798 1.7 christos AUXLIBS_SDBM, and AUXLIBS_SQLITE, respectively. </td> </tr> 799 1.4 tron 800 1.4 tron <tr> <td colspan="2"> CC=compiler_command</td> <td> Specifies a 801 1.4 tron non-default compiler. On many systems, the default is <tt>gcc</tt>. 802 1.4 tron </td> </tr> 803 1.4 tron 804 1.4 tron <tr> <td colspan="2"> CCARGS="compiler_arguments..."</td> <td> 805 1.4 tron Specifies non-default compiler arguments, for example, a non-default 806 1.4 tron <tt>include</tt> directory. The following directives turn 807 1.4 tron off Postfix features at compile time:</td> </tr> 808 1.4 tron 809 1.4 tron <tr> <td> </td> <td> -DNO_DB </td> <td> Do not build with Berkeley 810 1.4 tron DB support. By default, Berkeley DB support is compiled in on 811 1.6 tron platforms that are known to support this feature. If you override 812 1.6 tron this, then you probably should also override DEF_DB_TYPE as described 813 1.7 christos in section 4.6. </td> </tr> 814 1.7 christos 815 1.7 christos <tr> <td> </td> <td> -DNO_DNSSEC </td> <td> Do not build with DNSSEC 816 1.7 christos support, even if the resolver library appears to support it. </td> 817 1.7 christos </tr> 818 1.4 tron 819 1.4 tron <tr> <td> </td> <td> -DNO_DEVPOLL </td> <td> Do not build with 820 1.4 tron Solaris <tt>/dev/poll</tt> support. By default, <tt>/dev/poll</tt> 821 1.4 tron support is compiled in on Solaris versions that are known to support 822 1.4 tron this feature. </td> </tr> 823 1.4 tron 824 1.4 tron <tr> <td> </td> <td> -DNO_EPOLL </td> <td> Do not build with Linux 825 1.4 tron EPOLL support. By default, EPOLL support is compiled in on platforms 826 1.4 tron that are known to support this feature. </td> </tr> 827 1.4 tron 828 1.7 christos <tr> <td> </td> <td> -DNO_EAI </td> <td> Do not build with EAI 829 1.7 christos (SMTPUTF8) support. By default, EAI support is compiled in when 830 1.7 christos the "icuuc" library and header files are found. </td> </tr> 831 1.7 christos 832 1.7 christos <tr> <td> </td> <td> -DNO_INLINE </td> <td> Do not require support 833 1.7 christos for C99 "inline" functions. Instead, implement argument typechecks 834 1.7 christos for non-printf/scanf-like functions with ternary operators and 835 1.7 christos unreachable code. </td> </tr> 836 1.7 christos 837 1.4 tron <tr> <td> </td> <td> -DNO_IPV6 </td> <td> Do not build with IPv6 838 1.4 tron support. By default, IPv6 support is compiled in on platforms that 839 1.4 tron are known to have IPv6 support. Note: this directive is for debugging 840 1.8 christos And testing only. It is not guaranteed to work on all platforms. 841 1.8 christos If you don't want IPv6 support, set "inet_protocols = ipv4" in 842 1.8 christos main.cf. 843 1.4 tron </td> </tr> 844 1.4 tron 845 1.4 tron <tr> <td> </td> <td> -DNO_KQUEUE </td> <td> Do not build with FreeBSD 846 1.4 tron / NetBSD / OpenBSD / MacOSX KQUEUE support. By default, KQUEUE 847 1.4 tron support is compiled in on platforms that are known to support it. 848 1.4 tron </td> </tr> 849 1.4 tron 850 1.4 tron <tr> <td> </td> <td> -DNO_NIS </td> <td> Do not build with NIS or 851 1.6 tron NISPLUS support. NIS is not available on some recent Linux 852 1.6 tron distributions. </td> </tr> 853 1.6 tron 854 1.6 tron <tr> <td> </td> <td> -DNO_NISPLUS </td> <td> Do not build with 855 1.6 tron NISPLUS support. NISPLUS is not available on some recent Solaris 856 1.4 tron distributions. </td> </tr> 857 1.4 tron 858 1.4 tron <tr> <td> </td> <td> -DNO_PCRE </td> <td> Do not build with PCRE 859 1.4 tron support. By default, PCRE support is compiled in when the 860 1.4 tron <tt>pcre-config</tt> utility is installed. </td> </tr> 861 1.4 tron 862 1.4 tron <tr> <td> </td> <td> -DNO_POSIX_GETPW_R </td> <td> Disable support 863 1.4 tron for POSIX <tt>getpwnam_r/getpwuid_r</tt>. By default Postfix uses 864 1.4 tron these where they are known to be available. </td> </tr> 865 1.4 tron 866 1.9 christos <tr> <td> </td> <td> -DNO_RES_NCALLS </td> <td> Do not build with 867 1.9 christos the threadsafe resolver(5) API (res_ninit() etc.). </td> </tr> 868 1.9 christos 869 1.4 tron <tr> <td> </td> <td> -DNO_SIGSETJMP </td> <td> Use 870 1.4 tron <tt>setjmp()/longjmp()</tt> instead of <tt>sigsetjmp()/siglongjmp()</tt>. 871 1.4 tron By default, Postfix uses <tt>sigsetjmp()/siglongjmp()</tt> when 872 1.4 tron they are known to be available. </td> </tr> 873 1.4 tron 874 1.8 christos <tr> <td> </td> <td> -DNO_SNPRINTF </td> <td> Use <tt>sprintf()</tt> 875 1.8 christos instead of <tt>snprintf()</tt>. By default, Postfix uses 876 1.8 christos <tt>snprintf()</tt> except on ancient systems. </td> </tr> 877 1.8 christos 878 1.4 tron <tr> <td colspan="2"> DEBUG=debug_level </td> <td> Specifies a 879 1.7 christos non-default compiler debugging level. The default is "<tt>-g</tt>". 880 1.4 tron Specify DEBUG= to turn off debugging. </td> </tr> 881 1.4 tron 882 1.4 tron <tr> <td colspan="2"> OPT=optimization_level </td> <td> Specifies 883 1.7 christos a non-default optimization level. The default is "<tt>-O</tt>". 884 1.7 christos Specify OPT= to turn off optimization. </td> </tr> 885 1.7 christos 886 1.8 christos <tr> <td colspan="2"> POSTFIX_INSTALL_OPTS=-option... </td> <td> 887 1.8 christos Specifies options for the <tt>postfix-install</tt> command, separated 888 1.8 christos by whitespace. Currently, the only supported option is 889 1.8 christos "<tt>-keep-build-mtime</tt>". </td> </tr> 890 1.8 christos 891 1.7 christos <tr> <td colspan="2"> SHLIB_CFLAGS=flags </td> <td> Specifies 892 1.7 christos non-default compiler options for building Postfix dynamically-linked 893 1.7 christos libraries and database plugins. The typical default is "-fPIC". 894 1.7 christos </td> </tr> 895 1.7 christos 896 1.7 christos <tr> <td colspan="2"> SHLIB_RPATH=rpath </td> <td> Specifies 897 1.7 christos a non-default runpath for Postfix dynamically-linked libraries. The 898 1.7 christos typical default is "'-Wl,-rpath,${SHLIB_DIR}'". </td> </tr> 899 1.7 christos 900 1.7 christos <tr> <td colspan="2"> SHLIB_SUFFIX=suffix </td> <td> Specifies 901 1.7 christos a non-default suffix for Postfix dynamically-linked libraries and 902 1.7 christos database plugins. The typical default is "<tt>.so</tt>". </td> 903 1.7 christos </tr> 904 1.4 tron 905 1.4 tron <tr> <td colspan="2"> WARN="warning_flags..." </td> <td> Specifies 906 1.7 christos non-default compiler warning options for use when "<tt>make</tt>" 907 1.7 christos is invoked in a source subdirectory only. </td> 908 1.4 tron </tr> 909 1.4 tron 910 1.4 tron </table> 911 1.4 tron 912 1.7 christos <h3><a name="build_proc">4.8 - Support for thousands of processes</a></h3> 913 1.1 tron 914 1.1 tron <p> The number of connections that Postfix can manage simultaneously 915 1.1 tron is limited by the number of processes that it can run. This number 916 1.1 tron in turn is limited by the number of files and sockets that a single 917 1.1 tron process can open. For example, the Postfix queue manager has a 918 1.1 tron separate connection to each delivery process, and the anvil(8) 919 1.1 tron server has one connection per smtpd(8) process. </p> 920 1.1 tron 921 1.1 tron <p> Postfix version 2.4 and later have no built-in limits on the 922 1.1 tron number of open files or sockets, when compiled on systems that 923 1.1 tron support one of the following: </p> 924 1.1 tron 925 1.1 tron <ul> 926 1.1 tron 927 1.1 tron <li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9), 928 1.1 tron 929 1.1 tron <li> Solaris 8 /dev/poll, 930 1.1 tron 931 1.1 tron <li> Linux 2.6 epoll(4). 932 1.1 tron 933 1.1 tron </ul> 934 1.1 tron 935 1.1 tron 936 1.1 tron <p> With other Postfix versions or operating systems, the number 937 1.1 tron of file descriptors per process is limited by the value of the 938 1.1 tron FD_SETSIZE macro. If you expect to run more than 1000 mail delivery 939 1.1 tron processes, you may need to override the definition of the FD_SETSIZE 940 1.1 tron macro to make select() work correctly: </p> 941 1.1 tron 942 1.1 tron <blockquote> 943 1.1 tron <pre> 944 1.5 tron $ make makefiles CCARGS=-DFD_SETSIZE=2048 945 1.1 tron </pre> 946 1.1 tron </blockquote> 947 1.1 tron 948 1.1 tron <p> Warning: the above has no effect on some Linux versions. 949 1.1 tron Apparently, on these systems the FD_SETSIZE value can be changed 950 1.1 tron only by using undocumented interfaces. Currently, that means 951 1.1 tron including <bits/types.h> directly (which is not allowed) and 952 1.1 tron overriding the __FD_SETSIZE macro. Beware, undocumented interfaces 953 1.1 tron can change at any time and without warning. </p> 954 1.1 tron 955 1.1 tron <p> But wait, there is more: none of this will work unless the 956 1.1 tron operating system is configured to handle thousands of connections. 957 1.1 tron See the TUNING_README guide for examples of how to increase the 958 1.1 tron number of open sockets or files. </p> 959 1.1 tron 960 1.7 christos <h3><a name="build_final">4.9 - Compiling Postfix, at last</a></h3> 961 1.1 tron 962 1.1 tron <p> If the command </p> 963 1.1 tron 964 1.1 tron <blockquote> 965 1.1 tron <pre> 966 1.5 tron $ make 967 1.1 tron </pre> 968 1.1 tron </blockquote> 969 1.1 tron 970 1.1 tron <p> is successful, then you can proceed to <a href="#install">install</a> 971 1.1 tron Postfix (section 6). 972 1.1 tron 973 1.1 tron <p> If the command produces compiler error messages, it may be time 974 1.1 tron to search the web or to ask the postfix-users (a] postfix.org mailing 975 1.1 tron list, but be sure to search the mailing list archives first. Some 976 1.1 tron mailing list archives are linked from http://www.postfix.org/. </p> 977 1.1 tron 978 1.1 tron <h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2> 979 1.1 tron 980 1.1 tron <p> Each system type that Postfix knows is identified by a unique 981 1.1 tron name. Examples: SUNOS5, FREEBSD4, and so on. When porting Postfix 982 1.1 tron to a new system, the first step is to choose a SYSTEMTYPE name for 983 1.1 tron the new system. You must use a name that includes at least the 984 1.1 tron major version of the operating system (such as SUNOS4 or LINUX2), 985 1.1 tron so that different releases of the same system can be supported 986 1.1 tron without confusion. </p> 987 1.1 tron 988 1.1 tron <p> Add a case statement to the "makedefs" shell script in the 989 1.1 tron source code top-level directory that recognizes the new system 990 1.1 tron reliably, and that emits the right system-specific information. 991 1.1 tron Be sure to make the code robust against user PATH settings; if the 992 1.1 tron system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to 993 1.1 tron build for the native flavor, instead of the emulated one. </p> 994 1.1 tron 995 1.1 tron <p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h 996 1.1 tron include file. You may have to invent new feature macro names. 997 1.1 tron Please choose sensible feature macro names such as HAS_DBM or 998 1.1 tron FIONREAD_IN_SYS_FILIO_H. 999 1.1 tron 1000 1.1 tron <p> I strongly recommend against using "#ifdef SYSTEMTYPE" in 1001 1.1 tron individual source files. While this may look like the quickest 1002 1.1 tron solution, it will create a mess when newer versions of the same 1003 1.1 tron SYSTEMTYPE need to be supported. You're likely to end up placing 1004 1.1 tron "#ifdef" sections all over the source code again. </p> 1005 1.1 tron 1006 1.1 tron <h2><a name="install">6 - Installing the software after successful 1007 1.1 tron compilation</a></h2> 1008 1.1 tron 1009 1.1 tron <p> This text describes how to install Postfix from source code. 1010 1.1 tron See the PACKAGE_README file if you are building a package for 1011 1.1 tron distribution to other systems. </p> 1012 1.1 tron 1013 1.1 tron <h3>6.1 - Save existing Sendmail binaries</h3> 1014 1.1 tron 1015 1.1 tron <p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing 1016 1.1 tron Sendmail installation with Postfix, you may need to keep the old 1017 1.1 tron sendmail program running for some time in order to flush the mail 1018 1.1 tron queue. </p> 1019 1.1 tron 1020 1.1 tron <ul> 1021 1.1 tron 1022 1.1 tron <li> <p> Some systems implement a mail switch mechanism where 1023 1.1 tron different MTAs (Postfix, Sendmail, etc.) can be installed at the 1024 1.1 tron same time, while only one of them is actually being used. Examples 1025 1.1 tron of such switching mechanisms are the FreeBSD mailwrapper(8) or the 1026 1.1 tron Linux mail switch. In this case you should try to "flip" the switch 1027 1.1 tron to "Postfix" before installing Postfix. </p> 1028 1.1 tron 1029 1.1 tron <li> <p> If your system has no mail switch mechanism, execute the 1030 1.1 tron following commands (your sendmail, newaliases and mailq programs 1031 1.1 tron may be in a different place): </p> 1032 1.1 tron 1033 1.1 tron <pre> 1034 1.1 tron # mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF 1035 1.1 tron # mv /usr/bin/newaliases /usr/bin/newaliases.OFF 1036 1.1 tron # mv /usr/bin/mailq /usr/bin/mailq.OFF 1037 1.1 tron # chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ 1038 1.1 tron /usr/bin/mailq.OFF 1039 1.1 tron </pre> 1040 1.1 tron 1041 1.1 tron </ul> 1042 1.1 tron 1043 1.1 tron <h3>6.2 - Create account and groups</h3> 1044 1.1 tron 1045 1.1 tron <p> Before you install Postfix for the first time you need to 1046 1.1 tron create an account and a group:</p> 1047 1.1 tron 1048 1.1 tron <ul> 1049 1.1 tron 1050 1.1 tron <li> <p> Create a user account "postfix" with a user id and group 1051 1.1 tron id that are not used by any other user account. Preferably, this 1052 1.1 tron is an account that no-one can log into. The account does not need 1053 1.1 tron an executable login shell, and needs no existing home directory. 1054 1.1 tron My password and group file entries look like this: </p> 1055 1.1 tron 1056 1.1 tron <blockquote> 1057 1.1 tron <pre> 1058 1.1 tron /etc/passwd: 1059 1.1 tron postfix:*:12345:12345:postfix:/no/where:/no/shell 1060 1.1 tron 1061 1.1 tron /etc/group: 1062 1.1 tron postfix:*:12345: 1063 1.1 tron </pre> 1064 1.1 tron </blockquote> 1065 1.1 tron 1066 1.1 tron <p> Note: there should be no whitespace before "postfix:". </p> 1067 1.1 tron 1068 1.1 tron <li> <p> Create a group "postdrop" with a group id that is not used 1069 1.1 tron by any other user account. Not even by the postfix user account. 1070 1.1 tron My group file entry looks like: 1071 1.1 tron 1072 1.1 tron <blockquote> 1073 1.1 tron <pre> 1074 1.1 tron /etc/group: 1075 1.1 tron postdrop:*:54321: 1076 1.1 tron </pre> 1077 1.1 tron </blockquote> 1078 1.1 tron 1079 1.1 tron <p> Note: there should be no whitespace before "postdrop:". </p> 1080 1.1 tron 1081 1.1 tron </ul> 1082 1.1 tron 1083 1.1 tron <h3>6.3 - Install Postfix</h3> 1084 1.1 tron 1085 1.1 tron <p> To install or upgrade Postfix from compiled source code, run 1086 1.1 tron one of the following commands as the super-user:</p> 1087 1.1 tron 1088 1.1 tron <blockquote> 1089 1.1 tron <pre> 1090 1.1 tron # make install (interactive version, first time install) 1091 1.1 tron 1092 1.1 tron # make upgrade (non-interactive version, for upgrades) 1093 1.1 tron </pre> 1094 1.1 tron </blockquote> 1095 1.1 tron 1096 1.1 tron <ul> 1097 1.1 tron 1098 1.1 tron <li> <p> The interactive version ("make install") asks for pathnames 1099 1.1 tron for Postfix data and program files, and stores your preferences in 1100 1.1 tron the main.cf file. <b> If you don't want Postfix to overwrite 1101 1.1 tron non-Postfix "sendmail", "mailq" and "newaliases" files, specify 1102 1.1 tron pathnames that end in ".postfix"</b>. </p> 1103 1.1 tron 1104 1.1 tron <li> <p> The non-interactive version ("make upgrade") needs the 1105 1.1 tron /etc/postfix/main.cf file from a previous installation. If the file 1106 1.1 tron does not exist, use interactive installation ("make install") 1107 1.1 tron instead. </p> 1108 1.1 tron 1109 1.7 christos <li> <p> If you specify name=value arguments on the "make install" 1110 1.7 christos or "make upgrade" command line, then these will take precedence 1111 1.7 christos over compiled-in default settings or main.cf settings. </p> 1112 1.7 christos 1113 1.7 christos <p> The command "make install/upgrade name=value ..." will replace 1114 1.7 christos the string MAIL_VERSION at the end of a configuration parameter 1115 1.7 christos value with the Postfix release version. Do not try to specify 1116 1.7 christos something like $mail_version on this command line. This produces 1117 1.7 christos inconsistent results with different versions of the make(1) command. 1118 1.7 christos </p> 1119 1.7 christos 1120 1.1 tron </ul> 1121 1.1 tron 1122 1.1 tron <h3>6.4 - Configure Postfix</h3> 1123 1.1 tron 1124 1.1 tron <p> Proceed to the section on how you wish to run Postfix on 1125 1.1 tron your particular machine: </p> 1126 1.1 tron 1127 1.1 tron <ul> 1128 1.1 tron 1129 1.1 tron <li> <p> <a href="#send_only">Send</a> mail only, without changing 1130 1.1 tron an existing Sendmail installation (section 7). </p> 1131 1.1 tron 1132 1.1 tron <li> <p> <a href="#send_receive">Send and receive</a> mail via a 1133 1.1 tron virtual host interface, still without any change to an existing 1134 1.1 tron Sendmail installation (section 8). </p> 1135 1.1 tron 1136 1.1 tron <li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail 1137 1.1 tron (section 9). </p> 1138 1.1 tron 1139 1.1 tron </ul> 1140 1.1 tron 1141 1.1 tron <h2><a name="send_only">7 - Configuring Postfix to send mail 1142 1.1 tron only</a></h2> 1143 1.1 tron 1144 1.1 tron <p> If you are going to use Postfix to send mail only, there is no 1145 1.1 tron need to change your existing sendmail setup. Instead, set up your 1146 1.1 tron mail user agent so that it calls the Postfix sendmail program 1147 1.1 tron directly. </p> 1148 1.1 tron 1149 1.1 tron <p> Follow the instructions in the "<a href="#mandatory">Mandatory 1150 1.1 tron configuration file edits</a>" in section 10, and review the "<a 1151 1.1 tron href="#hamlet">To chroot or not to chroot</a>" text in section 1152 1.1 tron 11. </p> 1153 1.1 tron 1154 1.1 tron <p> You MUST comment out the "smtp inet" entry in /etc/postfix/master.cf, 1155 1.1 tron in order to avoid conflicts with the real sendmail. Put a "#" 1156 1.1 tron character in front of the line that defines the smtpd service: </p> 1157 1.1 tron 1158 1.1 tron <blockquote> 1159 1.1 tron <pre> 1160 1.1 tron /etc/postfix/master.cf: 1161 1.1 tron #smtp inet n - n - - smtpd 1162 1.1 tron </pre> 1163 1.1 tron </blockquote> 1164 1.1 tron 1165 1.1 tron <p> Start the Postfix system: </p> 1166 1.1 tron 1167 1.1 tron <blockquote> 1168 1.1 tron <pre> 1169 1.1 tron # postfix start 1170 1.1 tron </pre> 1171 1.1 tron </blockquote> 1172 1.1 tron 1173 1.1 tron <p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1174 1.1 tron 1175 1.1 tron <blockquote> 1176 1.1 tron <pre> 1177 1.1 tron # sendmail -bd -qwhatever 1178 1.1 tron </pre> 1179 1.1 tron </blockquote> 1180 1.1 tron 1181 1.1 tron <p> and watch your maillog file for any error messages. The pathname 1182 1.1 tron is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1183 1.1 tron else. Typically, the pathname is defined in the /etc/syslog.conf 1184 1.1 tron file. </p> 1185 1.1 tron 1186 1.1 tron <blockquote> 1187 1.1 tron <pre> 1188 1.5 tron $ egrep '(reject|warning|error|fatal|panic):' /some/log/file 1189 1.1 tron </pre> 1190 1.1 tron </blockquote> 1191 1.1 tron 1192 1.1 tron <p> Note: the most important error message is logged first. Later 1193 1.1 tron messages are not as useful. </p> 1194 1.1 tron 1195 1.1 tron <p> In order to inspect the mail queue, use one of the following 1196 1.1 tron commands: </p> 1197 1.1 tron 1198 1.1 tron <blockquote> 1199 1.1 tron <pre> 1200 1.5 tron $ mailq 1201 1.1 tron 1202 1.5 tron $ sendmail -bp 1203 1.1 tron 1204 1.5 tron $ postqueue -p 1205 1.1 tron </pre> 1206 1.1 tron </blockquote> 1207 1.1 tron 1208 1.1 tron <p> See also the "<a href="#care">Care and feeding</a>" section 12 1209 1.1 tron below. </p> 1210 1.1 tron 1211 1.1 tron <h2><a name="send_receive">8 - Configuring Postfix to send and 1212 1.1 tron receive mail via virtual interface</a></h2> 1213 1.1 tron 1214 1.1 tron <p> Alternatively, you can use the Postfix system to send AND 1215 1.1 tron receive mail while leaving your Sendmail setup intact, by running 1216 1.1 tron Postfix on a virtual interface address. Simply configure your mail 1217 1.1 tron user agent to directly invoke the Postfix sendmail program. </p> 1218 1.1 tron 1219 1.1 tron <p> To create a virtual network interface address, study your 1220 1.1 tron system ifconfig manual page. The command syntax could be any 1221 1.1 tron of: </p> 1222 1.1 tron 1223 1.1 tron <blockquote> 1224 1.1 tron <pre> 1225 1.1 tron # <b>ifconfig le0:1 <address> netmask <mask> up</b> 1226 1.1 tron # <b>ifconfig en0 alias <address> netmask 255.255.255.255</b> 1227 1.1 tron </pre> 1228 1.1 tron </blockquote> 1229 1.1 tron 1230 1.1 tron <p> In the /etc/postfix/main.cf file, I would specify </p> 1231 1.1 tron 1232 1.1 tron <blockquote> 1233 1.1 tron <pre> 1234 1.1 tron /etc/postfix/main.cf: 1235 1.1 tron myhostname = virtual.host.tld 1236 1.1 tron inet_interfaces = $myhostname 1237 1.1 tron mydestination = $myhostname 1238 1.1 tron </pre> 1239 1.1 tron </blockquote> 1240 1.1 tron 1241 1.1 tron <p> Follow the instructions in the "<a href="#mandatory">Mandatory 1242 1.1 tron configuration file edits</a>" in section 10, and review the "<a 1243 1.9 christos href="#hamlet">To chroot or not to chroot</a>" text in section 1244 1.1 tron 11. </p> 1245 1.1 tron 1246 1.1 tron <p> Start the Postfix system: </p> 1247 1.1 tron 1248 1.1 tron <blockquote> 1249 1.1 tron <pre> 1250 1.1 tron # postfix start 1251 1.1 tron </pre> 1252 1.1 tron </blockquote> 1253 1.1 tron 1254 1.1 tron <p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1255 1.1 tron 1256 1.1 tron <blockquote> 1257 1.1 tron <pre> 1258 1.1 tron # sendmail -bd -qwhatever 1259 1.1 tron </pre> 1260 1.1 tron </blockquote> 1261 1.1 tron 1262 1.1 tron <p> and watch your maillog file for any error messages. The pathname 1263 1.1 tron is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1264 1.1 tron else. Typically, the pathname is defined in the /etc/syslog.conf 1265 1.1 tron file. </p> 1266 1.1 tron 1267 1.1 tron <blockquote> 1268 1.1 tron <pre> 1269 1.5 tron $ egrep '(reject|warning|error|fatal|panic):' /some/log/file 1270 1.1 tron </pre> 1271 1.1 tron </blockquote> 1272 1.1 tron 1273 1.1 tron <p> Note: the most important error message is logged first. Later 1274 1.1 tron messages are not as useful. </p> 1275 1.1 tron 1276 1.1 tron <p> In order to inspect the mail queue, use one of the following 1277 1.1 tron commands: </p> 1278 1.1 tron 1279 1.1 tron <blockquote> 1280 1.1 tron <pre> 1281 1.5 tron $ mailq 1282 1.1 tron 1283 1.5 tron $ sendmail -bp 1284 1.1 tron 1285 1.5 tron $ postqueue -p 1286 1.1 tron </pre> 1287 1.1 tron </blockquote> 1288 1.1 tron 1289 1.1 tron <p> See also the "<a href="#care">Care and feeding</a>" section 12 1290 1.1 tron below. </p> 1291 1.1 tron 1292 1.1 tron <h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2> 1293 1.1 tron 1294 1.1 tron <p> Prior to installing Postfix you should <a href="#save">save</a> 1295 1.1 tron any existing sendmail program files as described in section 6. Be 1296 1.1 tron sure to keep the old sendmail running for at least a couple days 1297 1.1 tron to flush any unsent mail. To do so, stop the sendmail daemon and 1298 1.1 tron restart it as: </p> 1299 1.1 tron 1300 1.1 tron <blockquote> 1301 1.1 tron <pre> 1302 1.1 tron # /usr/sbin/sendmail.OFF -q 1303 1.1 tron </pre> 1304 1.1 tron </blockquote> 1305 1.1 tron 1306 1.1 tron <p> Note: this is old sendmail syntax. Newer versions use separate 1307 1.1 tron processes for mail submission and for running the queue. </p> 1308 1.1 tron 1309 1.1 tron <p> After you have visited the "<a href="#mandatory">Mandatory 1310 1.1 tron configuration file edits</a>" section below, you can start the 1311 1.1 tron Postfix system with: </p> 1312 1.1 tron 1313 1.1 tron <blockquote> 1314 1.1 tron <pre> 1315 1.1 tron # postfix start 1316 1.1 tron </pre> 1317 1.1 tron </blockquote> 1318 1.1 tron 1319 1.1 tron <p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1320 1.1 tron 1321 1.1 tron <blockquote> 1322 1.1 tron <pre> 1323 1.1 tron # sendmail -bd -qwhatever 1324 1.1 tron </pre> 1325 1.1 tron </blockquote> 1326 1.1 tron 1327 1.1 tron <p> and watch your maillog file for any error messages. The pathname 1328 1.1 tron is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1329 1.1 tron else. Typically, the pathname is defined in the /etc/syslog.conf 1330 1.1 tron file. </p> 1331 1.1 tron 1332 1.1 tron <blockquote> 1333 1.1 tron <pre> 1334 1.5 tron $ egrep '(reject|warning|error|fatal|panic):' /some/log/file 1335 1.1 tron </pre> 1336 1.1 tron </blockquote> 1337 1.1 tron 1338 1.1 tron <p> Note: the most important error message is logged first. Later 1339 1.1 tron messages are not as useful. </p> 1340 1.1 tron 1341 1.1 tron <p> In order to inspect the mail queue, use one of the following 1342 1.1 tron commands: </p> 1343 1.1 tron 1344 1.1 tron <blockquote> 1345 1.1 tron <pre> 1346 1.5 tron $ mailq 1347 1.1 tron 1348 1.5 tron $ sendmail -bp 1349 1.1 tron 1350 1.5 tron $ postqueue -p 1351 1.1 tron </pre> 1352 1.1 tron </blockquote> 1353 1.1 tron 1354 1.1 tron <p> See also the "<a href="#care">Care and feeding</a>" section 12 1355 1.1 tron below. </p> 1356 1.1 tron 1357 1.1 tron <h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2> 1358 1.1 tron 1359 1.1 tron <p> Note: the material covered in this section is covered in more 1360 1.1 tron detail in the BASIC_CONFIGURATION_README document. The information 1361 1.1 tron presented below is targeted at experienced system administrators. 1362 1.1 tron </p> 1363 1.1 tron 1364 1.1 tron <h3>10.1 - Postfix configuration files</h3> 1365 1.1 tron 1366 1.1 tron <p> By default, Postfix configuration files are in /etc/postfix. 1367 1.1 tron The two most important files are main.cf and master.cf; these files 1368 1.1 tron must be owned by root. Giving someone else write permission to 1369 1.1 tron main.cf or master.cf (or to their parent directories) means giving 1370 1.1 tron root privileges to that person. </p> 1371 1.1 tron 1372 1.1 tron <p> In /etc/postfix/main.cf, you will have to set up a minimal number 1373 1.1 tron of configuration parameters. Postfix configuration parameters 1374 1.1 tron resemble shell variables, with two important differences: the first 1375 1.1 tron one is that Postfix does not know about quotes like the UNIX shell 1376 1.1 tron does.</p> 1377 1.1 tron 1378 1.1 tron <p> You specify a configuration parameter as: </p> 1379 1.1 tron 1380 1.1 tron <blockquote> 1381 1.1 tron <pre> 1382 1.1 tron /etc/postfix/main.cf: 1383 1.1 tron parameter = value 1384 1.1 tron </pre> 1385 1.1 tron </blockquote> 1386 1.1 tron 1387 1.1 tron <p> and you use it by putting a "$" character in front of its name: </p> 1388 1.1 tron 1389 1.1 tron <blockquote> 1390 1.1 tron <pre> 1391 1.1 tron /etc/postfix/main.cf: 1392 1.1 tron other_parameter = $parameter 1393 1.1 tron </pre> 1394 1.1 tron </blockquote> 1395 1.1 tron 1396 1.1 tron <p> You can use $parameter before it is given a value (that is the 1397 1.1 tron second main difference with UNIX shell variables). The Postfix 1398 1.1 tron configuration language uses lazy evaluation, and does not look at 1399 1.1 tron a parameter value until it is needed at runtime. </p> 1400 1.1 tron 1401 1.1 tron <p> Whenever you make a change to the main.cf or master.cf file, 1402 1.1 tron execute the following command in order to refresh a running mail 1403 1.1 tron system: </p> 1404 1.1 tron 1405 1.1 tron <blockquote> 1406 1.1 tron <pre> 1407 1.1 tron # postfix reload 1408 1.1 tron </pre> 1409 1.1 tron </blockquote> 1410 1.1 tron 1411 1.1 tron <h3>10.2 - Default domain for unqualified addresses</h3> 1412 1.1 tron 1413 1.1 tron <p> First of all, you must specify what domain will be appended to an 1414 1.1 tron unqualified address (i.e. an address without @domain.tld). The 1415 1.1 tron "myorigin" parameter defaults to the local hostname, but that is 1416 1.1 tron probably OK only for very small sites. </p> 1417 1.1 tron 1418 1.1 tron <p> Some examples (use only one): </p> 1419 1.1 tron 1420 1.1 tron <blockquote> 1421 1.1 tron <pre> 1422 1.1 tron /etc/postfix/main.cf: 1423 1.1 tron myorigin = $myhostname (send mail as "user@$myhostname") 1424 1.1 tron myorigin = $mydomain (send mail as "user@$mydomain") 1425 1.1 tron </pre> 1426 1.1 tron </blockquote> 1427 1.1 tron 1428 1.1 tron <h3>10.3 - What domains to receive locally</h3> 1429 1.1 tron 1430 1.1 tron <p> Next you need to specify what mail addresses Postfix should deliver 1431 1.1 tron locally. </p> 1432 1.1 tron 1433 1.1 tron <p> Some examples (use only one): </p> 1434 1.1 tron 1435 1.1 tron <blockquote> 1436 1.1 tron <pre> 1437 1.1 tron /etc/postfix/main.cf: 1438 1.1 tron mydestination = $myhostname, localhost.$mydomain, localhost 1439 1.1 tron mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain 1440 1.1 tron mydestination = $myhostname 1441 1.1 tron </pre> 1442 1.1 tron </blockquote> 1443 1.1 tron 1444 1.1 tron <p>The first example is appropriate for a workstation, the second 1445 1.1 tron is appropriate for the mailserver for an entire domain. The third 1446 1.1 tron example should be used when running on a virtual host interface.</p> 1447 1.1 tron 1448 1.1 tron <h3>10.4 - Proxy/NAT interface addresses </h3> 1449 1.1 tron 1450 1.1 tron <p> The proxy_interfaces parameter specifies all network addresses 1451 1.1 tron that Postfix receives mail on by way of a proxy or network address 1452 1.1 tron translation unit. You may specify symbolic hostnames instead of 1453 1.1 tron network addresses. </p> 1454 1.1 tron 1455 1.1 tron <p> IMPORTANT: You must specify your proxy/NAT external addresses 1456 1.1 tron when your system is a backup MX host for other domains, otherwise 1457 1.1 tron mail delivery loops will happen when the primary MX host is down. 1458 1.1 tron </p> 1459 1.1 tron 1460 1.1 tron <p> Example: host behind NAT box running a backup MX host. </p> 1461 1.1 tron 1462 1.1 tron <blockquote> 1463 1.1 tron <pre> 1464 1.1 tron /etc/postfix/main.cf: 1465 1.1 tron proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) 1466 1.1 tron </pre> 1467 1.1 tron </blockquote> 1468 1.1 tron 1469 1.1 tron <h3>10.5 - What local clients to relay mail from </h3> 1470 1.1 tron 1471 1.1 tron <p> If your machine is on an open network then you must specify 1472 1.1 tron what client IP addresses are authorized to relay their mail through 1473 1.1 tron your machine into the Internet. The default setting includes all 1474 1.1 tron subnetworks that the machine is attached to. This may give relay 1475 1.1 tron permission to too many clients. My own settings are: </p> 1476 1.1 tron 1477 1.1 tron <blockquote> 1478 1.1 tron <pre> 1479 1.1 tron /etc/postfix/main.cf: 1480 1.1 tron mynetworks = 168.100.189.0/28, 127.0.0.0/8 1481 1.1 tron </pre> 1482 1.1 tron </blockquote> 1483 1.1 tron 1484 1.1 tron <h3>10.6 - What relay destinations to accept from strangers </h3> 1485 1.1 tron 1486 1.1 tron <p> If your machine is on an open network then you must also specify 1487 1.1 tron whether Postfix will forward mail from strangers. The default 1488 1.1 tron setting will forward mail to all domains (and subdomains of) what 1489 1.1 tron is listed in $mydestination. This may give relay permission for 1490 1.1 tron too many destinations. Recommended settings (use only one): </p> 1491 1.1 tron 1492 1.1 tron <blockquote> 1493 1.1 tron <pre> 1494 1.1 tron /etc/postfix/main.cf: 1495 1.1 tron relay_domains = (do not forward mail from strangers) 1496 1.1 tron relay_domains = $mydomain (my domain and subdomains) 1497 1.1 tron relay_domains = $mydomain, other.domain.tld, ... 1498 1.1 tron </pre> 1499 1.1 tron </blockquote> 1500 1.1 tron 1501 1.1 tron <h3>10.7 - Optional: configure a smart host for remote delivery</h3> 1502 1.1 tron 1503 1.1 tron <p> If you're behind a firewall, you should set up a relayhost. If 1504 1.1 tron you can, specify the organizational domain name so that Postfix 1505 1.1 tron can use DNS lookups, and so that it can fall back to a secondary 1506 1.1 tron MX host when the primary MX host is down. Otherwise just specify 1507 1.1 tron a hard-coded hostname. </p> 1508 1.1 tron 1509 1.1 tron <p> Some examples (use only one): </p> 1510 1.1 tron 1511 1.1 tron <blockquote> 1512 1.1 tron <pre> 1513 1.1 tron /etc/postfix/main.cf: 1514 1.1 tron relayhost = $mydomain 1515 1.1 tron relayhost = [mail.$mydomain] 1516 1.1 tron </pre> 1517 1.1 tron </blockquote> 1518 1.1 tron 1519 1.1 tron <p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p> 1520 1.1 tron 1521 1.1 tron <p> By default, the SMTP client will do DNS lookups even when you 1522 1.1 tron specify a relay host. If your machine has no access to a DNS server, 1523 1.1 tron turn off SMTP client DNS lookups like this: </p> 1524 1.1 tron 1525 1.1 tron <blockquote> 1526 1.1 tron <pre> 1527 1.1 tron /etc/postfix/main.cf: 1528 1.1 tron disable_dns_lookups = yes 1529 1.1 tron </pre> 1530 1.1 tron </blockquote> 1531 1.1 tron 1532 1.1 tron <p> The STANDARD_CONFIGURATION_README file has more hints and tips for 1533 1.1 tron firewalled and/or dial-up networks. </p> 1534 1.1 tron 1535 1.1 tron <h3>10.8 - Create the aliases database</h3> 1536 1.1 tron 1537 1.1 tron <p> Postfix uses a Sendmail-compatible aliases(5) table to redirect 1538 1.1 tron mail for local(8) recipients. Typically, this information is kept 1539 1.1 tron in two files: in a text file /etc/aliases and in an indexed file 1540 1.1 tron /etc/aliases.db. The command "postconf alias_maps" will tell you 1541 1.1 tron the exact location of the text file. </p> 1542 1.1 tron 1543 1.1 tron <p> First, be sure to update the text file with aliases for root, 1544 1.1 tron postmaster and "postfix" that forward mail to a real person. Postfix 1545 1.1 tron has a sample aliases file /etc/postfix/aliases that you can adapt 1546 1.1 tron to local conditions. </p> 1547 1.1 tron 1548 1.1 tron <blockquote> 1549 1.1 tron <pre> 1550 1.1 tron /etc/aliases: 1551 1.1 tron root: you 1552 1.1 tron postmaster: root 1553 1.1 tron postfix: root 1554 1.1 tron bin: root 1555 1.1 tron <i>etcetera...</i> 1556 1.1 tron </pre> 1557 1.1 tron </blockquote> 1558 1.1 tron 1559 1.1 tron <p> Note: there should be no whitespace before the ":". </p> 1560 1.1 tron 1561 1.1 tron <p> Finally, build the indexed aliases file with one of the 1562 1.1 tron following commands: </p> 1563 1.1 tron 1564 1.1 tron <blockquote> 1565 1.1 tron <pre> 1566 1.1 tron # newaliases 1567 1.1 tron # sendmail -bi 1568 1.9 christos # postalias /etc/aliases (pathname is system dependent!) 1569 1.1 tron </pre> 1570 1.1 tron </blockquote> 1571 1.1 tron 1572 1.1 tron <h2><a name="hamlet">11 - To chroot or not to chroot</a></h2> 1573 1.1 tron 1574 1.1 tron <p> Postfix daemon processes can be configured (via master.cf) to 1575 1.1 tron run in a chroot jail. The processes run at a fixed low privilege 1576 1.1 tron and with access only to the Postfix queue directories (/var/spool/postfix). 1577 1.1 tron This provides a significant barrier against intrusion. The barrier 1578 1.1 tron is not impenetrable, but every little bit helps. </p> 1579 1.1 tron 1580 1.1 tron <p> With the exception of Postfix daemons that deliver mail locally 1581 1.1 tron and/or that execute non-Postfix commands, every Postfix daemon can 1582 1.1 tron run chrooted. </p> 1583 1.1 tron 1584 1.1 tron <p> Sites with high security requirements should consider to chroot 1585 1.1 tron all daemons that talk to the network: the smtp(8) and smtpd(8) 1586 1.1 tron processes, and perhaps also the lmtp(8) client. The author's own 1587 1.1 tron porcupine.org mail server runs all daemons chrooted that can be 1588 1.1 tron chrooted. </p> 1589 1.1 tron 1590 1.1 tron <p> The default /etc/postfix/master.cf file specifies that no 1591 1.1 tron Postfix daemon runs chrooted. In order to enable chroot operation, 1592 1.1 tron edit the file /etc/postfix/master.cf. Instructions are in the file. 1593 1.1 tron </p> 1594 1.1 tron 1595 1.1 tron <p> Note that a chrooted daemon resolves all filenames relative to 1596 1.1 tron the Postfix queue directory (/var/spool/postfix). For successful 1597 1.1 tron use of a chroot jail, most UNIX systems require you to bring in 1598 1.1 tron some files or device nodes. The examples/chroot-setup directory 1599 1.1 tron in the source code distribution has a collection of scripts that 1600 1.1 tron help you set up Postfix chroot environments on different operating 1601 1.1 tron systems. </p> 1602 1.1 tron 1603 1.1 tron <p> Additionally, you almost certainly need to configure syslogd 1604 1.1 tron so that it listens on a socket inside the Postfix queue directory. 1605 1.1 tron Examples for specific systems: </p> 1606 1.1 tron 1607 1.1 tron <dl> 1608 1.1 tron 1609 1.1 tron <dt> FreeBSD: </dt> 1610 1.1 tron 1611 1.1 tron <dd> <pre> 1612 1.1 tron # mkdir -p /var/spool/postfix/var/run 1613 1.1 tron # syslogd -l /var/spool/postfix/var/run/log 1614 1.1 tron </pre> </dd> 1615 1.1 tron 1616 1.1 tron <dt> Linux, OpenBSD: </dt> 1617 1.1 tron 1618 1.1 tron <dd> <pre> 1619 1.1 tron # mkdir -p /var/spool/postfix/dev 1620 1.1 tron # syslogd -a /var/spool/postfix/dev/log 1621 1.1 tron </pre> </dd> 1622 1.1 tron 1623 1.1 tron </dl> 1624 1.1 tron 1625 1.1 tron <h2><a name="care">12 - Care and feeding of the Postfix system</a></h2> 1626 1.1 tron 1627 1.1 tron <p> Postfix daemon processes run in the background, and log problems 1628 1.1 tron and normal activity to the syslog daemon. The names of logfiles 1629 1.1 tron are specified in /etc/syslog.conf. At the very least you need 1630 1.1 tron something like: </p> 1631 1.1 tron 1632 1.1 tron <blockquote> 1633 1.1 tron <pre> 1634 1.1 tron /etc/syslog.conf: 1635 1.1 tron mail.err /dev/console 1636 1.1 tron mail.debug /var/log/maillog 1637 1.1 tron </pre> 1638 1.1 tron </blockquote> 1639 1.1 tron 1640 1.1 tron <p> IMPORTANT: the syslogd will not create files. You must create 1641 1.1 tron them before (re)starting syslogd. </p> 1642 1.1 tron 1643 1.1 tron <p> IMPORTANT: on Linux you need to put a "-" character before 1644 1.1 tron the pathname, e.g., -/var/log/maillog, otherwise the syslogd 1645 1.1 tron will use more system resources than Postfix does. </p> 1646 1.1 tron 1647 1.1 tron <p> Hopefully, the number of problems will be small, but it is a good 1648 1.1 tron idea to run every night before the syslog files are rotated: </p> 1649 1.1 tron 1650 1.1 tron <blockquote> 1651 1.1 tron <pre> 1652 1.1 tron # postfix check 1653 1.1 tron # egrep '(reject|warning|error|fatal|panic):' /some/log/file 1654 1.1 tron </pre> 1655 1.1 tron </blockquote> 1656 1.1 tron 1657 1.1 tron <ul> 1658 1.1 tron 1659 1.1 tron <li> <p> The first line (postfix check) causes Postfix to report 1660 1.1 tron file permission/ownership discrepancies. </p> 1661 1.1 tron 1662 1.1 tron <li> <p> The second line looks for problem reports from the mail 1663 1.1 tron software, and reports how effective the relay and junk mail access 1664 1.1 tron blocks are. This may produce a lot of output. You will want to 1665 1.1 tron apply some postprocessing to eliminate uninteresting information. 1666 1.1 tron </p> 1667 1.1 tron 1668 1.1 tron </ul> 1669 1.1 tron 1670 1.1 tron <p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a> 1671 1.1 tron document describes the meaning of the "warning" etc. labels in 1672 1.1 tron Postfix logging. </p> 1673 1.1 tron 1674 1.1 tron </body> 1675 1.1 tron 1676 1.1 tron </html> 1677
Indexes created Fri Jun 26 00:24:39 UTC 2026