DebOps Project
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
Introduction
debops.postfixis anAnsiblerole which installs and managesPostfix, 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 mis-configured 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 postscreendaemon 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 imple-mented 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.
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
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.
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 sub-mission on port 465 (when subsub-mission 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.
• 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
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
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_local.pki.realm }}{% else %}system{% endif %}’
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: []
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’ ’[email protected]’: ’username’
’[email protected]’: ’[email protected]’
Passwords are stored in asecretdirectory, 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. You need to add client and sender_dependentin Postfix capabilities to enable this feature.
postfix_sender_dependent_relayhost_map: {}
Example entries:
’<sender-address>’: ’<relay-host>’
’[email protected]’: ’[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.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 en-abled) - <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 dnsblin Postfix capabilities.
- ’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 dnswlin 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.postfixcreates 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
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") }}’]
# 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’
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:
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.
Guides and examples
debops.postfixis 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.
Troubleshooting
Copyright
Copyright (C) 2014 Maciej Delmanowski <[email protected]> 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/
Credits
8.1 Credits, in chronological order
• Maciej Delmanowski <drybjed_at_gmail.com> – creator of the DebOps Project
