dist/proto/BASIC_CONFIGURATION_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title> Postfix Basic Configuration </title>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix Basic Configuration </h1>

<hr>

<h2> Introduction </h2>

<p> Postfix has several hundred configuration parameters that are
controlled via the main.cf file.  Fortunately, all parameters have
sensible default values.  In many cases, you need to configure only
two or three parameters before you can start to play with the mail
system. Here's a quick introduction to the syntax:  </p>

<ul>

<li> <p> <a href="#syntax">Postfix configuration files</a></p>

</ul>

<p> The text below assumes that you already have Postfix installed
on the system, either by compiling the source code yourself (as
described in the INSTALL file) or by installing an already compiled
version.  </p>

<p> This document covers basic Postfix configuration. Information
about how to configure Postfix for specific applications such as
mailhub, firewall or dial-up client can be found in the
STANDARD_CONFIGURATION_README file. But don't go there until you
already have covered the material presented below.  </p>

<p> The first parameters of interest specify the machine's identity
and role in the network. </p>

<ul>

<li> <p> <a href="#myorigin"> What domain name to use in outbound mail </a> </p>

<li> <p> <a href="#mydestination"> What domains to receive mail for </a> </p>

<li> <p> <a href="#relay_from"> What clients to relay mail from </a> </p>

<li> <p> <a href="#relay_to"> What destinations to relay mail to </a> </p>

<li> <p> <a href="#relayhost"> What delivery method: direct or
indirect </a> </p>

</ul>

<p> The default values for many other configuration parameters are
derived from just these. </p>

<p> The next parameter of interest controls the amount of mail sent
to the local postmaster: </p>

<ul>

<li> <p> <a href="#notify"> What trouble to report to the postmaster
</a> </p>

</ul>

<p> Be sure to set the following correctly if you're behind a proxy or
network address translator, and you are running a backup MX host
for some other domain: </p>

<ul>

<li> <p> <a href="#proxy_interfaces"> Proxy/NAT external network
addresses </a> </p>

</ul>

<p>  Postfix daemon processes run in the background, and log problems
and normal activity to the syslog daemon. Here are a few things
that you need to be aware of: </p>

<ul>

<li> <p> <a href="#syslog_howto"> What you need to know about
Postfix logging </a> </p>

</ul>

<p> If your machine has unusual security requirements you may
want to run Postfix daemon processes inside a chroot environment. </p>

<ul>

<li> <p> <a href="#chroot_setup"> Running Postfix daemon processes
chrooted </a> </p>

</ul>
<p> If you run Postfix on a virtual network interface, or if your
machine runs other mailers on virtual interfaces, you'll have to
look at the other parameters listed here as well: </p>

<ul>

<li> <p> <a href="#myhostname"> My own hostname </a> </p>

<li> <p> <a href="#mydomain"> My own domain name </a> </p>

<li> <p> <a href="#inet_interfaces"> My own network addresses </a> </p>

</ul>

<h2> <a name="syntax">Postfix configuration files</a></h2>

<p> By default, Postfix configuration files are in /etc/postfix.
The two most important files are main.cf and master.cf; these files
must be owned by root.  Giving someone else write permission to
main.cf or master.cf (or to their parent directories) means giving
root privileges to that person. </p>

<p> In /etc/postfix/main.cf you will have to set up a minimal number
of configuration parameters.  Postfix configuration parameters
resemble shell variables, with two important differences: the first
one is that Postfix does not know about quotes like the UNIX shell
does.</p>

<p> You specify a configuration parameter as: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    parameter = value
</pre>
</blockquote>

<p> and you use it by putting a "$" character in front of its name: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    other_parameter = $parameter
</pre>
</blockquote>

<p> You can use $parameter before it is given a value (that is the
second main difference with UNIX shell variables). The Postfix
configuration language uses lazy evaluation, and does not look at
a parameter value until it is needed at runtime.  </p>

<p> Postfix uses database files for access control, address rewriting
and other purposes. The DATABASE_README file gives an introduction
to how Postfix works with Berkeley DB, LDAP or SQL and other types.
Here is a common example of how Postfix invokes a database: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    virtual_alias_maps = hash:/etc/postfix/virtual
</pre>
</blockquote>

