debops.postfix documentation Release master DebOps Project February 18, 2015
Contents 1 Introduction 1 1.1 Features.................................................. 1 2 Installation 3 2.1 Role dependencies............................................ 3 3 Getting started 5 4 Default variables 7 4.1 General Postfix configuration...................................... 7 4.2 PKI / TLS configuration......................................... 9 4.3 Firewall configuration.......................................... 10 4.4 Postfix SMTP client options....................................... 11 4.5 Mail archive options........................................... 11 4.6 Anti-spam configuration......................................... 12 4.7 Postfix SMTPD restrictions....................................... 13 4.8 Mail aliases................................................ 14 4.9 Postfix custom configuration....................................... 15 4.10 Mail service debugging......................................... 17 5 Guides and examples 19 6 Troubleshooting 21 7 Copyright 23 8 Credits 25 8.1 Credits, in chronological order...................................... 25 9 Changelog 27 9.1 v0.1.0................................................... 27 i
ii
CHAPTER 1 Introduction debops.postfix is an Ansible role which installs and manages Postfix, an SMTP server. It is designed to manage Postfix on different hosts in a cluster, with different capabilities. 1.1 Features At the moment role can configure Postfix to act as: a null client: Postfix sends all mail to another system specified either via DNS MX records or an Ansible variable, no local mail is enabled (this is the default configuration); a local SMTP server: local mail is delivered to local user accounts; a network SMTP server: network access is enabled separately from other capabilities, to avoid exposing misconfigured SMTP server by mistake and becoming an open relay; an incoming MX gateway: Postfix will listen on the port 25 (default SMTP port) and process connections using postscreen daemon with automatic greylisting and optional RBL checking; an outgoing SMTP client: Postfix will relay outgoing mail messages to specified remote MX hosts, you can optionally enable SMTP client authentication, passwords will be stored separate from the inventory in secret/ directory (see debops.secret role). Sender dependent authentication is also available. More capabilities like user authentication, support for virtual mail, spam/virus filtering and others will be implemented in the future. This role can also be used as a dependency of other roles which then can enable more features of the Postfix SMTP server for their own use. For example, debops.mailman role enables mail forwarding to the configured mailing lists, and debops.smstools role uses Postfix as mail-sms gateway. 1
2 Chapter 1. Introduction
CHAPTER 2 Installation This role requires at least Ansible v1.7.0. To install it, run: ansible-galaxy install debops.postfix 2.1 Role dependencies debops.ferm debops.secret 3
4 Chapter 2. Installation
CHAPTER 3 Getting started An example playbook which uses debops.postfix role: --- - name: Manage Postfix instance hosts: all roles: - role: debops.postfix tags: postfix This playbook should install postfix package along with its dependencies, and configure the service with default values generated by Ansible. 5
6 Chapter 3. Getting started
CHAPTER 4 Default variables 4.1 General Postfix configuration Configuration options for Postfix. Many options are configured automatically using templates, here you can (mostly) add your own entries to Postfix lists (look in Postfix manual for details), they will by added or replaced in templates. 4.1.1 postfix capabilities List of active Postfix capabilities. By default Postfix is configured with local mail disabled, all mail is sent to local MX server configured in DNS. postfix: [ null ] List of available Postfix capabilities: null: Postfix has no local delivery, all mail is sent to a MX for current domain. Configuration similar to that presented here: http://www.postfix.org/standard_configuration_readme.html#null_client Default. You should remove this capability and replace it with others presented below. local: local delivery is enabled on current host. network: enables access to Postfix-related ports (25, 587, 465) in firewall, required for incoming mail to be acceped by Postfix. mx: enables support for incoming mail on port 25, designed for hosts set up as MX. Automatically enables postscreen (without dnsbl/dnswl support), anti-spam restrictions. submission: enables authorized mail submission on ports 25 and 587 (user authentication is currently not supported and needs to be configured separately). deprecated: designed to enable obsolete functions of mail system, currently enables authorized mail submission on port 465 (when submission is also present in the list of capabilities). client: enable SASL authentication for SMTP client (for outgoing mail messages sent via relayhosts that require user authentication). sender_dependent: enable sender dependent SMTP client authentication (client capability required) archive: BCC all mail (or mail from/to specified domains) passing through the SMTP server to an e-mail account on local or remote server. postscreen: allows to enable postscreen support on port 25 independently of mx capability. dnsbl: enables support for DNS blacklists in postscreen, automatically enables whitelists. 7
dnswl: enables support for DNS whitelists in postscreen, without blacklists. test: enables soft_bounce option and XCLIENT protocol extension for localhost (useful in mail system testing). defer: planned feature to defer mail delivery. auth: planned feature to enable user authentication. Not all combinations of these capabilities will work correctly together. 4.1.2 postfix_relayhost Address of mail host this host should relay all mail to instead of delivering it directly. (Automatic configuration) postfix_relayhost: False 4.1.3 postfix_mailname Mail host name configured in /etc/mailname postfix_mailname: {{ ansible_fqdn }} 4.1.4 postfix_mydomain Domain name to use for outgoing mail messages postfix_mydomain: {{ ansible_domain }} 4.1.5 postfix_delay_warning_time How long to wait before notifying users about delivery problems postfix_delay_warning_time: 4h 4.1.6 postfix_relay_domains List of relay domains this host accepts postfix_relay_domains: [] 4.1.7 postfix_inet_interfaces On what interfaces Postfix should listen to by default (not a list). (Automatic configuration) postfix_inet_interfaces: False 8 Chapter 4. Default variables
4.1.8 postfix_mydestination List of local domains accepted by Postfix. (Automatic configuration) postfix_mydestination: [] 4.1.9 postfix_mynetworks List of networks Postfix accepts by default. (localhost is always enabled) postfix_mynetworks: [] 4.1.10 postfix_transport_maps List of Postfix transport maps. (Automatic configuration) postfix_transport_maps: [] 4.1.11 postfix_virtual_alias_maps List of Postfix virtual alias maps. (Automatic configuration) postfix_virtual_alias_maps: [] 4.1.12 postfix_message_size_limit Message size limit in megabytes postfix_message_size_limit: 50 4.2 PKI / TLS configuration 4.2.1 postfix_pki Enable or disable support for TLS in Postfix (using debops.pki) postfix_pki: True 4.2.2 postfix_pki_path Base PKI directory postfix_pki_path: {% if (ansible_local is defined and ansible_local.pki is defined) %}{{ ansible_loc 4.2. PKI / TLS configuration 9
4.2.3 postfix_pki_realm Default PKI realm used by Postfix postfix_pki_realm: {% if (ansible_local is defined and ansible_local.pki is defined) %}{{ ansible_lo 4.2.4 postfix_pki_crt Default certificate, relative to postfix_pki_realm variable postfix_pki_crt: default.crt 4.2.5 postfix_pki_key Default private key, relative to postfix_pki_realm variable postfix_pki_key: default.key 4.2.6 postfix_pki_dhparam Default Diffie-Hellman parameters file (2048 bits), relative to postfix_pki_realm variable postfix_pki_dhparam: dhparam.pem 4.3 Firewall configuration If network and any of needed Postfix capabilities are enabled, all hosts can send mail to this Postfix instance. You can limit access to specific hosts or networks using postfix_allow_* variables. 4.3.1 postfix_allow_smtp List of hosts/networks that can access smtp port (25) postfix_allow_smtp: [] 4.3.2 postfix_allow_submission List of hosts/networks that can access submission port (587) postfix_allow_submission: [] 4.3.3 postfix_allow_smtps List of hosts/networks that can access smtps port (465), deprecated. postfix_allow_smtps: [] 10 Chapter 4. Default variables
4.4 Postfix SMTP client options 4.4.1 postfix_smtp_sasl_password_map Map of SMTP SASL passwords used in SMTP client authentication by Postfix. You need to add client in Postfix capabilities to enable this feature. postfix_smtp_sasl_password_map: {} Format of the password entries: key: remote SMTP server hostname or sender e-mail address value: username on the remote SMTP server Example entries: postfix_smtp_sasl_password_map: smtp.example.org : username user@example.org : username user@example.org : username@example.com Passwords are stored in a secret directory, in path: secret/credentials/{{ ansible_fqdn }}/postfix/smtp_sasl_password_map/{{ key }}/{{ value }} If you do not define the passwords there, this role will generate random passwords by default and store them there. You can use this to your advantage by running debops once without defining the password to let debops generate the right location automatically. Passwords on the remote host are stored in: /etc/postfix/private_hash_tables/ To regenerate, change or add new passwords, you need to remove the *.lock files located in above directory. 4.4.2 postfix_sender_dependent_relayhost_map Map of sender dependent relayhosts used in SMTP client mail relay by Postfix. sender_dependent in Postfix capabilities to enable this feature. You need to add client and postfix_sender_dependent_relayhost_map: {} Example entries: <sender-address> : <relay-host> user@example.org : [smtp.example.org]:submission 4.5 Mail archive options Archiving is enabled by archive option in Postfix capabilities. Remember that an archive account on the receiving server needs to exist. 4.4. Postfix SMTP client options 11
4.5.1 postfix_archive_method How Postfix should redistribute archived messages: - all: send all mail without sorting - domain: send mail sorted by domain - domain-account: send mail sorted by domain and account, divided by separator postfix_archive_method: all 4.5.2 postfix_archive_to Optional address of a mail account to send the archived mails to. If not specified, Ansible will generate an address by itself in format: - <postfix_archive_account>@<ansible_fqdn> (if local mail is enabled) - <postfix_archive_account>@<postfix_archive_subdomain>.<ansible_domain> (if local mail is disabled). postfix_archive_to: 4.5.3 postfix_archive_account Mail account to send archived mail to (used by Ansible to generate archive address). postfix_archive_account: mail-archive 4.5.4 postfix_archive_subdomain Subdomain part of a domain used to generate archive address, if local mail is not enabled in Postfix capabilities (dot at the end is required). postfix_archive_subdomain: archive. 4.5.5 postfix_archive_separator Character used to separate domain and account part in sorted archive mails. If you use virtual mail delivery, you can sort mail into subdirectories by setting separator as / (does not work on local mail delivery). postfix_archive_separator: = 4.5.6 postfix_archive_domains List of domains to archive. If it s empty, everything is archived. postfix_archive_domains: [] 4.6 Anti-spam configuration 4.6.1 postfix_postscreen_dnsbl_sites List of DNS Blacklists enabled in postscreen service. Disabled by default. To enable blacklists, you need to add dnsbl in Postfix capabilities. 12 Chapter 4. Default variables
postfix_postscreen_dnsbl_sites: # Spamhaus ZEN: http://www.spamhaus.org/zen/ # Might require registration - zen.spamhaus.org*3 # Barracuda Reputation Block List: http://barracudacentral.org/rbl # Requires registration #- b.barracudacentral.org*2 # Spam Eating Monkey: http://spameatingmonkey.com/lists.html # Might require registration - bl.spameatingmonkey.net*2 - backscatter.spameatingmonkey.net*2 # SpamCop Blocking List: http://www.spamcop.net/bl.shtml - bl.spamcop.net # Passive Spam Block List: http://psbl.org/ - psbl.surriel.com # mailspike: http://mailspike.net/usage.html # Might require contact - bl.mailspike.net 4.6.2 postfix_postscreen_dnswl_sites List of DNS Whitelists enabled in postscreen service. Disabled by default. To enable whitelists, you need to add dnswl in Postfix capabilities. postfix_postscreen_dnswl_sites: # SpamHaus Whitelist: http://www.spamhauswhitelist.com/en/usage.html # Might require registration - swl.spamhaus.org*-4 # DNS Whitelist: http://dnswl.org/tech # Might require registration - list.dnswl.org=127.[0..255].[0..255].0*-2 - list.dnswl.org=127.[0..255].[0..255].1*-3 - list.dnswl.org=127.[0..255].[0..255].[2..255]*-4 4.7 Postfix SMTPD restrictions debops.postfix creates a base set of various smtpd restrictions by itself, to protect the SMTP server against spam. However this functionality is currently basic. Using lists below you can define your own set of smtpd restrictions, which will override anything generated automatically by the role. 4.7.1 postfix_smtpd_client_restrictions Client restrictions, processed at the connection stage 4.7. Postfix SMTPD restrictions 13
postfix_smtpd_client_restrictions: [] 4.7.2 postfix_smtpd_helo_restrictions Hello restrictions, processed at HELO/EHLO stage postfix_smtpd_helo_restrictions: [] 4.7.3 postfix_smtpd_sender_restrictions Sender restrictions, processed at MAIL FROM stage postfix_smtpd_sender_restrictions: [] 4.7.4 postfix_smtpd_relay_restrictions Relay restrictions (currently not supported in the role) postfix_smtpd_relay_restrictions: [] 4.7.5 postfix_smtpd_recipient_restrictions Recipient restrictions, processed at RCPT TO stage postfix_smtpd_recipient_restrictions: [] 4.7.6 postfix_smtpd_data_restrictions Data restrictions, processed at DATA stage postfix_smtpd_data_restrictions: [] 4.8 Mail aliases Postfix role automatically manages /etc/aliases file with a set of default aliases redirected to root and staff accounts. 4.8.1 postfix_default_local_alias_recipients List of default recipients for local aliases which have no recipients specified, by default current $USER managing Ansible postfix_default_local_alias_recipients: [ {{ lookup("env","user") }} ] 14 Chapter 4. Default variables
4.8.2 postfix_local_aliases Hash of local aliases which will be merged with default aliases in vars/main.yml postfix_local_aliases: {} # Examples: # alias : [ account1, account2 ] # other : [ user@email, " /dir/command" ] # blackhole : [ /dev/null ] # send_to_default_recipients : [] 4.9 Postfix custom configuration 4.9.1 postfix_local_maincf Custom Postfix configuration added at the end of /etc/postfix/main.cf in a text block format postfix_local_maincf: False 4.9.2 postfix_local_mastercf Custom Postfix configuration added at the end of /etc/postfix/master.cf in a text block format postfix_local_mastercf: False 4.9.3 postfix_dependent_lists This variable can be used in Postfix dependency role definition to configure additional lists used in Postfix main.cf configuration file. This variable will be saved in Ansible facts and updated when necessary. postfix_dependent_lists: {} Examples Append custom tables to transport_maps option: transport_maps: [ hash:/etc/postfix/transport ] Append a given list of alias maps if Postfix has local capability: alias_maps: - capability: local list: [ hash:/etc/aliases ] Append this virtual alias map if Postfix does not have local capability: virtual_alias_maps: - no_capability: local list: [ hash:/etc/postfix/virtual_alias_maps ] 4.9. Postfix custom configuration 15
4.9.4 postfix_dependent_maincf Here you can specify Postfix configuration options which should be enabled in /etc/postfix/main.cf using debops.postfix dependency role definition. Configuration will be saved in Ansible facts and updated when necessary. postfix_dependent_maincf: [] Examples Add this option in main.cf: postfix_dependent_maincf: - param: local_destination_recipient_limit value: 1 Enable this option only if mx is in Postfix capabilities: postfix_dependent_maincf: - param: defer_transports value: smtp capability: mx Enable this option only if local is not in Postfix capabilities: postfix_dependent_maincf: - param: relayhost value: mx.example.org no_capability: local If no value is specified, check if a list of the same name as param exists in postfix_dependent_lists and enable it: postfix_dependent_maincf: - param: virtual_alias_maps 4.9.5 postfix_dependent_mastercf This list can be used to configure services in Postfix master.cf using Postfix dependency variables. Configured services will be saved in Ansible facts and updated when necessary. postfix_dependent_mastercf: [] Parameters Optional parameters from master.cf: - private - unpriv - chroot - wakeup - maxproc You can also specify capability or no_capability to define when a particular service should be configured Examples Minimal service using pipe command: 16 Chapter 4. Default variables
postfix_dependent_mastercf: - service: mydaemon type: unix command: pipe options: flagsd=fr user=mydaemon:mydaemon argv=/usr/local/bin/mydaemon.sh ${nexthop} ${user} 4.10 Mail service debugging 4.10.1 postfix_smtpd_authorized_xclient_hosts List of clients and networks which will have access to XCLIENT protocol extension when test Postfix capability is enabled. postfix_smtpd_authorized_xclient_hosts: [ 127.0.0.1/32 ] 4.10. Mail service debugging 17
18 Chapter 4. Default variables
CHAPTER 5 Guides and examples debops.postfix is designed to manage a Postfix service by itself. Other Ansible roles can use it as a dependency and influence the Postfix configuration using dependency variables, but to avoid possible issues they should not modify Postfix configuration directly. Any changes to Postfix configuration files not done by debops.postfix will be overwritten. 19
20 Chapter 5. Guides and examples
CHAPTER 6 Troubleshooting This section will contain information about fixing issues with debops.postfix role. 21
22 Chapter 6. Troubleshooting
CHAPTER 7 Copyright Copyright (C) 2014 Maciej Delmanowski <drybjed@gmail.com> Copyright (C) 2014 DebOps Project http://debops.org/ [see Credits for more details] his program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 3, as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/ 23
24 Chapter 7. Copyright
CHAPTER 8 Credits 8.1 Credits, in chronological order Maciej Delmanowski <drybjed_at_gmail.com> creator of the DebOps Project current project maintainer 25
26 Chapter 8. Credits
CHAPTER 9 Changelog 9.1 v0.1.0 First release [drybjed] 27