1 1.1 tron <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 1.11 christos "https://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.10 christos <link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 1.1 tron 13 1.1 tron </head> 14 1.1 tron 15 1.1 tron <body> 16 1.1 tron 17 1.1 tron <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix 18 1.1 tron Installation From Source Code </h1> 19 1.1 tron 20 1.1 tron <hr> 21 1.1 tron 22 1.1 tron <h2> <a name="1">1 - Purpose of this document</a> </h2> 23 1.1 tron 24 1.1 tron <p> If you are using a pre-compiled version of Postfix, you should 25 1.1 tron start with BASIC_CONFIGURATION_README and the general documentation 26 1.1 tron referenced by it. INSTALL is only a bootstrap document to get 27 1.1 tron Postfix up and running from scratch with the minimal number of 28 1.1 tron steps; it should not be considered part of the general documentation. 29 1.1 tron </p> 30 1.1 tron 31 1.1 tron <p> This document describes how to build, install and configure a 32 1.1 tron Postfix system so that it can do one of the following: </p> 33 1.1 tron 34 1.1 tron <ul> 35 1.1 tron 36 1.1 tron <li> Send mail only, without changing an existing Sendmail 37 1.1 tron installation. 38 1.1 tron 39 1.1 tron <li> Send and receive mail via a virtual host interface, still 40 1.1 tron without any change to an existing Sendmail installation. 41 1.1 tron 42 1.1 tron <li> Run Postfix instead of Sendmail. 43 1.1 tron 44 1.1 tron </ul> 45 1.1 tron 46 1.1 tron <p> Topics covered in this document: </p> 47 1.1 tron 48 1.1 tron <ol> 49 1.1 tron 50 1.1 tron <li> <a href="#1">Purpose of this document</a> 51 1.1 tron 52 1.1 tron <li> <a href="#2">Typographical conventions</a> 53 1.1 tron 54 1.1 tron <li> <a href="#3">Documentation</a> 55 1.1 tron 56 1.1 tron <li> <a href="#4">Building on a supported system</a> 57 1.1 tron 58 1.1 tron <li> <a href="#5">Porting Postfix to an unsupported system</a> 59 1.1 tron 60 1.1 tron <li> <a href="#install">Installing the software after successful 61 1.1 tron compilation </a> 62 1.1 tron 63 1.1 tron <li> <a href="#send_only">Configuring Postfix to send mail 64 1.1 tron only </a> 65 1.1 tron 66 1.1 tron <li> <a href="#send_receive">Configuring Postfix to send and 67 1.1 tron receive mail via virtual interface </a> 68 1.1 tron 69 1.1 tron <li> <a href="#replace">Running Postfix instead of Sendmail</a> 70 1.1 tron 71 1.1 tron <li> <a href="#mandatory">Mandatory configuration file edits</a> 72 1.1 tron 73 1.1 tron <li> <a href="#hamlet">To chroot or not to chroot</a> 74 1.1 tron 75 1.1 tron <li> <a href="#care">Care and feeding of the Postfix system</a> 76 1.1 tron 77 1.1 tron </ol> 78 1.1 tron 79 1.1 tron <h2> <a name="2">2 - Typographical conventions</a> </h2> 80 1.1 tron 81 1.1 tron <p> In the instructions below, a command written as </p> 82 1.1 tron 83 1.1 tron <blockquote> 84 1.1 tron <pre> 85 1.1 tron # command 86 1.1 tron </pre> 87 1.1 tron </blockquote> 88 1.1 tron 89 1.1 tron <p> should be executed as the superuser. </p> 90 1.1 tron 91 1.1 tron <p> A command written as </p> 92 1.1 tron 93 1.1 tron <blockquote> 94 1.1 tron <pre> 95 1.5 tron $ command 96 1.1 tron </pre> 97 1.1 tron </blockquote> 98 1.1 tron 99 1.1 tron <p> should be executed as an unprivileged user. </p> 100 1.1 tron 101 1.1 tron <h2> <a name="3">3 - Documentation</a> </h2> 102 1.1 tron 103 1.1 tron <p> Documentation is available as README files (start with the file 104 1.1 tron README_FILES/AAAREADME), as HTML web pages (point your browser to 105 1.1 tron "html/index.html") and as UNIX-style manual pages. </p> 106 1.1 tron 107 1.1 tron <p> You should view the README files with a pager such as more(1) 108 1.1 tron or less(1), because the files use backspace characters in order to 109 1.1 tron produce <b>bold</b> font. To print a README file without backspace 110 1.1 tron characters, use the col(1) command. For example: </p> 111 1.1 tron 112 1.1 tron <blockquote> 113 1.1 tron <pre> 114 1.5 tron $ col -bx <file | lpr 115 1.1 tron </pre> 116 1.1 tron </blockquote> 117 1.1 tron 118 1.1 tron <p> In order to view the manual pages before installing Postfix, 119 1.1 tron point your MANPATH environment variable to the "man" subdirectory; 120 1.1 tron be sure to use an absolute path. </p> 121 1.1 tron 122 1.1 tron <blockquote> 123 1.1 tron <pre> 124 1.5 tron $ export MANPATH; MANPATH="`pwd`/man:$MANPATH" 125 1.5 tron $ setenv MANPATH "`pwd`/man:$MANPATH" 126 1.1 tron </pre> 127 1.1 tron </blockquote> 128 1.1 tron 129 1.12 christos <p> Of particular interest is the postconf(5) manual page that lists 130 1.12 christos all the 900+ configuration parameters. The hyperlinks in the HTML 131 1.12 christos version (html/postconf.5.html) make the text easy to navigate. </p> 132 1.1 tron 133 1.1 tron <p> All Postfix source files have their own built-in manual page. 134 1.1 tron Tools to extract those embedded manual pages are available in the 135 1.1 tron mantools directory. </p> 136 1.1 tron 137 1.1 tron <h2> <a name="4">4 - Building on a supported system</a> </h2> 138 1.1 tron 139 1.12 christos <p> Postfix development happens on FreeBSD and Linux, with occasional 140 1.12 christos tests on Solaris. Support for other systems relies on feedback from 141 1.12 christos their users, and may not always be 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.12 christos <tr> <td> CDB database</td> <td>CDB_README</td> <td> Postfix 602 1.12 christos 2.2 </td> </tr> 603 1.12 christos 604 1.6 tron <tr> <td> LMDB database</td> <td>LMDB_README</td> <td> Postfix 605 1.6 tron 2.11 </td> </tr> 606 1.6 tron 607 1.1 tron <tr> <td> LDAP database</td> <td>LDAP_README</td> <td> Postfix 608 1.1 tron 1.0 </td> </tr> 609 1.1 tron 610 1.11 christos <tr> <td> MongoDB database</td> <td>MONGODB_README</td> <td> Postfix 611 1.11 christos 3.9 </td> </tr> 612 1.11 christos 613 1.1 tron <tr> <td> MySQL database</td> <td>MYSQL_README</td> <td> Postfix 614 1.1 tron 1.0 </td> </tr> 615 1.1 tron 616 1.1 tron <tr> <td> Perl compatible regular expression</td> <td>PCRE_README</td> 617 1.1 tron <td> Postfix 1.0 </td> </tr> 618 1.1 tron 619 1.1 tron <tr> <td> PostgreSQL database</td> <td>PGSQL_README</td> <td> 620 1.1 tron Postfix 2.0 </td> </tr> 621 1.1 tron 622 1.1 tron <tr> <td> SASL authentication </td> <td>SASL_README</td> <td> 623 1.1 tron Postfix 1.0 </td> </tr> 624 1.1 tron 625 1.3 tron <tr> <td> SQLite database</td> <td>SQLITE_README</td> <td> Postfix 626 1.3 tron 2.8 </td> </tr> 627 1.3 tron 628 1.1 tron <tr> <td> STARTTLS session encryption </td> <td>TLS_README</td> <td> 629 1.1 tron Postfix 2.2 </td> </tr> 630 1.1 tron 631 1.1 tron </table> 632 1.1 tron 633 1.1 tron </blockquote> 634 1.1 tron 635 1.1 tron <p> Note: IP version 6 support is compiled into Postfix on operating 636 1.1 tron systems that have IPv6 support. See the IPV6_README file for details. 637 1.1 tron </p> 638 1.1 tron 639 1.7 christos <h3><a name="build_over">4.6 - Overriding built-in parameter default 640 1.7 christos settings</a></h3> 641 1.7 christos 642 1.7 christos <h4>4.6.1 - Postfix 3.0 and later </h4> 643 1.7 christos 644 1.7 christos <p> All Postfix configuration parameters can be changed by editing 645 1.7 christos a Postfix configuration file, except for one: the parameter that 646 1.7 christos specifies the location of Postfix configuration files. In order to 647 1.7 christos build Postfix with a configuration directory other than /etc/postfix, 648 1.7 christos use: </p> 649 1.7 christos 650 1.7 christos <blockquote> 651 1.7 christos <pre> 652 1.7 christos $ make makefiles config_directory=/some/where ...other arguments... 653 1.7 christos $ make 654 1.7 christos </pre> 655 1.7 christos </blockquote> 656 1.7 christos 657 1.7 christos <p> The command "make makefiles name=value ..." will replace the 658 1.7 christos string MAIL_VERSION at the end of a configuration parameter value 659 1.7 christos with the Postfix release version. Do not try to specify something 660 1.7 christos like $mail_version on this command line. This produces inconsistent 661 1.7 christos results with different versions of the make(1) command. </p> 662 1.7 christos 663 1.7 christos <p> Parameters whose defaults can be specified in this way are 664 1.7 christos listed below. See the postconf(5) manpage for a description 665 1.7 christos (command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> 666 1.7 christos 667 1.7 christos <blockquote> 668 1.7 christos 669 1.7 christos <table border="1"> 670 1.7 christos 671 1.7 christos <tr> <th>parameter name</th> <th>typical default</th> </tr> 672 1.7 christos 673 1.7 christos <tr> <td>command_directory</td> <td>/usr/sbin</td> </tr> 674 1.7 christos 675 1.7 christos <tr> <td>config_directory</td> <td>/etc/postfix</td> </tr> 676 1.7 christos 677 1.12 christos <tr> <td>default_database_type</td> <td>lmdb, cdb, or hash</td> </tr> 678 1.12 christos 679 1.12 christos <tr> <td>default_cache_db_type</td> <td>lmdb or btree</td> </tr> 680 1.7 christos 681 1.7 christos <tr> <td>daemon_directory</td> <td>/usr/libexec/postfix</td> </tr> 682 1.7 christos 683 1.7 christos <tr> <td>data_directory</td> <td>/var/lib/postfix</td> </tr> 684 1.7 christos 685 1.7 christos <tr> <td>html_directory</td> <td>no</td> </tr> 686 1.7 christos 687 1.7 christos <tr> <td>mail_spool_directory</td> <td>/var/mail</td> </tr> 688 1.7 christos 689 1.7 christos <tr> <td>mailq_path</td> <td>/usr/bin/mailq</td> </tr> 690 1.7 christos 691 1.7 christos <tr> <td>manpage_directory</td> <td>/usr/local/man</td> </tr> 692 1.7 christos 693 1.7 christos <tr> <td>meta_directory</td> <td>/etc/postfix</td> </tr> 694 1.7 christos 695 1.7 christos <tr> <td>newaliases_path</td> <td>/usr/bin/newaliases</td> </tr> 696 1.7 christos 697 1.7 christos <tr> <td>openssl_path</td> <td>openssl</td> </tr> 698 1.7 christos 699 1.7 christos <tr> <td>queue_directory</td> <td>/var/spool/postfix</td> </tr> 700 1.7 christos 701 1.7 christos <tr> <td>readme_directory</td> <td>no</td> </tr> 702 1.7 christos 703 1.7 christos <tr> <td>sendmail_path</td> <td>/usr/sbin/sendmail</td> </tr> 704 1.7 christos 705 1.7 christos <tr> <td>shlib_directory</td> <td>/usr/lib/postfix</td> </tr> 706 1.7 christos 707 1.7 christos </table> 708 1.7 christos 709 1.7 christos </blockquote> 710 1.7 christos 711 1.7 christos <h4>4.6.2 - All Postfix versions </h4> 712 1.1 tron 713 1.1 tron <p> All Postfix configuration parameters can be changed by editing 714 1.1 tron a Postfix configuration file, except for one: the parameter that 715 1.1 tron specifies the location of Postfix configuration files. In order to 716 1.1 tron build Postfix with a configuration directory other than /etc/postfix, 717 1.1 tron use: </p> 718 1.1 tron 719 1.1 tron <blockquote> 720 1.1 tron <pre> 721 1.10 christos $ make makefiles CCARGS="-DDEF_CONFIG_DIR=\\\"/some/where\\\"" 722 1.5 tron $ make 723 1.1 tron </pre> 724 1.1 tron </blockquote> 725 1.1 tron 726 1.1 tron <p> IMPORTANT: Be sure to get the quotes right. These details matter 727 1.1 tron a lot. </p> 728 1.1 tron 729 1.7 christos <p> Parameters whose defaults can be specified in this way are 730 1.7 christos listed below. See the postconf(5) manpage for a description 731 1.7 christos (command: "<tt>nroff -man man/man5/postconf.5 | less</tt>"). </p> 732 1.1 tron 733 1.1 tron <blockquote> 734 1.1 tron 735 1.1 tron <table border="1"> 736 1.1 tron 737 1.1 tron <tr><th> Macro name </th> <th>default value for</th> <th>typical 738 1.1 tron default</th> </tr> 739 1.1 tron 740 1.1 tron <tr> <td>DEF_COMMAND_DIR</td> <td>command_directory</td> 741 1.1 tron <td>/usr/sbin</td> </tr> 742 1.1 tron 743 1.1 tron <tr> <td>DEF_CONFIG_DIR</td> <td>config_directory</td> 744 1.1 tron <td>/etc/postfix</td> </tr> 745 1.1 tron 746 1.6 tron <tr> <td>DEF_DB_TYPE</td> <td>default_database_type</td> 747 1.12 christos <td>lmdb, cdb, or hash</td> </tr> 748 1.12 christos 749 1.12 christos <tr> <td>DEF_CACHE_DB_TYPE</td> <td>default_cache_db_type</td> 750 1.12 christos <td>lmdb or btree</td> </tr> 751 1.6 tron 752 1.1 tron <tr> <td>DEF_DAEMON_DIR</td> <td>daemon_directory</td> 753 1.1 tron <td>/usr/libexec/postfix</td> </tr> 754 1.1 tron 755 1.1 tron <tr> <td>DEF_DATA_DIR</td> <td>data_directory</td> 756 1.2 tron <td>/var/db/postfix</td> </tr> 757 1.1 tron 758 1.1 tron <tr> <td>DEF_MAILQ_PATH</td> <td>mailq_path</td> <td>/usr/bin/mailq</td> 759 1.1 tron </tr> 760 1.1 tron 761 1.1 tron <tr> <td>DEF_HTML_DIR</td> <td>html_directory</td> 762 1.1 tron <td>no</td> </tr> 763 1.1 tron 764 1.1 tron <tr> <td>DEF_MANPAGE_DIR</td> <td>manpage_directory</td> 765 1.1 tron <td>/usr/local/man</td> </tr> 766 1.1 tron 767 1.1 tron <tr> <td>DEF_NEWALIAS_PATH</td> <td>newaliases_path</td> 768 1.1 tron <td>/usr/bin/newaliases</td> </tr> 769 1.1 tron 770 1.1 tron <tr> <td>DEF_QUEUE_DIR</td> <td>queue_directory</td> 771 1.1 tron <td>/var/spool/postfix</td> </tr> 772 1.1 tron 773 1.1 tron <tr> <td>DEF_README_DIR</td> <td>readme_directory</td> 774 1.1 tron <td>no</td> </tr> 775 1.1 tron 776 1.1 tron <tr> <td>DEF_SENDMAIL_PATH</td> <td>sendmail_path</td> 777 1.1 tron <td>/usr/sbin/sendmail</td> </tr> 778 1.1 tron 779 1.12 christos <tr> <td>DEF_SHLIB_DIR</td> <td>shlib_directory</td> 780 1.12 christos <td>/usr/lib/postfix</td> </tr> 781 1.12 christos 782 1.1 tron </table> 783 1.1 tron 784 1.1 tron </blockquote> 785 1.1 tron 786 1.1 tron <p> Note: the data_directory parameter (for caches and pseudo-random 787 1.12 christos numbers) was introduced with Postfix version 2.5; shlib_directory 788 1.12 christos (for shared-library objects and database plugins) with Postfix 789 1.12 christos version 3.0. </p> 790 1.1 tron 791 1.7 christos <h3><a name="build_other">4.7 - Overriding other compile-time 792 1.7 christos features</a></h3> 793 1.4 tron 794 1.4 tron <p> The general method to override Postfix compile-time features 795 1.4 tron is as follows: </p> 796 1.4 tron 797 1.4 tron <blockquote> 798 1.4 tron <pre> 799 1.5 tron $ make makefiles name=value name=value... 800 1.5 tron $ make 801 1.4 tron </pre> 802 1.4 tron </blockquote> 803 1.4 tron 804 1.4 tron <p> The following is an extensive list of names and values. </p> 805 1.4 tron 806 1.4 tron <table border="1"> 807 1.4 tron 808 1.4 tron <tr> <th colspan="2"> Name/Value </th> <th> Description </th> </tr> 809 1.4 tron 810 1.4 tron <tr> <td colspan="2"> AUXLIBS="object_library..."</td> <td> Specifies 811 1.7 christos one or more non-default object libraries. Postfix 3.0 and later 812 1.7 christos specify some of their database library dependencies with AUXLIBS_CDB, 813 1.7 christos AUXLIBS_LDAP, AUXLIBS_LMDB, AUXLIBS_MYSQL, AUXLIBS_PCRE, AUXLIBS_PGSQL, 814 1.7 christos AUXLIBS_SDBM, and AUXLIBS_SQLITE, respectively. </td> </tr> 815 1.4 tron 816 1.4 tron <tr> <td colspan="2"> CC=compiler_command</td> <td> Specifies a 817 1.4 tron non-default compiler. On many systems, the default is <tt>gcc</tt>. 818 1.4 tron </td> </tr> 819 1.4 tron 820 1.4 tron <tr> <td colspan="2"> CCARGS="compiler_arguments..."</td> <td> 821 1.4 tron Specifies non-default compiler arguments, for example, a non-default 822 1.4 tron <tt>include</tt> directory. The following directives turn 823 1.4 tron off Postfix features at compile time:</td> </tr> 824 1.4 tron 825 1.4 tron <tr> <td> </td> <td> -DNO_DB </td> <td> Do not build with Berkeley 826 1.4 tron DB support. By default, Berkeley DB support is compiled in on 827 1.12 christos platforms that have historically supported this feature. If you override 828 1.12 christos this, then you probably should also override default_database_type 829 1.12 christos or DEF_DB_TYPE as described in section 4.6. </td> </tr> 830 1.7 christos 831 1.7 christos <tr> <td> </td> <td> -DNO_DNSSEC </td> <td> Do not build with DNSSEC 832 1.7 christos support, even if the resolver library appears to support it. </td> 833 1.7 christos </tr> 834 1.4 tron 835 1.4 tron <tr> <td> </td> <td> -DNO_DEVPOLL </td> <td> Do not build with 836 1.4 tron Solaris <tt>/dev/poll</tt> support. By default, <tt>/dev/poll</tt> 837 1.4 tron support is compiled in on Solaris versions that are known to support 838 1.4 tron this feature. </td> </tr> 839 1.4 tron 840 1.4 tron <tr> <td> </td> <td> -DNO_EPOLL </td> <td> Do not build with Linux 841 1.4 tron EPOLL support. By default, EPOLL support is compiled in on platforms 842 1.4 tron that are known to support this feature. </td> </tr> 843 1.4 tron 844 1.7 christos <tr> <td> </td> <td> -DNO_EAI </td> <td> Do not build with EAI 845 1.7 christos (SMTPUTF8) support. By default, EAI support is compiled in when 846 1.7 christos the "icuuc" library and header files are found. </td> </tr> 847 1.7 christos 848 1.7 christos <tr> <td> </td> <td> -DNO_INLINE </td> <td> Do not require support 849 1.7 christos for C99 "inline" functions. Instead, implement argument typechecks 850 1.7 christos for non-printf/scanf-like functions with ternary operators and 851 1.7 christos unreachable code. </td> </tr> 852 1.7 christos 853 1.4 tron <tr> <td> </td> <td> -DNO_IPV6 </td> <td> Do not build with IPv6 854 1.4 tron support. By default, IPv6 support is compiled in on platforms that 855 1.4 tron are known to have IPv6 support. Note: this directive is for debugging 856 1.10 christos and testing only. It is not guaranteed to work on all platforms. 857 1.8 christos If you don't want IPv6 support, set "inet_protocols = ipv4" in 858 1.8 christos main.cf. 859 1.4 tron </td> </tr> 860 1.4 tron 861 1.4 tron <tr> <td> </td> <td> -DNO_KQUEUE </td> <td> Do not build with FreeBSD 862 1.4 tron / NetBSD / OpenBSD / MacOSX KQUEUE support. By default, KQUEUE 863 1.4 tron support is compiled in on platforms that are known to support it. 864 1.4 tron </td> </tr> 865 1.4 tron 866 1.4 tron <tr> <td> </td> <td> -DNO_NIS </td> <td> Do not build with NIS or 867 1.6 tron NISPLUS support. NIS is not available on some recent Linux 868 1.6 tron distributions. </td> </tr> 869 1.6 tron 870 1.6 tron <tr> <td> </td> <td> -DNO_NISPLUS </td> <td> Do not build with 871 1.6 tron NISPLUS support. NISPLUS is not available on some recent Solaris 872 1.4 tron distributions. </td> </tr> 873 1.4 tron 874 1.4 tron <tr> <td> </td> <td> -DNO_PCRE </td> <td> Do not build with PCRE 875 1.4 tron support. By default, PCRE support is compiled in when the 876 1.4 tron <tt>pcre-config</tt> utility is installed. </td> </tr> 877 1.4 tron 878 1.4 tron <tr> <td> </td> <td> -DNO_POSIX_GETPW_R </td> <td> Disable support 879 1.4 tron for POSIX <tt>getpwnam_r/getpwuid_r</tt>. By default Postfix uses 880 1.4 tron these where they are known to be available. </td> </tr> 881 1.4 tron 882 1.9 christos <tr> <td> </td> <td> -DNO_RES_NCALLS </td> <td> Do not build with 883 1.9 christos the threadsafe resolver(5) API (res_ninit() etc.). </td> </tr> 884 1.9 christos 885 1.4 tron <tr> <td> </td> <td> -DNO_SIGSETJMP </td> <td> Use 886 1.4 tron <tt>setjmp()/longjmp()</tt> instead of <tt>sigsetjmp()/siglongjmp()</tt>. 887 1.4 tron By default, Postfix uses <tt>sigsetjmp()/siglongjmp()</tt> when 888 1.4 tron they are known to be available. </td> </tr> 889 1.4 tron 890 1.8 christos <tr> <td> </td> <td> -DNO_SNPRINTF </td> <td> Use <tt>sprintf()</tt> 891 1.8 christos instead of <tt>snprintf()</tt>. By default, Postfix uses 892 1.8 christos <tt>snprintf()</tt> except on ancient systems. </td> </tr> 893 1.8 christos 894 1.4 tron <tr> <td colspan="2"> DEBUG=debug_level </td> <td> Specifies a 895 1.7 christos non-default compiler debugging level. The default is "<tt>-g</tt>". 896 1.4 tron Specify DEBUG= to turn off debugging. </td> </tr> 897 1.4 tron 898 1.4 tron <tr> <td colspan="2"> OPT=optimization_level </td> <td> Specifies 899 1.7 christos a non-default optimization level. The default is "<tt>-O</tt>". 900 1.7 christos Specify OPT= to turn off optimization. </td> </tr> 901 1.7 christos 902 1.8 christos <tr> <td colspan="2"> POSTFIX_INSTALL_OPTS=-option... </td> <td> 903 1.8 christos Specifies options for the <tt>postfix-install</tt> command, separated 904 1.8 christos by whitespace. Currently, the only supported option is 905 1.8 christos "<tt>-keep-build-mtime</tt>". </td> </tr> 906 1.8 christos 907 1.7 christos <tr> <td colspan="2"> SHLIB_CFLAGS=flags </td> <td> Specifies 908 1.7 christos non-default compiler options for building Postfix dynamically-linked 909 1.7 christos libraries and database plugins. The typical default is "-fPIC". 910 1.7 christos </td> </tr> 911 1.7 christos 912 1.7 christos <tr> <td colspan="2"> SHLIB_RPATH=rpath </td> <td> Specifies 913 1.7 christos a non-default runpath for Postfix dynamically-linked libraries. The 914 1.7 christos typical default is "'-Wl,-rpath,${SHLIB_DIR}'". </td> </tr> 915 1.7 christos 916 1.7 christos <tr> <td colspan="2"> SHLIB_SUFFIX=suffix </td> <td> Specifies 917 1.7 christos a non-default suffix for Postfix dynamically-linked libraries and 918 1.7 christos database plugins. The typical default is "<tt>.so</tt>". </td> 919 1.7 christos </tr> 920 1.4 tron 921 1.4 tron <tr> <td colspan="2"> WARN="warning_flags..." </td> <td> Specifies 922 1.7 christos non-default compiler warning options for use when "<tt>make</tt>" 923 1.7 christos is invoked in a source subdirectory only. </td> 924 1.4 tron </tr> 925 1.4 tron 926 1.4 tron </table> 927 1.4 tron 928 1.7 christos <h3><a name="build_proc">4.8 - Support for thousands of processes</a></h3> 929 1.1 tron 930 1.1 tron <p> The number of connections that Postfix can manage simultaneously 931 1.1 tron is limited by the number of processes that it can run. This number 932 1.1 tron in turn is limited by the number of files and sockets that a single 933 1.1 tron process can open. For example, the Postfix queue manager has a 934 1.1 tron separate connection to each delivery process, and the anvil(8) 935 1.1 tron server has one connection per smtpd(8) process. </p> 936 1.1 tron 937 1.1 tron <p> Postfix version 2.4 and later have no built-in limits on the 938 1.1 tron number of open files or sockets, when compiled on systems that 939 1.1 tron support one of the following: </p> 940 1.1 tron 941 1.1 tron <ul> 942 1.1 tron 943 1.1 tron <li> BSD kqueue(2) (FreeBSD 4.1, NetBSD 2.0, OpenBSD 2.9), 944 1.1 tron 945 1.1 tron <li> Solaris 8 /dev/poll, 946 1.1 tron 947 1.1 tron <li> Linux 2.6 epoll(4). 948 1.1 tron 949 1.1 tron </ul> 950 1.1 tron 951 1.1 tron 952 1.1 tron <p> With other Postfix versions or operating systems, the number 953 1.1 tron of file descriptors per process is limited by the value of the 954 1.1 tron FD_SETSIZE macro. If you expect to run more than 1000 mail delivery 955 1.1 tron processes, you may need to override the definition of the FD_SETSIZE 956 1.1 tron macro to make select() work correctly: </p> 957 1.1 tron 958 1.1 tron <blockquote> 959 1.1 tron <pre> 960 1.5 tron $ make makefiles CCARGS=-DFD_SETSIZE=2048 961 1.1 tron </pre> 962 1.1 tron </blockquote> 963 1.1 tron 964 1.1 tron <p> Warning: the above has no effect on some Linux versions. 965 1.1 tron Apparently, on these systems the FD_SETSIZE value can be changed 966 1.1 tron only by using undocumented interfaces. Currently, that means 967 1.1 tron including <bits/types.h> directly (which is not allowed) and 968 1.1 tron overriding the __FD_SETSIZE macro. Beware, undocumented interfaces 969 1.1 tron can change at any time and without warning. </p> 970 1.1 tron 971 1.1 tron <p> But wait, there is more: none of this will work unless the 972 1.1 tron operating system is configured to handle thousands of connections. 973 1.1 tron See the TUNING_README guide for examples of how to increase the 974 1.1 tron number of open sockets or files. </p> 975 1.1 tron 976 1.7 christos <h3><a name="build_final">4.9 - Compiling Postfix, at last</a></h3> 977 1.1 tron 978 1.1 tron <p> If the command </p> 979 1.1 tron 980 1.1 tron <blockquote> 981 1.1 tron <pre> 982 1.5 tron $ make 983 1.1 tron </pre> 984 1.1 tron </blockquote> 985 1.1 tron 986 1.1 tron <p> is successful, then you can proceed to <a href="#install">install</a> 987 1.1 tron Postfix (section 6). 988 1.1 tron 989 1.1 tron <p> If the command produces compiler error messages, it may be time 990 1.1 tron to search the web or to ask the postfix-users (a] postfix.org mailing 991 1.1 tron list, but be sure to search the mailing list archives first. Some 992 1.11 christos mailing list archives are linked from https://www.postfix.org/. </p> 993 1.1 tron 994 1.1 tron <h2> <a name="5">5 - Porting Postfix to an unsupported system</a> </h2> 995 1.1 tron 996 1.1 tron <p> Each system type that Postfix knows is identified by a unique 997 1.1 tron name. Examples: SUNOS5, FREEBSD4, and so on. When porting Postfix 998 1.1 tron to a new system, the first step is to choose a SYSTEMTYPE name for 999 1.1 tron the new system. You must use a name that includes at least the 1000 1.1 tron major version of the operating system (such as SUNOS4 or LINUX2), 1001 1.1 tron so that different releases of the same system can be supported 1002 1.1 tron without confusion. </p> 1003 1.1 tron 1004 1.1 tron <p> Add a case statement to the "makedefs" shell script in the 1005 1.1 tron source code top-level directory that recognizes the new system 1006 1.1 tron reliably, and that emits the right system-specific information. 1007 1.1 tron Be sure to make the code robust against user PATH settings; if the 1008 1.1 tron system offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to 1009 1.1 tron build for the native flavor, instead of the emulated one. </p> 1010 1.1 tron 1011 1.1 tron <p> Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h 1012 1.1 tron include file. You may have to invent new feature macro names. 1013 1.1 tron Please choose sensible feature macro names such as HAS_DBM or 1014 1.1 tron FIONREAD_IN_SYS_FILIO_H. 1015 1.1 tron 1016 1.1 tron <p> I strongly recommend against using "#ifdef SYSTEMTYPE" in 1017 1.1 tron individual source files. While this may look like the quickest 1018 1.1 tron solution, it will create a mess when newer versions of the same 1019 1.1 tron SYSTEMTYPE need to be supported. You're likely to end up placing 1020 1.1 tron "#ifdef" sections all over the source code again. </p> 1021 1.1 tron 1022 1.1 tron <h2><a name="install">6 - Installing the software after successful 1023 1.1 tron compilation</a></h2> 1024 1.1 tron 1025 1.1 tron <p> This text describes how to install Postfix from source code. 1026 1.1 tron See the PACKAGE_README file if you are building a package for 1027 1.1 tron distribution to other systems. </p> 1028 1.1 tron 1029 1.1 tron <h3>6.1 - Save existing Sendmail binaries</h3> 1030 1.1 tron 1031 1.1 tron <p> <a name="save">IMPORTANT</a>: if you are REPLACING an existing 1032 1.1 tron Sendmail installation with Postfix, you may need to keep the old 1033 1.1 tron sendmail program running for some time in order to flush the mail 1034 1.1 tron queue. </p> 1035 1.1 tron 1036 1.1 tron <ul> 1037 1.1 tron 1038 1.1 tron <li> <p> Some systems implement a mail switch mechanism where 1039 1.1 tron different MTAs (Postfix, Sendmail, etc.) can be installed at the 1040 1.1 tron same time, while only one of them is actually being used. Examples 1041 1.1 tron of such switching mechanisms are the FreeBSD mailwrapper(8) or the 1042 1.1 tron Linux mail switch. In this case you should try to "flip" the switch 1043 1.1 tron to "Postfix" before installing Postfix. </p> 1044 1.1 tron 1045 1.1 tron <li> <p> If your system has no mail switch mechanism, execute the 1046 1.1 tron following commands (your sendmail, newaliases and mailq programs 1047 1.1 tron may be in a different place): </p> 1048 1.1 tron 1049 1.1 tron <pre> 1050 1.1 tron # mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF 1051 1.1 tron # mv /usr/bin/newaliases /usr/bin/newaliases.OFF 1052 1.1 tron # mv /usr/bin/mailq /usr/bin/mailq.OFF 1053 1.1 tron # chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ 1054 1.1 tron /usr/bin/mailq.OFF 1055 1.1 tron </pre> 1056 1.1 tron 1057 1.1 tron </ul> 1058 1.1 tron 1059 1.1 tron <h3>6.2 - Create account and groups</h3> 1060 1.1 tron 1061 1.1 tron <p> Before you install Postfix for the first time you need to 1062 1.1 tron create an account and a group:</p> 1063 1.1 tron 1064 1.1 tron <ul> 1065 1.1 tron 1066 1.1 tron <li> <p> Create a user account "postfix" with a user id and group 1067 1.1 tron id that are not used by any other user account. Preferably, this 1068 1.1 tron is an account that no-one can log into. The account does not need 1069 1.1 tron an executable login shell, and needs no existing home directory. 1070 1.1 tron My password and group file entries look like this: </p> 1071 1.1 tron 1072 1.1 tron <blockquote> 1073 1.1 tron <pre> 1074 1.1 tron /etc/passwd: 1075 1.1 tron postfix:*:12345:12345:postfix:/no/where:/no/shell 1076 1.1 tron 1077 1.1 tron /etc/group: 1078 1.1 tron postfix:*:12345: 1079 1.1 tron </pre> 1080 1.1 tron </blockquote> 1081 1.1 tron 1082 1.1 tron <p> Note: there should be no whitespace before "postfix:". </p> 1083 1.1 tron 1084 1.1 tron <li> <p> Create a group "postdrop" with a group id that is not used 1085 1.1 tron by any other user account. Not even by the postfix user account. 1086 1.1 tron My group file entry looks like: 1087 1.1 tron 1088 1.1 tron <blockquote> 1089 1.1 tron <pre> 1090 1.1 tron /etc/group: 1091 1.1 tron postdrop:*:54321: 1092 1.1 tron </pre> 1093 1.1 tron </blockquote> 1094 1.1 tron 1095 1.1 tron <p> Note: there should be no whitespace before "postdrop:". </p> 1096 1.1 tron 1097 1.1 tron </ul> 1098 1.1 tron 1099 1.1 tron <h3>6.3 - Install Postfix</h3> 1100 1.1 tron 1101 1.1 tron <p> To install or upgrade Postfix from compiled source code, run 1102 1.1 tron one of the following commands as the super-user:</p> 1103 1.1 tron 1104 1.1 tron <blockquote> 1105 1.1 tron <pre> 1106 1.1 tron # make install (interactive version, first time install) 1107 1.1 tron 1108 1.1 tron # make upgrade (non-interactive version, for upgrades) 1109 1.1 tron </pre> 1110 1.1 tron </blockquote> 1111 1.1 tron 1112 1.1 tron <ul> 1113 1.1 tron 1114 1.1 tron <li> <p> The interactive version ("make install") asks for pathnames 1115 1.1 tron for Postfix data and program files, and stores your preferences in 1116 1.1 tron the main.cf file. <b> If you don't want Postfix to overwrite 1117 1.1 tron non-Postfix "sendmail", "mailq" and "newaliases" files, specify 1118 1.1 tron pathnames that end in ".postfix"</b>. </p> 1119 1.1 tron 1120 1.1 tron <li> <p> The non-interactive version ("make upgrade") needs the 1121 1.1 tron /etc/postfix/main.cf file from a previous installation. If the file 1122 1.1 tron does not exist, use interactive installation ("make install") 1123 1.1 tron instead. </p> 1124 1.1 tron 1125 1.7 christos <li> <p> If you specify name=value arguments on the "make install" 1126 1.7 christos or "make upgrade" command line, then these will take precedence 1127 1.7 christos over compiled-in default settings or main.cf settings. </p> 1128 1.7 christos 1129 1.7 christos <p> The command "make install/upgrade name=value ..." will replace 1130 1.7 christos the string MAIL_VERSION at the end of a configuration parameter 1131 1.7 christos value with the Postfix release version. Do not try to specify 1132 1.7 christos something like $mail_version on this command line. This produces 1133 1.7 christos inconsistent results with different versions of the make(1) command. 1134 1.7 christos </p> 1135 1.7 christos 1136 1.1 tron </ul> 1137 1.1 tron 1138 1.1 tron <h3>6.4 - Configure Postfix</h3> 1139 1.1 tron 1140 1.1 tron <p> Proceed to the section on how you wish to run Postfix on 1141 1.1 tron your particular machine: </p> 1142 1.1 tron 1143 1.1 tron <ul> 1144 1.1 tron 1145 1.1 tron <li> <p> <a href="#send_only">Send</a> mail only, without changing 1146 1.1 tron an existing Sendmail installation (section 7). </p> 1147 1.1 tron 1148 1.1 tron <li> <p> <a href="#send_receive">Send and receive</a> mail via a 1149 1.1 tron virtual host interface, still without any change to an existing 1150 1.1 tron Sendmail installation (section 8). </p> 1151 1.1 tron 1152 1.1 tron <li> <p> Run Postfix <a href="#replace">instead of</a> Sendmail 1153 1.1 tron (section 9). </p> 1154 1.1 tron 1155 1.1 tron </ul> 1156 1.1 tron 1157 1.1 tron <h2><a name="send_only">7 - Configuring Postfix to send mail 1158 1.1 tron only</a></h2> 1159 1.1 tron 1160 1.1 tron <p> If you are going to use Postfix to send mail only, there is no 1161 1.1 tron need to change your existing sendmail setup. Instead, set up your 1162 1.1 tron mail user agent so that it calls the Postfix sendmail program 1163 1.1 tron directly. </p> 1164 1.1 tron 1165 1.1 tron <p> Follow the instructions in the "<a href="#mandatory">Mandatory 1166 1.1 tron configuration file edits</a>" in section 10, and review the "<a 1167 1.1 tron href="#hamlet">To chroot or not to chroot</a>" text in section 1168 1.1 tron 11. </p> 1169 1.1 tron 1170 1.1 tron <p> You MUST comment out the "smtp inet" entry in /etc/postfix/master.cf, 1171 1.1 tron in order to avoid conflicts with the real sendmail. Put a "#" 1172 1.1 tron character in front of the line that defines the smtpd service: </p> 1173 1.1 tron 1174 1.1 tron <blockquote> 1175 1.1 tron <pre> 1176 1.1 tron /etc/postfix/master.cf: 1177 1.1 tron #smtp inet n - n - - smtpd 1178 1.1 tron </pre> 1179 1.1 tron </blockquote> 1180 1.1 tron 1181 1.1 tron <p> Start the Postfix system: </p> 1182 1.1 tron 1183 1.1 tron <blockquote> 1184 1.1 tron <pre> 1185 1.1 tron # postfix start 1186 1.1 tron </pre> 1187 1.1 tron </blockquote> 1188 1.1 tron 1189 1.1 tron <p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1190 1.1 tron 1191 1.1 tron <blockquote> 1192 1.1 tron <pre> 1193 1.1 tron # sendmail -bd -qwhatever 1194 1.1 tron </pre> 1195 1.1 tron </blockquote> 1196 1.1 tron 1197 1.1 tron <p> and watch your maillog file for any error messages. The pathname 1198 1.1 tron is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1199 1.1 tron else. Typically, the pathname is defined in the /etc/syslog.conf 1200 1.1 tron file. </p> 1201 1.1 tron 1202 1.1 tron <blockquote> 1203 1.1 tron <pre> 1204 1.10 christos $ grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1205 1.1 tron </pre> 1206 1.1 tron </blockquote> 1207 1.1 tron 1208 1.1 tron <p> Note: the most important error message is logged first. Later 1209 1.1 tron messages are not as useful. </p> 1210 1.1 tron 1211 1.1 tron <p> In order to inspect the mail queue, use one of the following 1212 1.1 tron commands: </p> 1213 1.1 tron 1214 1.1 tron <blockquote> 1215 1.1 tron <pre> 1216 1.5 tron $ mailq 1217 1.1 tron 1218 1.5 tron $ sendmail -bp 1219 1.1 tron 1220 1.5 tron $ postqueue -p 1221 1.1 tron </pre> 1222 1.1 tron </blockquote> 1223 1.1 tron 1224 1.1 tron <p> See also the "<a href="#care">Care and feeding</a>" section 12 1225 1.1 tron below. </p> 1226 1.1 tron 1227 1.1 tron <h2><a name="send_receive">8 - Configuring Postfix to send and 1228 1.1 tron receive mail via virtual interface</a></h2> 1229 1.1 tron 1230 1.1 tron <p> Alternatively, you can use the Postfix system to send AND 1231 1.1 tron receive mail while leaving your Sendmail setup intact, by running 1232 1.1 tron Postfix on a virtual interface address. Simply configure your mail 1233 1.1 tron user agent to directly invoke the Postfix sendmail program. </p> 1234 1.1 tron 1235 1.1 tron <p> To create a virtual network interface address, study your 1236 1.1 tron system ifconfig manual page. The command syntax could be any 1237 1.1 tron of: </p> 1238 1.1 tron 1239 1.1 tron <blockquote> 1240 1.1 tron <pre> 1241 1.1 tron # <b>ifconfig le0:1 <address> netmask <mask> up</b> 1242 1.1 tron # <b>ifconfig en0 alias <address> netmask 255.255.255.255</b> 1243 1.1 tron </pre> 1244 1.1 tron </blockquote> 1245 1.1 tron 1246 1.1 tron <p> In the /etc/postfix/main.cf file, I would specify </p> 1247 1.1 tron 1248 1.1 tron <blockquote> 1249 1.1 tron <pre> 1250 1.1 tron /etc/postfix/main.cf: 1251 1.1 tron myhostname = virtual.host.tld 1252 1.1 tron inet_interfaces = $myhostname 1253 1.1 tron mydestination = $myhostname 1254 1.1 tron </pre> 1255 1.1 tron </blockquote> 1256 1.1 tron 1257 1.1 tron <p> Follow the instructions in the "<a href="#mandatory">Mandatory 1258 1.1 tron configuration file edits</a>" in section 10, and review the "<a 1259 1.9 christos href="#hamlet">To chroot or not to chroot</a>" text in section 1260 1.1 tron 11. </p> 1261 1.1 tron 1262 1.1 tron <p> Start the Postfix system: </p> 1263 1.1 tron 1264 1.1 tron <blockquote> 1265 1.1 tron <pre> 1266 1.1 tron # postfix start 1267 1.1 tron </pre> 1268 1.1 tron </blockquote> 1269 1.1 tron 1270 1.1 tron <p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1271 1.1 tron 1272 1.1 tron <blockquote> 1273 1.1 tron <pre> 1274 1.1 tron # sendmail -bd -qwhatever 1275 1.1 tron </pre> 1276 1.1 tron </blockquote> 1277 1.1 tron 1278 1.1 tron <p> and watch your maillog file for any error messages. The pathname 1279 1.1 tron is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1280 1.1 tron else. Typically, the pathname is defined in the /etc/syslog.conf 1281 1.1 tron file. </p> 1282 1.1 tron 1283 1.1 tron <blockquote> 1284 1.1 tron <pre> 1285 1.10 christos $ grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1286 1.1 tron </pre> 1287 1.1 tron </blockquote> 1288 1.1 tron 1289 1.1 tron <p> Note: the most important error message is logged first. Later 1290 1.1 tron messages are not as useful. </p> 1291 1.1 tron 1292 1.1 tron <p> In order to inspect the mail queue, use one of the following 1293 1.1 tron commands: </p> 1294 1.1 tron 1295 1.1 tron <blockquote> 1296 1.1 tron <pre> 1297 1.5 tron $ mailq 1298 1.1 tron 1299 1.5 tron $ sendmail -bp 1300 1.1 tron 1301 1.5 tron $ postqueue -p 1302 1.1 tron </pre> 1303 1.1 tron </blockquote> 1304 1.1 tron 1305 1.1 tron <p> See also the "<a href="#care">Care and feeding</a>" section 12 1306 1.1 tron below. </p> 1307 1.1 tron 1308 1.1 tron <h2><a name="replace">9 - Running Postfix instead of Sendmail</a></h2> 1309 1.1 tron 1310 1.1 tron <p> Prior to installing Postfix you should <a href="#save">save</a> 1311 1.1 tron any existing sendmail program files as described in section 6. Be 1312 1.1 tron sure to keep the old sendmail running for at least a couple days 1313 1.1 tron to flush any unsent mail. To do so, stop the sendmail daemon and 1314 1.1 tron restart it as: </p> 1315 1.1 tron 1316 1.1 tron <blockquote> 1317 1.1 tron <pre> 1318 1.1 tron # /usr/sbin/sendmail.OFF -q 1319 1.1 tron </pre> 1320 1.1 tron </blockquote> 1321 1.1 tron 1322 1.1 tron <p> Note: this is old sendmail syntax. Newer versions use separate 1323 1.1 tron processes for mail submission and for running the queue. </p> 1324 1.1 tron 1325 1.1 tron <p> After you have visited the "<a href="#mandatory">Mandatory 1326 1.1 tron configuration file edits</a>" section below, you can start the 1327 1.1 tron Postfix system with: </p> 1328 1.1 tron 1329 1.1 tron <blockquote> 1330 1.1 tron <pre> 1331 1.1 tron # postfix start 1332 1.1 tron </pre> 1333 1.1 tron </blockquote> 1334 1.1 tron 1335 1.1 tron <p> or, if you feel nostalgic, use the Postfix sendmail command: </p> 1336 1.1 tron 1337 1.1 tron <blockquote> 1338 1.1 tron <pre> 1339 1.1 tron # sendmail -bd -qwhatever 1340 1.1 tron </pre> 1341 1.1 tron </blockquote> 1342 1.1 tron 1343 1.1 tron <p> and watch your maillog file for any error messages. The pathname 1344 1.1 tron is /var/log/maillog, /var/log/mail, /var/log/syslog, or something 1345 1.1 tron else. Typically, the pathname is defined in the /etc/syslog.conf 1346 1.1 tron file. </p> 1347 1.1 tron 1348 1.1 tron <blockquote> 1349 1.1 tron <pre> 1350 1.10 christos $ grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1351 1.1 tron </pre> 1352 1.1 tron </blockquote> 1353 1.1 tron 1354 1.1 tron <p> Note: the most important error message is logged first. Later 1355 1.1 tron messages are not as useful. </p> 1356 1.1 tron 1357 1.1 tron <p> In order to inspect the mail queue, use one of the following 1358 1.1 tron commands: </p> 1359 1.1 tron 1360 1.1 tron <blockquote> 1361 1.1 tron <pre> 1362 1.5 tron $ mailq 1363 1.1 tron 1364 1.5 tron $ sendmail -bp 1365 1.1 tron 1366 1.5 tron $ postqueue -p 1367 1.1 tron </pre> 1368 1.1 tron </blockquote> 1369 1.1 tron 1370 1.1 tron <p> See also the "<a href="#care">Care and feeding</a>" section 12 1371 1.1 tron below. </p> 1372 1.1 tron 1373 1.1 tron <h2><a name="mandatory">10 - Mandatory configuration file edits</a></h2> 1374 1.1 tron 1375 1.1 tron <p> Note: the material covered in this section is covered in more 1376 1.1 tron detail in the BASIC_CONFIGURATION_README document. The information 1377 1.1 tron presented below is targeted at experienced system administrators. 1378 1.1 tron </p> 1379 1.1 tron 1380 1.1 tron <h3>10.1 - Postfix configuration files</h3> 1381 1.1 tron 1382 1.1 tron <p> By default, Postfix configuration files are in /etc/postfix. 1383 1.1 tron The two most important files are main.cf and master.cf; these files 1384 1.1 tron must be owned by root. Giving someone else write permission to 1385 1.1 tron main.cf or master.cf (or to their parent directories) means giving 1386 1.1 tron root privileges to that person. </p> 1387 1.1 tron 1388 1.1 tron <p> In /etc/postfix/main.cf, you will have to set up a minimal number 1389 1.1 tron of configuration parameters. Postfix configuration parameters 1390 1.1 tron resemble shell variables, with two important differences: the first 1391 1.1 tron one is that Postfix does not know about quotes like the UNIX shell 1392 1.1 tron does.</p> 1393 1.1 tron 1394 1.1 tron <p> You specify a configuration parameter as: </p> 1395 1.1 tron 1396 1.1 tron <blockquote> 1397 1.1 tron <pre> 1398 1.1 tron /etc/postfix/main.cf: 1399 1.1 tron parameter = value 1400 1.1 tron </pre> 1401 1.1 tron </blockquote> 1402 1.1 tron 1403 1.1 tron <p> and you use it by putting a "$" character in front of its name: </p> 1404 1.1 tron 1405 1.1 tron <blockquote> 1406 1.1 tron <pre> 1407 1.1 tron /etc/postfix/main.cf: 1408 1.1 tron other_parameter = $parameter 1409 1.1 tron </pre> 1410 1.1 tron </blockquote> 1411 1.1 tron 1412 1.1 tron <p> You can use $parameter before it is given a value (that is the 1413 1.1 tron second main difference with UNIX shell variables). The Postfix 1414 1.1 tron configuration language uses lazy evaluation, and does not look at 1415 1.1 tron a parameter value until it is needed at runtime. </p> 1416 1.1 tron 1417 1.1 tron <p> Whenever you make a change to the main.cf or master.cf file, 1418 1.1 tron execute the following command in order to refresh a running mail 1419 1.1 tron system: </p> 1420 1.1 tron 1421 1.1 tron <blockquote> 1422 1.1 tron <pre> 1423 1.1 tron # postfix reload 1424 1.1 tron </pre> 1425 1.1 tron </blockquote> 1426 1.1 tron 1427 1.1 tron <h3>10.2 - Default domain for unqualified addresses</h3> 1428 1.1 tron 1429 1.1 tron <p> First of all, you must specify what domain will be appended to an 1430 1.1 tron unqualified address (i.e. an address without @domain.tld). The 1431 1.1 tron "myorigin" parameter defaults to the local hostname, but that is 1432 1.1 tron probably OK only for very small sites. </p> 1433 1.1 tron 1434 1.1 tron <p> Some examples (use only one): </p> 1435 1.1 tron 1436 1.1 tron <blockquote> 1437 1.1 tron <pre> 1438 1.1 tron /etc/postfix/main.cf: 1439 1.1 tron myorigin = $myhostname (send mail as "user@$myhostname") 1440 1.1 tron myorigin = $mydomain (send mail as "user@$mydomain") 1441 1.1 tron </pre> 1442 1.1 tron </blockquote> 1443 1.1 tron 1444 1.1 tron <h3>10.3 - What domains to receive locally</h3> 1445 1.1 tron 1446 1.1 tron <p> Next you need to specify what mail addresses Postfix should deliver 1447 1.1 tron locally. </p> 1448 1.1 tron 1449 1.1 tron <p> Some examples (use only one): </p> 1450 1.1 tron 1451 1.1 tron <blockquote> 1452 1.1 tron <pre> 1453 1.1 tron /etc/postfix/main.cf: 1454 1.1 tron mydestination = $myhostname, localhost.$mydomain, localhost 1455 1.1 tron mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain 1456 1.1 tron mydestination = $myhostname 1457 1.1 tron </pre> 1458 1.1 tron </blockquote> 1459 1.1 tron 1460 1.1 tron <p>The first example is appropriate for a workstation, the second 1461 1.1 tron is appropriate for the mailserver for an entire domain. The third 1462 1.1 tron example should be used when running on a virtual host interface.</p> 1463 1.1 tron 1464 1.1 tron <h3>10.4 - Proxy/NAT interface addresses </h3> 1465 1.1 tron 1466 1.1 tron <p> The proxy_interfaces parameter specifies all network addresses 1467 1.1 tron that Postfix receives mail on by way of a proxy or network address 1468 1.1 tron translation unit. You may specify symbolic hostnames instead of 1469 1.1 tron network addresses. </p> 1470 1.1 tron 1471 1.1 tron <p> IMPORTANT: You must specify your proxy/NAT external addresses 1472 1.1 tron when your system is a backup MX host for other domains, otherwise 1473 1.1 tron mail delivery loops will happen when the primary MX host is down. 1474 1.1 tron </p> 1475 1.1 tron 1476 1.1 tron <p> Example: host behind NAT box running a backup MX host. </p> 1477 1.1 tron 1478 1.1 tron <blockquote> 1479 1.1 tron <pre> 1480 1.1 tron /etc/postfix/main.cf: 1481 1.1 tron proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) 1482 1.1 tron </pre> 1483 1.1 tron </blockquote> 1484 1.1 tron 1485 1.1 tron <h3>10.5 - What local clients to relay mail from </h3> 1486 1.1 tron 1487 1.1 tron <p> If your machine is on an open network then you must specify 1488 1.1 tron what client IP addresses are authorized to relay their mail through 1489 1.1 tron your machine into the Internet. The default setting includes all 1490 1.1 tron subnetworks that the machine is attached to. This may give relay 1491 1.1 tron permission to too many clients. My own settings are: </p> 1492 1.1 tron 1493 1.1 tron <blockquote> 1494 1.1 tron <pre> 1495 1.1 tron /etc/postfix/main.cf: 1496 1.1 tron mynetworks = 168.100.189.0/28, 127.0.0.0/8 1497 1.1 tron </pre> 1498 1.1 tron </blockquote> 1499 1.1 tron 1500 1.1 tron <h3>10.6 - What relay destinations to accept from strangers </h3> 1501 1.1 tron 1502 1.1 tron <p> If your machine is on an open network then you must also specify 1503 1.1 tron whether Postfix will forward mail from strangers. The default 1504 1.1 tron setting will forward mail to all domains (and subdomains of) what 1505 1.1 tron is listed in $mydestination. This may give relay permission for 1506 1.1 tron too many destinations. Recommended settings (use only one): </p> 1507 1.1 tron 1508 1.1 tron <blockquote> 1509 1.1 tron <pre> 1510 1.1 tron /etc/postfix/main.cf: 1511 1.1 tron relay_domains = (do not forward mail from strangers) 1512 1.1 tron relay_domains = $mydomain (my domain and subdomains) 1513 1.1 tron relay_domains = $mydomain, other.domain.tld, ... 1514 1.1 tron </pre> 1515 1.1 tron </blockquote> 1516 1.1 tron 1517 1.1 tron <h3>10.7 - Optional: configure a smart host for remote delivery</h3> 1518 1.1 tron 1519 1.1 tron <p> If you're behind a firewall, you should set up a relayhost. If 1520 1.1 tron you can, specify the organizational domain name so that Postfix 1521 1.1 tron can use DNS lookups, and so that it can fall back to a secondary 1522 1.1 tron MX host when the primary MX host is down. Otherwise just specify 1523 1.1 tron a hard-coded hostname. </p> 1524 1.1 tron 1525 1.1 tron <p> Some examples (use only one): </p> 1526 1.1 tron 1527 1.1 tron <blockquote> 1528 1.1 tron <pre> 1529 1.1 tron /etc/postfix/main.cf: 1530 1.1 tron relayhost = $mydomain 1531 1.1 tron relayhost = [mail.$mydomain] 1532 1.1 tron </pre> 1533 1.1 tron </blockquote> 1534 1.1 tron 1535 1.1 tron <p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups. </p> 1536 1.1 tron 1537 1.1 tron <p> By default, the SMTP client will do DNS lookups even when you 1538 1.1 tron specify a relay host. If your machine has no access to a DNS server, 1539 1.1 tron turn off SMTP client DNS lookups like this: </p> 1540 1.1 tron 1541 1.1 tron <blockquote> 1542 1.1 tron <pre> 1543 1.1 tron /etc/postfix/main.cf: 1544 1.1 tron disable_dns_lookups = yes 1545 1.1 tron </pre> 1546 1.1 tron </blockquote> 1547 1.1 tron 1548 1.1 tron <p> The STANDARD_CONFIGURATION_README file has more hints and tips for 1549 1.1 tron firewalled and/or dial-up networks. </p> 1550 1.1 tron 1551 1.1 tron <h3>10.8 - Create the aliases database</h3> 1552 1.1 tron 1553 1.1 tron <p> Postfix uses a Sendmail-compatible aliases(5) table to redirect 1554 1.1 tron mail for local(8) recipients. Typically, this information is kept 1555 1.1 tron in two files: in a text file /etc/aliases and in an indexed file 1556 1.1 tron /etc/aliases.db. The command "postconf alias_maps" will tell you 1557 1.1 tron the exact location of the text file. </p> 1558 1.1 tron 1559 1.1 tron <p> First, be sure to update the text file with aliases for root, 1560 1.1 tron postmaster and "postfix" that forward mail to a real person. Postfix 1561 1.12 christos has a sample aliases file /etc/postfix/aliases that you can copy 1562 1.12 christos and adapt to local conditions. /p> 1563 1.1 tron 1564 1.1 tron <blockquote> 1565 1.1 tron <pre> 1566 1.1 tron /etc/aliases: 1567 1.1 tron root: you 1568 1.1 tron postmaster: root 1569 1.1 tron postfix: root 1570 1.1 tron bin: root 1571 1.1 tron <i>etcetera...</i> 1572 1.1 tron </pre> 1573 1.1 tron </blockquote> 1574 1.1 tron 1575 1.1 tron <p> Note: there should be no whitespace before the ":". </p> 1576 1.1 tron 1577 1.1 tron <p> Finally, build the indexed aliases file with one of the 1578 1.1 tron following commands: </p> 1579 1.1 tron 1580 1.1 tron <blockquote> 1581 1.1 tron <pre> 1582 1.1 tron # newaliases 1583 1.1 tron # sendmail -bi 1584 1.9 christos # postalias /etc/aliases (pathname is system dependent!) 1585 1.1 tron </pre> 1586 1.1 tron </blockquote> 1587 1.1 tron 1588 1.12 christos <p> The form "postalias /etc/aliases" builds a default-type indexed 1589 1.12 christos file. Use "postalias <i>type</i>:/etc/aliases" to specify an explicit 1590 1.12 christos type (it should match the type in the output from "postconf -x 1591 1.12 christos alias_maps"). </p> 1592 1.12 christos 1593 1.12 christos <p> The default indexed file type is configured with the 1594 1.12 christos default_database_type parameter. To list available explicit types, 1595 1.12 christos execute the command "<b>postconf -m</b>".</p> 1596 1.12 christos 1597 1.1 tron <h2><a name="hamlet">11 - To chroot or not to chroot</a></h2> 1598 1.1 tron 1599 1.1 tron <p> Postfix daemon processes can be configured (via master.cf) to 1600 1.1 tron run in a chroot jail. The processes run at a fixed low privilege 1601 1.1 tron and with access only to the Postfix queue directories (/var/spool/postfix). 1602 1.1 tron This provides a significant barrier against intrusion. The barrier 1603 1.1 tron is not impenetrable, but every little bit helps. </p> 1604 1.1 tron 1605 1.1 tron <p> With the exception of Postfix daemons that deliver mail locally 1606 1.1 tron and/or that execute non-Postfix commands, every Postfix daemon can 1607 1.1 tron run chrooted. </p> 1608 1.1 tron 1609 1.1 tron <p> Sites with high security requirements should consider to chroot 1610 1.1 tron all daemons that talk to the network: the smtp(8) and smtpd(8) 1611 1.1 tron processes, and perhaps also the lmtp(8) client. The author's own 1612 1.1 tron porcupine.org mail server runs all daemons chrooted that can be 1613 1.1 tron chrooted. </p> 1614 1.1 tron 1615 1.1 tron <p> The default /etc/postfix/master.cf file specifies that no 1616 1.1 tron Postfix daemon runs chrooted. In order to enable chroot operation, 1617 1.1 tron edit the file /etc/postfix/master.cf. Instructions are in the file. 1618 1.1 tron </p> 1619 1.1 tron 1620 1.1 tron <p> Note that a chrooted daemon resolves all filenames relative to 1621 1.1 tron the Postfix queue directory (/var/spool/postfix). For successful 1622 1.1 tron use of a chroot jail, most UNIX systems require you to bring in 1623 1.1 tron some files or device nodes. The examples/chroot-setup directory 1624 1.1 tron in the source code distribution has a collection of scripts that 1625 1.1 tron help you set up Postfix chroot environments on different operating 1626 1.1 tron systems. </p> 1627 1.1 tron 1628 1.1 tron <p> Additionally, you almost certainly need to configure syslogd 1629 1.1 tron so that it listens on a socket inside the Postfix queue directory. 1630 1.1 tron Examples for specific systems: </p> 1631 1.1 tron 1632 1.1 tron <dl> 1633 1.1 tron 1634 1.1 tron <dt> FreeBSD: </dt> 1635 1.1 tron 1636 1.1 tron <dd> <pre> 1637 1.1 tron # mkdir -p /var/spool/postfix/var/run 1638 1.1 tron # syslogd -l /var/spool/postfix/var/run/log 1639 1.1 tron </pre> </dd> 1640 1.1 tron 1641 1.1 tron <dt> Linux, OpenBSD: </dt> 1642 1.1 tron 1643 1.1 tron <dd> <pre> 1644 1.1 tron # mkdir -p /var/spool/postfix/dev 1645 1.1 tron # syslogd -a /var/spool/postfix/dev/log 1646 1.1 tron </pre> </dd> 1647 1.1 tron 1648 1.1 tron </dl> 1649 1.1 tron 1650 1.1 tron <h2><a name="care">12 - Care and feeding of the Postfix system</a></h2> 1651 1.1 tron 1652 1.1 tron <p> Postfix daemon processes run in the background, and log problems 1653 1.1 tron and normal activity to the syslog daemon. The names of logfiles 1654 1.1 tron are specified in /etc/syslog.conf. At the very least you need 1655 1.1 tron something like: </p> 1656 1.1 tron 1657 1.1 tron <blockquote> 1658 1.1 tron <pre> 1659 1.1 tron /etc/syslog.conf: 1660 1.1 tron mail.err /dev/console 1661 1.1 tron mail.debug /var/log/maillog 1662 1.1 tron </pre> 1663 1.1 tron </blockquote> 1664 1.1 tron 1665 1.1 tron <p> IMPORTANT: the syslogd will not create files. You must create 1666 1.1 tron them before (re)starting syslogd. </p> 1667 1.1 tron 1668 1.1 tron <p> IMPORTANT: on Linux you need to put a "-" character before 1669 1.1 tron the pathname, e.g., -/var/log/maillog, otherwise the syslogd 1670 1.1 tron will use more system resources than Postfix does. </p> 1671 1.1 tron 1672 1.1 tron <p> Hopefully, the number of problems will be small, but it is a good 1673 1.1 tron idea to run every night before the syslog files are rotated: </p> 1674 1.1 tron 1675 1.1 tron <blockquote> 1676 1.1 tron <pre> 1677 1.1 tron # postfix check 1678 1.10 christos # grep -E '(reject|warning|error|fatal|panic):' /some/log/file 1679 1.1 tron </pre> 1680 1.1 tron </blockquote> 1681 1.1 tron 1682 1.1 tron <ul> 1683 1.1 tron 1684 1.1 tron <li> <p> The first line (postfix check) causes Postfix to report 1685 1.1 tron file permission/ownership discrepancies. </p> 1686 1.1 tron 1687 1.1 tron <li> <p> The second line looks for problem reports from the mail 1688 1.1 tron software, and reports how effective the relay and junk mail access 1689 1.1 tron blocks are. This may produce a lot of output. You will want to 1690 1.1 tron apply some postprocessing to eliminate uninteresting information. 1691 1.1 tron </p> 1692 1.1 tron 1693 1.1 tron </ul> 1694 1.1 tron 1695 1.1 tron <p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a> 1696 1.1 tron document describes the meaning of the "warning" etc. labels in 1697 1.1 tron Postfix logging. </p> 1698 1.1 tron 1699 1.1 tron </body> 1700 1.1 tron 1701 1.1 tron </html> 1702
Indexes created Fri Jun 26 00:24:39 UTC 2026