<p> Whenever you make a change to the main.cf or master.cf file,
execute the following command as root in order to refresh a running
mail system: </p>

<blockquote>
<pre>
# postfix reload
</pre>
</blockquote>

<h2> <a name="myorigin"> What domain name to use in outbound mail </a> </h2>

<p> The myorigin parameter specifies the domain that appears in
mail that is posted on this machine. The default is to use the
local machine name, $myhostname, which defaults to the name of the
machine. Unless you are running a really small site, you probably
want to change that into $mydomain, which defaults to the parent
domain of the machine name. </p>

<p> For the sake of consistency between sender and recipient addresses,
myorigin also specifies the domain name that is appended
to an unqualified recipient address. </p>

<p> Examples (specify only one of the following): </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    myorigin = $myhostname (default: send mail as "user@$myhostname")
    myorigin = $mydomain   (probably desirable: "user@$mydomain")
</pre>
</blockquote>

<h2><a name="mydestination"> What domains to receive mail for </a>
</h2>

<p> The mydestination parameter specifies what domains this
machine will deliver locally, instead of forwarding to another
machine. The default is to receive mail for the machine itself.
See the VIRTUAL_README file for how to configure Postfix for
hosted domains. </p>

<p> You can specify zero or more domain names, "/file/name" patterns
and/or "type:table" lookup tables (such as hash:, btree:, nis:, ldap:,
or mysql:), separated by whitespace and/or commas.  A "/file/name"
pattern is replaced by its contents; "type:table" requests that a
table lookup is done and merely tests for existence: the lookup
result is ignored.  </p>

<p> IMPORTANT: If your machine is a mail server for its entire
domain, you must list $mydomain as well.  </p>

<p> Example 1: default setting. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    mydestination = $myhostname localhost.$mydomain localhost
</pre>
</blockquote>

<p> Example 2: domain-wide mail server. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    mydestination = $myhostname localhost.$mydomain localhost $mydomain
</pre>
</blockquote>

<p> Example 3: host with multiple DNS A records. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    mydestination = $myhostname localhost.$mydomain localhost
        www.$mydomain ftp.$mydomain
</pre>
</blockquote>

<p> Caution: in order to avoid mail delivery loops, you must list all
hostnames of the machine, including $myhostname, and localhost.$mydomain. </p>

<h2> <a name="relay_from"> What clients to relay mail from </a> </h2>

<p> By default, Postfix will forward mail from clients in authorized
network blocks to any destination.  Authorized networks are defined
with the mynetworks configuration parameter. The current default is to
authorize the local machine only. Prior to Postfix 3.0, the default
was to authorize all clients in the IP subnetworks that the local
machine is attached to. </p>

<p> Postfix can also be configured to relay mail from "mobile"
clients that send mail from outside an authorized network block.
This is explained in the SASL_README and TLS_README documents. </p>

<p> IMPORTANT: If your machine is connected to a wide area network
then the "mynetworks_style = subnet" setting may be too friendly. </p>

<p> Examples (specify only one of the following): </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    mynetworks_style = subnet  (not safe on a wide area network)
    mynetworks_style = host    (authorize local machine only)
    mynetworks = 127.0.0.0/8   (authorize local machine only)
    mynetworks = 127.0.0.0/8 168.100.189.2/32 (authorize local machine)
    mynetworks = 127.0.0.0/8 168.100.189.2/28 (authorize local networks)
</pre>
</blockquote>

<p> You can specify the trusted networks in the main.cf file, or
you can let Postfix do the work for you. The default is to let
Postfix do the work. The result depends on the mynetworks_style
parameter value.

<ul>

<li> <p> Specify "mynetworks_style = host" (the default when
compatibility_level &ge; 2) when Postfix should forward mail from
only the local machine. </p>

<li> <p> Specify "mynetworks_style = subnet" (the default when
compatibility_level &lt; 2) when Postfix should forward mail from
SMTP clients in the same IP subnetworks as the local machine.
On Linux, this works correctly only with interfaces specified
with the "ifconfig" or "ip" command. </p>

