An Ansible role to install and configure Postfix on Debian-based systems.
## **Description**
This role sets up Postfix to function as a local mail server designed for internal use. Its primary function is to accept mail from local services and relay all outbound messages through a configured **smarthost**.
This is the perfect setup for environments where internal applications (like cron, monitoring systems, or web applications) need to send email notifications without the complexity of managing a full, internet-facing mail server.
This role performs the following actions:
* Installs the Postfix package and necessary SASL modules on Debian/Ubuntu.
* Manages the main Postfix configuration file (/etc/postfix/main.cf) via a template.
* Manages the /etc/mailname file for defining the mail domain.
* Configures Postfix to route all outgoing mail through a specified smarthost.
* Securely configures SASL authentication for the smarthost if credentials are provided.
## **Requirements**
* **Target OS**: This role is designed exclusively for **Debian-based** distributions (e.g., Debian, Ubuntu).
* **Ansible**: Version 2.10 or newer.
## **Role Variables**
The role's behavior can be customized using the following variables. The default values are defined in defaults/main.yml.
| postfix_relayhost | "" (empty string) | **Required.** The smarthost for relaying all mail. Use square brackets [] to prevent MX lookups (e.g., \[smtp.sendgrid.net\]:587). |
| postfix_relayhost_user | (undefined) | The username for SASL authentication with the smarthost. If defined with a password, SASL auth will be enabled. |
| postfix_relayhost_password | (undefined) | The password or API key for the smarthost user. **It** is strongly recommended to store this in Ansible **Vault.** |
| postfix_mail_domain | `{{ ansible_domain \| default('internal.local') }}` | The primary mail domain for this server |
| postfix_myhostname | `mail.{{ postfix_mail_domain }}` | The fully qualified domain name (FQDN) of the mail server itself (e.g., mail.example.com). |
| postfix_mydestination | `$myhostname, localhost.{{ postfix_mail_domain }}, localhost, {{ postfix_mail_domain }}` | A comma-separated list of domains this server will accept mail for. The default is usually sufficient for an internal relay. |
| postfix_mynetworks | `"127.0.0.0/8 [::1]/128"` | The list of "trusted" remote SMTP clients that have more privileges than "strangers"|
| postfix_inet_interfaces | all | The network interfaces Postfix listens on. Set to loopback-only to only accept mail from the server itself. |
| postfix_inet_protocols | all | The IP protocols to use (ipv4, ipv6, or all). |
| dovecot_users | [] | List of local users to create. See below. |
### **Local Dovecot Users**
You can define local users for Dovecot (e.g., for service accounts). These users are managed in a separate password file and use a generated token for security.
```yaml
dovecot_users:
- name: "service1"
pass: "mysecretpassword"
```
The role will generate a random 16-character token on the server (stored in `/etc/dovecot/dovecot_token`). The actual password for the user will be `token + password`.
For example, if the token is `He5rN5SPH33AbFLn` and the password is `mysecretpassword`, the service must authenticate with `He5rN5SPH33AbFLnmysecretpassword`.
SASL authentication for the smarthost is **automatically enabled** if both postfix_relayhost_user and postfix_relayhost_password are defined. If they are not defined, Postfix will attempt to send mail without authentication.
This role has no dependencies on other Ansible roles or collections beyond the standard ansible.builtin modules.
## **Example Playbook**
Here is a basic example of how to use this role in your playbook. You must define postfix_relayhost. It is also highly recommended to use Ansible Vault to encrypt the smarthost password.
