Forge Home

postfix

Configures Postfix to send mail through a smart host

9,152 downloads

8,978 latest version

2.9 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.0.1 (latest)
  • 1.0.0
released May 2nd 2015
This version is compatible with:

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'dmcnicks-postfix', '1.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add dmcnicks-postfix
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install dmcnicks-postfix --version 1.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

dmcnicks/postfix — version 1.0.1 May 2nd 2015

The postfix module

Table of Contents

  1. Overview
  2. Module Description
  3. Setup
  4. Usage
  5. Limitations
  6. Development

Overview

Configures Postfix to send mail through a smart host.

Module Description

This Puppet module configures Postfix to use a smart host for outgoing email. If no alias domains are specified, Postfix will be configured to listen to the loopback interface and forward internal emails; the root alias is forwarded to an specified admin email email address, and additional aliases can be added using a defined type.

If alias domains are specified, Postfix will be configured to listen to all interfaces for incoming SMTP connections. In this configuration, additional virtual files can be specified to enable applications such as mailing list managers to receive emails.

Dependencies

Tested on

  • Debian 7 (wheezy)

Setup

What the postfix module affects

  • Installs SASL packages to enable SASL authentication with the smart host.
  • Installs the Postfix package and enables the Postfix service.
  • Overwrites the main.cf file.
  • Overwrites the aliases file.
  • Adds custom aliases to the aliases file via defined type.
  • Adds specified virtual files to the main.cf file.

Beginning with the postfix module

The basic usage of the Postfix module requires four parameters: a smart host, a username, an associated password and an admin email address to forward emails to:

class { 'postfix':
  smarthost   => 'smtp.isp.com',
  username    => 'username@isp.com',
  password    => 'NNNNNNNN',
  admin_email => 'admin@email.address'
}

In this configuration, Postfix will listen on the loopback interface only. It will configure the aliases file to forward root mail to the specified admin email address and configure Mandrill as a smart host, using the specified credentials.

This mode can be used on all nodes to ensure that cron emails and other error emails reach a systems administrator.

If an array of alias domains is specified, Postfix will listen on all interfaces and accept mail from the internet:

class { 'postfix':
  smarthost     => 'smtp.isp.com',
  username      => 'username@isp.com',
  password      => 'NNNNNNNN',
  admin_email   => 'admin@email.address',
  alias_domains => [ 'lists.my.domain', 'lists.other.domain' ]
}

More virtual alias files can be specified:

class { 'postfix':
  smarthost     => 'smtp.isp.com',
  username      => 'username@isp.com',
  password      => 'NNNNNNNN',
  admin_email   => 'admin@email.address',
  alias_domains => [ 'lists.my.domain', 'lists.other.domain' ],
  alias_files   => [ '/etc/mailman_aliases' ]
}

Using SSL

By default, Postfix will be configured to use the standard CA certificates file and a dummy self-signed certificate (the snakeoil certificate in Debian).

These can be overriden:

class { 'postfix':
  smarthost     => 'smtp.isp.com',
  username      => 'username@isp.com',
  password      => 'NNNNNNNN',
  admin_email   => 'admin@email.address',
  alias_domains => [ 'lists.my.domain', 'lists.other.domain' ],
  key_file      => '/path/to/my.key',
  cert_file     => '/path/to/my.crt',
  ca_file       => '/path/to/ca.crt'
}

Using defined types

Additional local aliases can be added using the postfix::alias defined type:

postfix::alias { 'jbloggs':
  to => 'jbloggs@gmail.com'
}

Aliases can be added to other files by specifying the file:

postfix::alias { 'jdoe':
  to => 'jdoe@outlook.com',
  in => '/etc/mailman_aliases'
}

The transport, virtual and virtual regexp files can also be configured using defined types:

postfix::transport { 'subdomain.domain.com':
  to => 'relay:[smtp.anotherisp.com]'
}

postfix::virtual { 'jbloggs@domain.com':
  to => 'domain.com-jbloggs'
}

postfix::regexp { '/^(postmaster|root|abuse)@domain.com/':
  to => 'root'
}

Usage

The postfix class

The module's primary class.

Parameters

username

(Required) The username to login to the smart host with.

password

(Required) The password to login to the smart host with.

smarthost

(Required) The hostname of the smart host.

admin_email

(Required) Email address that all system-generated emails will be forwarded to.

alias_domains

(Optional) An array of mail domains to accept incoming mail for.

key_file

(Optional) Private key to use for SSL / STARTTLS connections (defaults to /etc/ssl/private/ssl-cert-snakeoil.key).

cert_file

(Optional) Certificate to use for SSL / STARTTLS connections (defaults to /etc/ssl/certs/ssl-cert-snakeoil.crt).

ca_file

(Optional) File containing the CA certificate that signed the specified certificate (defaults to /etc/ssl/certs/ca-certificate.crt). (Optional)

The postfix::alias defined type

Defined type that adds aliases to the system alias file or alternative alias files that have been defined in the postfix class.

Parameters

#####title

(Namevar) The left-hand side of the alias. Alternatively, the alias file name can be specified in the title using the format alias in /path/to/aliasfile.

to

(Required) The right-hand side of the alias.

in

(Optional) The alias file that the alias should to be added to.

The postfix::transport defined type

Defined type that adds transport mappings to the transport table.

Parameters

#####title

(Namevar) The left-hand side of the transport mapping.

to

(Required) The right-hand side of the transport mapping.

The postfix::virtual defined type

Defined type that adds virtual alias mappings to the virtual alias table.

Parameters

#####title

(Namevar) The left-hand side of the virtual alias mapping.

to

(Required) The right-hand side of the virtual alias mapping.

The postfix::regexp defined type

Defined type that adds regular expression mappings to the regexp table.

Parameters

#####title

(Namevar) The left-hand side of the regular expression mapping.

to

(Required) The right-hand side of the regular expression mapping.

Limitations

There may be incompatibilities with other OS versions, packages and configurations.

Development

We are happy to receive pull requests.