<li> <p> Specify "mynetworks_style = class" when Postfix should
forward mail from SMTP clients in the same IP class A/B/C networks
as the local machine. Don't do this with a dialup site - it would
cause Postfix to "trust" your entire provider's network. Instead,
specify an explicit mynetworks list by hand, as described below.
</p>

</ul>

<p> Alternatively, you can specify the mynetworks list by hand,
in which case Postfix ignores the mynetworks_style setting.
To specify the list of trusted networks by hand, specify network
blocks in CIDR (network/mask) notation, for example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    mynetworks = 168.100.189.0/28, 127.0.0.0/8
</pre>
</blockquote>

<p> You can also specify the absolute pathname of a pattern file instead
of listing the patterns in the main.cf file. </p>

<h2> <a name="relay_to"> What destinations to relay mail to </a> </h2>

<p> By default, Postfix will forward mail from strangers (clients outside
authorized networks) to authorized remote destinations only.
Authorized remote
destinations are defined with the relay_domains configuration
parameter.  The default is to authorize all domains (and subdomains)
of the domains listed with the mydestination parameter.  </p>

<p> Examples (specify only one of the following): </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    relay_domains = $mydestination (default)
    relay_domains =           (safe: never forward mail from strangers)
    relay_domains = $mydomain (forward mail to my domain and subdomains)
</pre>
</blockquote>

<h2> <a name="relayhost"> What delivery method: direct or
indirect </a> </h2>

<p> By default, Postfix tries to deliver mail directly to the
Internet. Depending on your local conditions this may not be possible
or desirable.  For example, your system may be turned off outside
office hours, it may be behind a firewall, or it may be connected
via a provider who does not allow direct mail to the Internet.  In
those cases you need to configure Postfix to deliver mail indirectly
via a relay host. </p>

<p> Examples (specify only one of the following): </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    relayhost =                   (default: direct delivery to Internet)
    relayhost = $mydomain         (deliver via local mailhub)
    relayhost = [mail.$mydomain]  (deliver via local mailhub)
    relayhost = [mail.isp.tld]    (deliver via provider mailhub)
</pre>
</blockquote>

<p> The form enclosed with <tt>[]</tt> eliminates DNS MX lookups.
Don't worry if you don't know what that means. Just be sure to
specify the <tt>[]</tt> around the mailhub hostname that your ISP
gave to you, otherwise mail may be mis-delivered. </p>

<p> The STANDARD_CONFIGURATION_README file has more hints and tips
for firewalled and/or dial-up networks. </p>

<h2> <a name="notify"> What trouble to report to the postmaster</a> </h2>

<p> You should set up a postmaster alias in the aliases(5) table
that directs mail to a human person.  The postmaster address is
required to exist, so that people can report mail delivery problems.
While you're updating the aliases(5) table, be sure to direct mail
for the super-user to a human person too. </p>

<blockquote>
<pre>
/etc/aliases:
    postmaster: you
    root: you
</pre>
</blockquote>

<p> Execute the command "newaliases" after changing the aliases
file.  Instead of /etc/aliases, your alias file may be located
elsewhere.  Use the command "postconf alias_maps" to find out.</p>

<p> The Postfix system reports problems to the postmaster alias.
You may not be interested in all types of trouble reports, so this
reporting mechanism is configurable. The default is to report only
serious problems (resource, software) to postmaster:  </p>

<p> Default setting: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    notify_classes = resource, software
</pre>
</blockquote>

<p> The meaning of the classes is as follows: </p>

<blockquote>

<dl>

<dt> bounce </dt> <dd>  Inform the postmaster of undeliverable
mail.  Either send the postmaster a copy of undeliverable mail that
is returned to the sender, or send a transcript of the SMTP session
when Postfix rejected mail.  For privacy reasons, the postmaster
copy of undeliverable mail is truncated after the original message
headers.  This implies "2bounce" (see below).  See also the
luser_relay feature. The notification is sent to the address
specified with the bounce_notice_recipient configuration parameter
(default:  postmaster).  </dd>

<dt> 2bounce </dt> <dd> When Postfix is unable to return undeliverable
mail to the sender, send it to the postmaster instead (without
truncating the message after the primary headers). The notification
is sent to the address specified with the 2bounce_notice_recipient
configuration parameter (default:  postmaster).  </dd>

