Readme Syntax
Introduction
- Format your Readme with markup Bitbucket can parse and display Markdown, reStructuredText, Textile, and plain text README files. With a syntax like Markdown, you can emphasize text, include screen captures, and more. For a tutorial on Bitbucket's Markdown support and syntax examples, see our Markdown demo repository.
- Dillinger is an online cloud based HTML5 filled Markdown Editor. Sync with Dropbox, Github, Google Drive or OneDrive. Convert HTML to Markdown. 100% Open Source!
Postfix has several hundred configuration parameters that arecontrolled via the main.cf file. Fortunately, all parameters havesensible default values. In many cases, you need to configure onlytwo or three parameters before you can start to play with the mailsystem. Here's a quick introduction to the syntax:
A relative link is a link that is relative to the current file. For example, if you have a README file in root of your repository, and you have another file in docs/CONTRIBUTING.md, the relative link to CONTRIBUTING.md in your README might look like this: Contribution guidelines for this project (docs/CONTRIBUTING.md). Markdown and Visual Studio Code. Working with Markdown files in Visual Studio Code is simple, straightforward, and fun. Besides VS Code's basic editing, there are a number of Markdown specific features that will help you be more productive. Markdown Cheatsheet for Github Readme.md. Contribute to tchapi/markdown-cheatsheet development by creating an account on GitHub.
The text below assumes that you already have Postfix installedon the system, either by compiling the source code yourself (asdescribed in the INSTALL file) or by installing an already compiledversion.
This document covers basic Postfix configuration. Informationabout how to configure Postfix for specific applications such asmailhub, firewall or dial-up client can be found in theSTANDARD_CONFIGURATION_README file. But don't go there until youalready have covered the material presented below.
The first parameters of interest specify the machine's identityand role in the network.
The default values for many other configuration parameters arederived from just these.
The next parameter of interest controls the amount of mail sentto the local postmaster:
Be sure to set the following correctly if you're behind a proxy ornetwork address translator, and you are running a backup MX hostfor some other domain:
Postfix daemon processes run in the background, and log problemsand normal activity to the syslog daemon. Here are a few thingsthat you need to be aware of:
If your machine has unusual security requirements you maywant to run Postfix daemon processes inside a chroot environment.
If you run Postfix on a virtual network interface, or if yourmachine runs other mailers on virtual interfaces, you'll have tolook at the other parameters listed here as well:
Postfix configuration files
By default, Postfix configuration files are in /etc/postfix.The two most important files are main.cf and master.cf; these filesmust be owned by root. Giving someone else write permission tomain.cf or master.cf (or to their parent directories) means givingroot privileges to that person.
In /etc/postfix/main.cf you will have to set up a minimal numberof configuration parameters. Postfix configuration parametersresemble shell variables, with two important differences: the firstone is that Postfix does not know about quotes like the UNIX shelldoes.
You specify a configuration parameter as:
and you use it by putting a '$' character in front of its name:
You can use $parameter before it is given a value (that is thesecond main difference with UNIX shell variables). The Postfixconfiguration language uses lazy evaluation, and does not look ata parameter value until it is needed at runtime.
Postfix uses database files for access control, address rewritingand other purposes. The DATABASE_README file gives an introductionto how Postfix works with Berkeley DB, LDAP or SQL and other types.Here is a common example of how Postfix invokes a database:
Whenever you make a change to the main.cf or master.cf file,execute the following command as root in order to refresh a runningmail system:
What domain name to use in outbound mail
The myorigin parameter specifies the domain that appears inmail that is posted on this machine. The default is to use thelocal machine name, $myhostname, which defaults to the name of themachine. Unless you are running a really small site, you probablywant to change that into $mydomain, which defaults to the parentdomain of the machine name.
For the sake of consistency between sender and recipient addresses,myorigin also specifies the domain name that is appendedto an unqualified recipient address.
Examples (specify only one of the following):
What domains to receive mail for
The mydestination parameter specifies what domains thismachine will deliver locally, instead of forwarding to anothermachine. The default is to receive mail for the machine itself. See the VIRTUAL_README file for how to configure Postfix forhosted domains.
Readme Syntax
You can specify zero or more domain names, '/file/name' patternsand/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 atable lookup is done and merely tests for existence: the lookupresult is ignored.
IMPORTANT: If your machine is a mail server for its entiredomain, you must list $mydomain as well.
Example 1: default setting.
Example 2: domain-wide mail server.
Example 3: host with multiple DNS A records.
Caution: in order to avoid mail delivery loops, you must list allhostnames of the machine, including $myhostname, and localhost.$mydomain.
What clients to relay mail from
By default, Postfix will forward mail from clients in authorizednetwork blocks to any destination. Authorized networks are definedwith the mynetworks configuration parameter. The current default is toauthorize the local machine only. Prior to Postfix 3.0, the defaultwas to authorize all clients in the IP subnetworks that the localmachine is attached to.
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.
IMPORTANT: If your machine is connected to a wide area networkthen the 'mynetworks_style = host' setting may be too friendly.
Examples (specify only one of the following):
You can specify the trusted networks in the main.cf file, oryou can let Postfix do the work for you. The default is to letPostfix do the work. The result depends on the mynetworks_styleparameter value.
Specify 'mynetworks_style = host' when Postfix shouldforward mail from only the local machine.
Specify 'mynetworks_style = subnet' (the default) whenPostfix should forward mail from SMTP clients in the same IPsubnetworks as the local machine. On Linux, this works correctlyonly with interfaces specified with the 'ifconfig' command.
Specify 'mynetworks_style = class' when Postfix shouldforward mail from SMTP clients in the same IP class A/B/C networksas the local machine. Don't do this with a dialup site - it wouldcause Postfix to 'trust' your entire provider's network. Instead,specify an explicit mynetworks list by hand, as described below.
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 networkblocks in CIDR (network/mask) notation, for example:
Markdown Syntax
You can also specify the absolute pathname of a pattern file insteadof listing the patterns in the main.cf file.
What destinations to relay mail to
By default, Postfix will forward mail from strangers (clients outsideauthorized networks) to authorized remote destinations only.Authorized remotedestinations are defined with the relay_domains configurationparameter. The default is to authorize all domains (and subdomains)of the domains listed with the mydestination parameter.
Examples (specify only one of the following):
What delivery method: direct orindirect
By default, Postfix tries to deliver mail directly to theInternet. Depending on your local conditions this may not be possibleor desirable. For example, your system may be turned off outsideoffice hours, it may be behind a firewall, or it may be connectedvia a provider who does not allow direct mail to the Internet. Inthose cases you need to configure Postfix to deliver mail indirectlyvia a relay host.
Examples (specify only one of the following):
The form enclosed with [] eliminates DNS MX lookups.Don't worry if you don't know what that means. Just be sure tospecify the [] around the mailhub hostname that your ISPgave to you, otherwise mail may be mis-delivered.
The STANDARD_CONFIGURATION_README file has more hints and tipsfor firewalled and/or dial-up networks.
What trouble to report to the postmaster
You should set up a postmaster alias in the aliases(5) tablethat directs mail to a human person. The postmaster address isrequired to exist, so that people can report mail delivery problems.While you're updating the aliases(5) table, be sure to direct mailfor the super-user to a human person too.
Execute the command 'newaliases' after changing the aliasesfile. Instead of /etc/aliases, your alias file may be locatedelsewhere. Use the command 'postconf alias_maps' to find out.
The Postfix system reports problems to the postmaster alias.You may not be interested in all types of trouble reports, so thisreporting mechanism is configurable. The default is to report onlyserious problems (resource, software) to postmaster:
Default setting:
The meaning of the classes is as follows:
- bounce
- Inform the postmaster of undeliverablemail. Either send the postmaster a copy of undeliverable mail thatis returned to the sender, or send a transcript of the SMTP sessionwhen Postfix rejected mail. For privacy reasons, the postmastercopy of undeliverable mail is truncated after the original messageheaders. This implies '2bounce' (see below). See also theluser_relay feature. The notification is sent to the addressspecified with the bounce_notice_recipient configuration parameter(default: postmaster).
- 2bounce
- When Postfix is unable to return undeliverablemail to the sender, send it to the postmaster instead (withouttruncating the message after the primary headers). The notificationis sent to the address specified with the 2bounce_notice_recipientconfiguration parameter (default: postmaster).
- delay
- Inform the postmaster of delayed mail. Inthis case, the postmaster receives message headers only. Thenotification is sent to the address specified with thedelay_notice_recipient configuration parameter (default: postmaster).
- policy
- Inform the postmaster of client requeststhat were rejected because of (UCE) policy restrictions. Thepostmaster receives a transcript of the SMTP session. The notificationis sent to the address specified with the error_notice_recipientconfiguration parameter (default: postmaster).
- protocol
- Inform the postmaster of protocol errors(client or server side) or attempts by a client to executeunimplemented commands. The postmaster receives a transcript ofthe SMTP session. The notification is sent to the address specifiedwith the error_notice_recipient configuration parameter (default:postmaster).
- resource
- Inform the postmaster of mail not delivereddue to resource problems (for example, queue file write errors).The notification is sent to the address specified with theerror_notice_recipient configuration parameter (default: postmaster).
- software
- Inform the postmaster of mail not delivereddue to software problems. The notification is sent to the addressspecified with the error_notice_recipient configuration parameter(default: postmaster).
Proxy/NAT external networkaddresses
Some mail servers are connected to the Internet via a networkaddress translator (NAT) or proxy. This means that systems on theInternet connect to the address of the NAT or proxy, instead ofconnecting to the network address of the mail server. The NAT orproxy forwards the connection to the network address of the mailserver, but Postfix does not know this.
If you run a Postfix server behind a proxy or NAT, you need toconfigure the proxy_interfaces parameter and specify all the externalproxy or NAT addresses that Postfix receives mail on. You mayspecify symbolic hostnames instead of network addresses.
IMPORTANT: You must specify your proxy/NAT external addresseswhen your system is a backup MX host for other domains, otherwisemail delivery loops will happen when the primary MX host is down.
Example: host behind NAT box running a backup MX host.
What you need to know aboutPostfix logging
Postfix daemon processes run in the background, and log problemsand normal activity to the syslog daemon. The syslogd process sortsevents by class and severity, and appends them to logfiles. Thelogging classes, levels and logfile names are usually specified in/etc/syslog.conf. At the very least you need something like:
After changing the syslog.conf file, send a 'HUP' signal tothe syslogd process.
IMPORTANT: many syslogd implementations will not create files.You must create files before (re)starting syslogd.
IMPORTANT: on Linux you need to put a '-' character before thepathname, e.g., -/var/log/maillog, otherwise the syslogd processwill use more system resources than Postfix.
Hopefully, the number of problems will be small, but it is a goodidea to run every night before the syslog files are rotated:
The first line (postfix check) causes Postfix to reportfile permission/ownership discrepancies.
The second line looks for problem reports from the mailsoftware, and reports how effective the relay and junk mail accessblocks are. This may produce a lot of output. You will want toapply some postprocessing to eliminate uninteresting information.
The DEBUG_README document describes the meaning of the 'warning' etc. labels inPostfix logging.
Running Postfix daemon processeschrooted
Postfix daemon processes can be configured (via the master.cffile) to run in a chroot jail. The processes run at a fixed lowprivilege and with file system access limited to the Postfix queuedirectories (/var/spool/postfix). This provides a significantbarrier against intrusion. The barrier is not impenetrable (chrootlimits file system access only), but every little bit helps.
With the exception of Postfix daemons that deliver mail locallyand/or that execute non-Postfix commands, every Postfix daemon canrun chrooted.
Sites with high security requirements should consider to chrootall daemons that talk to the network: the smtp(8) and smtpd(8)processes, and perhaps also the lmtp(8) client. The author's ownporcupine.org mail server runs all daemons chrooted that can bechrooted.
The default /etc/postfix/master.cf file specifies that no Postfixdaemon runs chrooted. In order to enable chroot operation, editthe file /etc/postfix/master.cf, and follow instructions in thefile. When you're finished, execute 'postfix reload' to make thechange effective.
Note that a chrooted daemon resolves all filenames relative tothe Postfix queue directory (/var/spool/postfix). For successfuluse of a chroot jail, most UNIX systems require you to bring insome files or device nodes. The examples/chroot-setup directory inthe source code distribution has a collection of scripts that helpyou set up Postfix chroot environments on different operatingsystems.
Additionally, you almost certainly need to configure syslogdso that it listens on a socket inside the Postfix queue directory.Examples of syslogd command line options that achieve this forspecific systems:
FreeBSD: syslogd -l /var/spool/postfix/var/run/log
Linux, OpenBSD: syslogd -a /var/spool/postfix/dev/log
My own hostname
The myhostname parameter specifies the fully-qualified domainname of the machine running the Postfix system. $myhostnameappears as the default value in many other Postfix configurationparameters.
By default, myhostname is set to the local machine name. Ifyour local machine name is not in fully-qualified domain name form,or if you run Postfix on a virtual interface, you will have tospecify the fully-qualified domain name that the mail system shoulduse.
Alternatively, if you specify mydomain in main.cf, then Postfixwill use its value to generate a fully-qualified default value for the myhostname parameter.
Examples (specify only one of the following):
My own domain name
The mydomain parameter specifies the parent domain of$myhostname. By default, it is derived from $myhostnameby stripping off the first part (unless the result would be atop-level domain).
Conversely, if you specify mydomain in main.cf, then Postfixwill use its value to generate a fully-qualified default valuefor the myhostname parameter.
Examples (specify only one of the following):
My own network addresses
The inet_interfaces parameter specifies all network interfaceaddresses that the Postfix system should listen on; mail addressedto 'user@[network address]' will be delivered locally,as if it is addressed to a domain listed in $mydestination.
You can override the inet_interfaces setting in the Postfixmaster.cf file by prepending an IP address to a server name.
The default is to listen on all active interfaces. If you runmailers on virtual interfaces, you will have to specify whatinterfaces to listen on.
IMPORTANT: If you run MTAs on virtual interfaces you mustspecify explicit inet_interfaces values for the MTA that receivesmail for the machine itself: this MTA should never listen on thevirtual interfaces or you would have a mailer loop when a virtualMTA is down.
Example: default setting.
Example: host running one or more virtual mailers. Foreach Postfix instance, specify only one of the following.
Note: you need to stop and start Postfix after changing thisparameter.