diff options
Diffstat (limited to 'proto/BASIC_CONFIGURATION_README.html')
| -rw-r--r-- | proto/BASIC_CONFIGURATION_README.html | 682 |
1 files changed, 682 insertions, 0 deletions
diff --git a/proto/BASIC_CONFIGURATION_README.html b/proto/BASIC_CONFIGURATION_README.html new file mode 100644 index 0000000..f8d94b0 --- /dev/null +++ b/proto/BASIC_CONFIGURATION_README.html @@ -0,0 +1,682 @@ +<!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=us-ascii"> + +</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 = host" 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" when Postfix should +forward mail from only the local machine. </p> + +<li> <p> Specify "mynetworks_style = subnet" (the default) 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" 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 +# egrep '(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> |