postfix-master/basic.html

   1 <html>
   2
   3 <head>
   4
   5 <title> Postfix Configuration - Basics </title>
   6
   7 <META NAME="ROBOTS" CONTENT="NOINDEX,NOFOLLOW">
   8 </head>
   9
  10 <body background="obsolete.gif">
  11
  12 <h1><a href="big-picture.html"><img src="small-picture.gif" width="115" height="45"></a> Postfix Configuration - Basics </h1>
  13
  14 <hr>
  15
  16 <p> <strong> Note: this web page is no longer maintained. It exists
  17 only to avoid breaking links in web pages that describe earlier
  18 versions of the Postfix mail system. </strong> </p>
  19
  20 <a href="docs.html">Up one level</a> | Basic Configuration | <a
  21 href="uce.html">UCE Controls</a> | <a href="rate.html"> Rate
  22 Controls</a> | <a href="resource.html"> Resource Controls</a> | <a
  23 href="rewrite.html"> Address Manipulation </a>
  24
  25 <h2> Introduction </h2>
  26
  27 Postfix has several hundred configuration parameters that are controlled
  28 via the <b>main.cf</b> file.  Fortunately, they have sensible
  29 default values.  In most cases, you need to configure only two or
  30 three parameters before you can use the Postfix mail system:
  31
  32 <ul>
  33
  34 <li> <a href="#myorigin"> What domain to use in outbound mail </a>
  35
  36 <p>
  37
  38 <li> <a href="#mydestination"> What domains to receive mail for
  39 </a>
  40 <p>
  41
  42 <li> <a href="#relaying"> What clients to relay mail for </a>
  43
  44 </ul>
  45
  46 The default values for many other configuration parameters are
  47 derived from just these.
  48
  49 <p>
  50
  51 The next parameter of interest controls the amount of mail sent
  52 to the local postmaster:
  53
  54 <ul>
  55
  56 <li> <a href="#notify"> What trouble to report to the postmaster
  57 </a>
  58
  59 </ul>
  60
  61 <p>
  62
  63 Be sure to set the following correctly if you're behind a proxy or
  64 network address translator, and you are running a backup MX host
  65 for some other domain:
  66
  67 <p>
  68
  69 <ul>
  70
  71 <li> <a href="#proxy_interfaces"> Proxy/NAT network addresses </a>
  72
  73 </ul>
  74
  75 By the way, if you change parameters of a running Postfix system,
  76 don't forget to issue a <b>postfix reload</b> command.
  77
  78 <p>
  79
  80 If you run Postfix on a virtual network interface, or if your
  81 machine runs other mailers on virtual interfaces, you'll have to
  82 look at the other parameters listed here as well:
  83
  84 <ul>
  85
  86 <li> <a href="#myhostname"> My own hostname </a>
  87
  88 <p>
  89
  90 <li> <a href="#mydomain"> My own domain name </a>
  91
  92 <p>
  93
  94 <li> <a href="#mynetworks"> My own networks </a>
  95
  96 <p>
  97
  98 <li> <a href="#inet_interfaces"> My own network addresses </a>
  99
 100 </ul>
 101
 102 <a name="myorigin"> <h2> What domain to use in outbound mail </h2> </a>
 103
 104 The <b>myorigin</b> parameter specifies the domain that appears in
 105 mail that is posted on this machine. The default is to use the
 106 local machine name, <b><a href="#myhostname"> $myhostname</a>, </b>
 107 which defaults to the name of the machine. Unless you are running
 108 a really small site, you probably want to change that into <b><a
 109 href="#mydomain"> $mydomain</a>,</b> which defaults to the parent
 110 domain of the machine name.
 111
 112 <p>
 113
 114 For the sake of consistency between sender and recipient addresses,
 115 <b>myorigin</b> also specifies the default domain name that is
 116 appended to an unqualified recipient address.
 117
 118 <p>
 119
 120 <dl>
 121
 122 <dt> Examples:
 123
 124 <p>
 125
 126 <dd> <b>myorigin = $myhostname</b> (default)
 127
 128 <dd> <b>myorigin = $mydomain</b> (probably desirable)
 129
 130 </dl>
 131
 132 <a name="mydestination"> <h2> What domains to receive mail for
 133 </h2> </a>
 134
 135 The <b>mydestination</b> parameter specifies what domains this
 136 machine will deliver locally, instead of forwarding to another
 137 machine. The default is to receive mail for the machine itself.
 138
 139 <p>
 140
 141 You can specify zero or more domain names, <i>/file/name</i> patterns
 142 and/or <i>type:name</i> lookup tables, separated by whitespace
 143 and/or commas.  A <i>/file/name</i> is replaced by its contents;
 144 <i>type:name</i> requests that a table lookup is done.
 145
 146 <p>
 147
 148 If your machine is a mail server for its entire domain, you must
 149 list <b>$mydomain</b> as well.
 150
 151 <p>
 152
 153 <dl> Examples:
 154
 155 <p>
 156
 157 <dl>
 158
 159 <dt> Default setting:
 160
 161 <dd> <b>mydestination = $myhostname localhost.$mydomain</b>
 162
 163 <p>
 164
 165 <dt> Domain-wide mail server:
 166
 167 <dd> <b>mydestination = $myhostname localhost.$mydomain $mydomain
 168 </b>
 169
 170 <p>
 171
 172 <dt> Host with multiple DNS A records:
 173
 174 <dd> <b>mydestination = $myhostname localhost.$mydomain www.$mydomain
 175 ftp.$mydomain</b>
 176
 177 </dl>
 178
 179 <p>
 180
 181 Caution: in order to avoid mail delivery loops, you must list all
 182 hostnames of the machine, including $myhostname, and localhost.$mydomain.
 183
 184 </dl>
 185
 186 <a name="relaying"> <h2> What clients to relay mail for </h2> </a>
 187
 188 By default, Postfix will relay mail for clients in authorized
 189 networks.
 190
 191 <p>
 192
 193 Authorized client networks are defined by the <a
 194 href="#mynetworks">mynetworks</a> parameter. The default is to
 195 authorize all clients in the IP subnetworks that the local machine
 196 is attached to.
 197
 198 <a name="notify"> <h2> What trouble to report to the postmaster
 199 </h2> </a>
 200
 201 You should set up a <b>postmaster</b> <a
 202 href="rewrite.html#aliases">alias</a> that points to a human person.
 203 This alias is required to exist, so that people can report mail
 204 delivery problems.
 205
 206 <p>
 207
 208 The Postfix system itself also reports problems to the postmaster
 209 alias. You may not be interested in all types of trouble reports,
 210 so this reporting mechanism is configurable. The default is to
 211 report only serious problems (resource, software) to postmaster:
 212
 213 <p>
 214
 215 <dl>
 216
 217 <dt> Default:
 218
 219 <dd> <b>notify_classes = resource, software</b>
 220
 221 <p>
 222
 223 <dt>The meaning of the classes is as follows:
 224
 225 <p>
 226
 227 <dl>
 228
 229 <dt> <b>bounce</b> <dd> Send postmaster copies of undeliverable
 230 mail.  If mail is undeliverable, a so-called single bounce message
 231 is sent, with a copy of the message that was not delivered. For
 232 privacy reasons, the postmaster copy of a single bounce message is
 233 truncated after the original message headers.  If a single bounce
 234 message is undeliverable, the postmaster receives a double bounce
 235 message with a copy of the entire single bounce message.  See also
 236 the <a href="rewrite.html#luser_relay"> luser_relay</a> feature.
 237
 238 <p>
 239
 240 <dt> <b>2bounce</b> <dd> Send double bounces to the postmaster.
 241
 242 <p>
 243
 244 <dt> <b>delay</b> <dd> Inform the postmaster of delayed mail.
 245 In this case, the postmaster receives message headers only.
 246
 247 <p>
 248
 249 <dt> <b>policy</b> <dd> Inform the postmaster of client requests
 250 that were rejected because of (UCE) policy restrictions.  The
 251 postmaster receives a transcript of the entire SMTP session.
 252
 253 <p>
 254
 255 <dt> <b>protocol</b> <dd> Inform the postmaster of protocol errors
 256 (client or server side) or attempts by a client to execute
 257 unimplemented commands. The postmaster receives a transcript of
 258 the entire SMTP session.
 259
 260 <p>
 261
 262 <dt> <b>resource</b> <dd> Inform the postmaster of mail not delivered
 263 due to resource problems (for example, queue file write errors).
 264
 265 <p>
 266
 267 <dt> <b>software</b> <dd> Inform the postmaster of mail not delivered
 268 due to software problems.
 269
 270 </dl>
 271
 272 </dl>
 273
 274 <a name="proxy_interfaces"> <h2> Proxy/NAT network addresses </h2> </a>
 275
 276 The <b>proxy_interfaces</b> parameter specifies all network addresses
 277 that the Postfix receives mail on by way of a proxy or network
 278 address translation unit. You may specify symbolic hostnames instead
 279 of network addresses.
 280
 281 <p>
 282
 283 You must specify your proxy/NAT addresses when your system is a
 284 backup MX host for other domains, otherwise mail delivery loops
 285 will happen when the primary MX host is down.
 286
 287 <p>
 288
 289 <dl>
 290
 291 <dt> Examples:
 292
 293 <p>
 294
 295 <dl>
 296
 297 <dt> Default:
 298
 299 <dd> <b>proxy_interfaces = </b>
 300
 301 <p>
 302
 303 <dt> Host running backup MTA:
 304
 305 <dd> <b>proxy_interfaces = 1.2.3.4</b> (the proxy/NAT network address)
 306
 307 </dl>
 308
 309 </dl>
 310
 311 <a name="myhostname"> <h2> My own hostname </h2> </a>
 312
 313 The <b>myhostname</b> parameter describes the fully-qualified domain
 314 name of the machine running the Postfix system.  <b> $myhostname</b>
 315 appears as the default value in many other Postfix configuration
 316 parameters.
 317
 318 <p>
 319
 320 By default, <b>myhostname</b> is set to the local machine name.
 321 If your machine name is not in fully-qualified domain name form,
 322 or if you run Postfix on a virtual interface, you will have to
 323 specify the fully-qualified domain name that the mail system
 324 should use.
 325
 326 <dl>
 327
 328 <dt> Examples:
 329
 330 <p>
 331
 332 <dd> <b>myhostname = host.local.domain</b> (local hostname is not
 333 FQDN)
 334
 335 <dd> <b>myhostname = host.virtual.domain</b> (virtual interface)
 336
 337 <dd> <b>myhostname = virtual.domain</b> (virtual interface)
 338
 339 </dl>
 340
 341 <a name="mydomain"> <h2> My own domain name </h2> </a>
 342
 343 The <b>mydomain</b> parameter specifies the parent domain of
 344 <b>$myhostname.</b>  By default it is derived from <b> $myhostname</b>
 345 by stripping off the first part (unless the result would be a
 346 top-level domain).
 347
 348 <dl>
 349
 350 <dt> Examples:
 351
 352 <p>
 353
 354 <dd> <b>mydomain = local.domain</b>
 355
 356 <dd> <b>mydomain = virtual.domain</b> (virtual interface)
 357
 358 </dl>
 359
 360 <a name="mynetworks"> <h2> My own networks </h2> </a>
 361
 362 The <b>mynetworks</b> parameter lists all networks that this machine
 363 somehow trusts. This information can be used by the <a
 364 href="uce.html#smtpd_recipient_restrictions"> anti-UCE</a> features
 365 to recognize trusted SMTP clients that are allowed to relay mail
 366 through Postfix.
 367
 368 <p>
 369
 370 You can specify the list of trusted networks in the <b>main.cf</b>
 371 file, or you can let Postfix deduce the list for you. The default
 372 is to let Postfix do the work for you.
 373
 374 <p>
 375
 376 <dl>
 377
 378 <dt> Default:
 379
 380 <dd> <b>mynetworks_style = subnet</b>
 381
 382 <p>
 383
 384 <dt>The meaning of the styles is as follows:
 385
 386 <p>
 387
 388 <dl>
 389
 390 <dt> <b>class</b> <dd> Trust SMTP clients in the class A/B/C networks
 391 that Postfix is connected to. <b>Don't do this with a dialup site
 392 - it would cause Postfix to "trust" your entire provider's network.
 393 Instead, specify an explicit mynetworks list by hand, as described
 394 below</b>.
 395
 396 <p>
 397
 398 <dt> <b>subnet</b> (default) <dd> Trust SMTP clients in the IP
 399 subnetworks that Postfix is connected to.
 400
 401 <p>
 402
 403 <dt> <b>host</b> <dd> Trust only the local machine.
 404
 405 </dl>
 406
 407 </dl>
 408
 409 <p>
 410
 411 Alternatively, you can specify the <b>mynetworks</b> list by hand,
 412 in which case Postfix ignores the <b>mynetworks_style</b> setting.
 413 To specify the list of trusted networks by hand, specify network
 414 blocks in CIDR (network/mask) notation, for example:
 415
 416 <p>
 417
 418 <dl>
 419
 420 <dd> <b>mynetworks = 168.100.189.0/28, 127.0.0.0/8</b>
 421
 422 </dl>
 423
 424 <p>
 425
 426 You can also specify the absolute pathname of a pattern file instead
 427 of listing the patterns in the <b>main.cf</b> file.
 428
 429 <a name="inet_interfaces"> <h2> My own network addresses </h2> </a>
 430
 431 The <b>inet_interfaces</b> parameter specifies all network interface
 432 addresses that the Postfix system should listen on; mail addressed
 433 to <i>user</i>@[<i>network address</i>] will be delivered locally,
 434 as if it is addressed to a domain listed in <b> $mydestination.
 435 </b>
 436
 437 <p>
 438
 439 The default is to listen on all active interfaces.  If you run
 440 mailers on virtual interfaces, you will have to specify what
 441 interfaces to listen on.
 442
 443 <p>
 444
 445 You even have to specify explicit machine interfaces for the
 446 non-virtual mailer that receives mail for the machine itself: the
 447 non-virtual mailer should never listen on the virtual interfaces
 448 or you would have a mailer loop.
 449
 450 <dl>
 451
 452 <dt> Examples:
 453
 454 <p>
 455
 456 <dl>
 457
 458 <dt> Default:
 459
 460 <dd> <b>inet_interfaces = all</b>
 461
 462 <p>
 463
 464 <dt> Host running virtual mailers:
 465
 466 <dd> <b>inet_interfaces = virtual.host.tld</b> (virtual domain)
 467
 468 <dd> <b>inet_interfaces = $myhostname localhost.$mydomain</b>
 469 (non-virtual mailer)
 470
 471 </dl>
 472
 473 </dl>
 474
 475 <p>
 476
 477 <b>Note: you need to stop and start Postfix when this parameter changes.</b>
 478
 479 <hr>
 480
 481 <a href="docs.html">Up one level</a> | Basic Configuration | <a
 482 href="uce.html">UCE Controls</a> | <a href="rate.html"> Rate
 483 Controls</a> | <a href="resource.html"> Resource Controls</a> | <a
 484 href="rewrite.html"> Address Manipulation </a>
 485
 486 </body>
 487
 488 </html>