<dt> delay </dt> <dd> Inform the postmaster of delayed mail.  In
this case, the postmaster receives message headers only.  The
notification is sent to the address specified with the
delay_notice_recipient configuration parameter (default:  postmaster).
</dd>

<dt> policy </dt> <dd> Inform the postmaster of client requests
that were rejected because of (UCE) policy restrictions.  The
postmaster receives a transcript of the SMTP session. The notification
is sent to the address specified with the error_notice_recipient
configuration parameter (default:  postmaster).  </dd>

<dt> protocol </dt> <dd> Inform the postmaster of protocol errors
(client or server side) or attempts by a client to execute
unimplemented commands. The postmaster receives a transcript of
the SMTP session. The notification is sent to the address specified
with the error_notice_recipient configuration parameter (default:
postmaster). </dd>

<dt> resource </dt> <dd> Inform the postmaster of mail not delivered
due to resource problems (for example, queue file write errors).
The notification is sent to the address specified with the
error_notice_recipient configuration parameter (default:  postmaster).
</dd>

<dt> software </dt> <dd> Inform the postmaster of mail not delivered
due to software problems. The notification is sent to the address
specified with the error_notice_recipient configuration parameter
(default:  postmaster). </dd>

</dl>

</blockquote>

<h2><a name="proxy_interfaces"> Proxy/NAT external network
addresses</a> </h2>

<p> Some mail servers are connected to the Internet via a network
address translator (NAT) or proxy. This means that systems on the
Internet connect to the address of the NAT or proxy, instead of
connecting to the network address of the mail server. The NAT or
proxy forwards the connection to the network address of the mail
server, but Postfix does not know this.  </p>

<p> If you run a Postfix server behind a proxy or NAT, you need to
configure the proxy_interfaces parameter and specify all the external
proxy or NAT addresses that Postfix receives mail on. You may
specify symbolic hostnames instead of network addresses.  </p>

<p> IMPORTANT: You must specify your proxy/NAT external addresses
when your system is a backup MX host for other domains, otherwise
mail delivery loops will happen when the primary MX host is down.
</p>

<p> Example: host behind NAT box running a backup MX host. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address)
</pre>
</blockquote>

<h2> <a name="syslog_howto"> What you need to know about
Postfix logging </a> </h2>

<p> Postfix daemon processes run in the background, and log problems
and normal activity to the syslog daemon. The syslogd process sorts
events by class and severity, and appends them to logfiles. The
logging classes, levels and logfile names are usually specified in
/etc/syslog.conf. At the very least you need something like:  </p>

<blockquote>
<pre>
/etc/syslog.conf:
    mail.err                                    /dev/console
    mail.debug                                  /var/log/maillog
</pre>
</blockquote>

<p> After changing the syslog.conf file, send a "HUP" signal to
the syslogd process.  </p>

<p> IMPORTANT: many syslogd implementations will not create files.
You must create files before (re)starting syslogd. </p>

<p> IMPORTANT: on Linux you need to put a "-" character before the
pathname, e.g., -/var/log/maillog, otherwise the syslogd process
will use more system resources than Postfix. </p>

<p> Hopefully, the number of problems will be small, but it is a good
idea to run every night before the syslog files are rotated: </p>

<blockquote>
<pre>
# postfix check
# grep -E '(reject|warning|error|fatal|panic):' /some/log/file
</pre>
</blockquote>

<ul>

<li> <p> The first line (postfix check) causes Postfix to report
file permission/ownership discrepancies. </p>

<li> <p> The second line looks for problem reports from the mail
software, and reports how effective the relay and junk mail access
blocks are.  This may produce a lot of output.  You will want to
apply some postprocessing to eliminate uninteresting information.
</p>

</ul>

<p> The <a href="DEBUG_README.html#logging"> DEBUG_README </a>
document describes the meaning of the "warning" etc. labels in
Postfix logging. </p>

<h2> <a name="chroot_setup"> Running Postfix daemon processes
chrooted </a> </h2>

<p> Postfix daemon processes can be configured (via the master.cf
file) to run in a chroot jail.  The processes run at a fixed low
privilege and with file system access limited to the Postfix queue
directories (/var/spool/postfix).  This provides a significant
barrier against intrusion. The barrier is not impenetrable (chroot
limits file system access only), but every little bit helps.</p>

<p>With the exception of Postfix daemons that deliver mail locally
and/or that execute non-Postfix commands, every Postfix daemon can
run chrooted.</p>

<p>Sites with high security requirements should consider to chroot
all daemons that talk to the network: the smtp(8) and smtpd(8)
processes, and perhaps also the lmtp(8) client. The author's own
porcupine.org mail server runs all daemons chrooted that can be
chrooted.  </p>

<p>The default /etc/postfix/master.cf file specifies that no Postfix
daemon runs chrooted. In order to enable chroot operation, edit
the file /etc/postfix/master.cf, and follow instructions in the
file.  When you're finished, execute "postfix reload" to make the
change effective. </p>

<p>Note that a chrooted daemon resolves all filenames relative to
the Postfix queue directory (/var/spool/postfix). For successful
use of a chroot jail, most UNIX systems require you to bring in
some files or device nodes. The examples/chroot-setup directory in
the source code distribution has a collection of scripts that help
you set up Postfix chroot environments on different operating
systems.</p>

<p> Additionally, you almost certainly need to configure syslogd
so that it listens on a socket inside the Postfix queue directory.
Examples of syslogd command line options that achieve this for
specific systems: </p>

<p> FreeBSD: <tt>syslogd -l /var/spool/postfix/var/run/log</tt> </p>

<p> Linux, OpenBSD: <tt>syslogd -a /var/spool/postfix/dev/log</tt> </p>

<h2><a name="myhostname"> My own hostname </a> </h2>

<p> The myhostname parameter specifies the fully-qualified domain
name of the machine running the Postfix system.   $myhostname
appears as the default value in many other Postfix configuration
parameters. </p>

<p> By default, myhostname is set to the local machine name.  If
your local machine name is not in fully-qualified domain name form,
or if you run Postfix on a virtual interface, you will have to
specify the fully-qualified domain name that the mail system should
use. </p>

<p> Alternatively, if you specify mydomain in main.cf, then Postfix
will use its value to generate a fully-qualified default value
for the myhostname parameter. </p>

<p> Examples (specify only one of the following): </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    myhostname = host.local.domain (machine name is not FQDN)
    myhostname = host.virtual.domain (virtual interface)
    myhostname = virtual.domain (virtual interface)
</pre>
</blockquote>

<h2><a name="mydomain"> My own domain name</a> </h2>

<p> The mydomain parameter specifies the parent domain of
$myhostname.  By default, it is derived from  $myhostname
by stripping off the first part (unless the result would be a
top-level domain). </p>

<p> Conversely, if you specify mydomain in main.cf, then Postfix
will use its value to generate a fully-qualified default value
for the myhostname parameter. </p>

<p> Examples (specify only one of the following): </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    mydomain = local.domain
    mydomain = virtual.domain (virtual interface)
</pre>
</blockquote>

<h2><a name="inet_interfaces">My own network addresses</a> </h2>

<p>The inet_interfaces parameter specifies all network interface
addresses that the Postfix system should listen on; mail addressed
to "user@[network address]" will be delivered locally,
as if it is addressed to a domain listed in  $mydestination.</p>

<p> You can override the inet_interfaces setting in the Postfix
master.cf file by prepending an IP address to a server name. </p>

<p> The default is to listen on all active interfaces.  If you run
mailers on virtual interfaces, you will have to specify what
interfaces to listen on.  </p>

<p> IMPORTANT: If you run MTAs on virtual interfaces you must
specify explicit inet_interfaces values for the MTA that receives
mail for the machine itself:  this MTA should never listen on the
virtual interfaces or you would have a mailer loop when a virtual
MTA is down.  </p>

<p> Example: default setting. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    inet_interfaces = all
</pre>
</blockquote>

<p> Example: host running one or more virtual mailers. For
each Postfix instance, specify only one of the following. </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    inet_interfaces = virtual.host.tld         (virtual Postfix)
    inet_interfaces = $myhostname localhost... (non-virtual Postfix)
</pre>
</blockquote>

<p> Note: you need to stop and start Postfix after changing this
parameter.  </p>

</body>

</html>