puppet-postfix

Table of Contents

1. Description
2. Usage
   • Types
3. Reference
4. Limitations
5. Development
   • Contributing

Description

An extremely flexible Puppet module to manage Postfix installation. Manage main.cf settings and master.cf entries by postconf backed native types. Both types include support for multiple Postfix instances. The Postfix instances can be managed with a native type too.

Usage

The easiest way to use this module is to specify all desired configuration in Hiera. Here is a close-to-real-life example:

postfix::main_config:
  alias_database: hash:/etc/aliases
  alias_maps: hash:/etc/aliases
  append_dot_mydomain: no
  biff: no
  inet_protocols: all
  inet_interfaces: all
  mydestination: '$myhostname, localdomain, localhost'
  myorigin: '$mydomain'
  mynetworks:
    - '10.40.0.0/24'
    - '127.0.0.0/8'
    - '[::ffff:127.0.0.0]/104'
    - '[::1]/128'
  readme_directory: no
  recipient_delimiter: +
  smtpd_banner: '$myhostname ESMTP $mail_name'
  smtpd_relay_restrictions:
    - permit_mynetworks
    - permit_sasl_authenticated
    - defer_unauth_destination
  smtpd_use_tls: yes
  smtpd_tls_cert_file: &postfix_cert /etc/postfix/ssl/postfix.crt
  smtpd_tls_key_file: &postfix_key /etc/postfix/ssl/postfix.key
  smtpd_sasl_auth_enable: no # only enable for mandatory tls ports
  smtpd_sasl_type: dovecot
  smtpd_sasl_path: private/auth
  # sasl only encrypted
  smtpd_tls_auth_only: yes
  smtpd_tls_security_level: may
  virtual_transport: 'lmtp:unix:private/dovecot-lmtp'
  milter_protocol: 6
  common_milters: >-
    { inet:localhost:11332,
    connect_timeout=10s,
    default_action=accept }
  smtpd_milters: '$common_milters'
  non_smtpd_milters: '$common_milters'
  milter_mail_macros: i {mail_addr} {client_addr} {client_name} {auth_authen}

postfix::master_services:
  # merged with the defaults defined in data/modules/postfix.yaml
  smtps/inet: { ensure: present }
  submission/inet: { ensure: present }

This will create postconf and postconf_master resources for each setting. The resource types can also be used directly as described below.

Generating default master.cf entries

In order to generate the default postconf_master hiera entries needed to run postfix, you can use the provided master2hierayaml.rb script:

scripts/master2hierayaml.rb /usr/share/doc/postfix/defaults/master.cf > data/modules/postfix.yaml

It will try to parse active as well as commented entries and lines, and output warnings to stderr if it fails to do so. However, check the output carefully, otherwise you might end up with a non-working mail system.

Purging unmanaged entries

By default, this module will warn about unmanaged config entries in any managed main.cf and master.cf, but not remove them. To enable purging of those resources, set purge_main and purge_master to true:

postfix::purge_main: true
postfix::purge_master: true

Types

The postconf type enables you to set or rest postconf parameters.

  postconf { 'myhostname':
    value => 'foo.bar',
  }

The postmulti type allows you to create, de/activate and destroy postfix postmulti instances with pupppet.

By default ensure is set to active but can be set to inactive or absent respectively to deactivate or remove an postmulti instance.

When using postmulti the resource name must begin with postfix-:

  postmulti { 'postfix-foo': }

Using the :: syntax in resource titles allows you to manage different postfix instances. In the following example the foo::myhostname postconf resource would internally set the Postfix configuration directory to /etc/postfix-foo and configure the parameter in this instance.

  postconf { 'foo::myhostname':
    parameter => 'myhostname',
    value     => 'foo.bar',
  }

The postconf_master type enables you to manage the master.cf entries.

  postconf_master { 'mytransport/unix':
    command => 'smtp',
  }

The service and type params allow you to define the postconf_master service/type independently from the resource name. Using the :: syntax in resource titles again allows you to manage different postfix instances.

  postconf_master { 'mytransport/unix':
    command => 'smtp',
  }

  postconf_master { 'foo::mytransport/unix':
    service    => 'mytransport',
    type       => 'unix',
    command    => 'smtp',
  }

Reference

Classes and parameters are documented in REFERENCE.md.

Limitations

The postfix version of RHEL7 does not support postconf_master. An alternative version is available from the IUS Community Project.

Development

Contributing

Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.

Reference

Table of Contents

Classes

Public Classes

• postfix: This class installs and configures the postfix service.

Private Classes

• postfix::config: This class handles postfix configuration.
• postfix::package: Manages the postfix packages.
• postfix::service: Manages the postfix service.

Resource types

• postconf: Create a new postconf entry. Puppet does not really support generating/prefetching resources with multiple namevars, so this type represents
• postconf_master: Create a new postconf master.cf entry. Puppet does not really support generating/prefetching resources with multiple namevars, so this type
• postmulti: Manage postfix instances. Example: postmulti { 'postfix-out': }

Classes

postfix

This class installs and configures the postfix service.

Examples

Basic usage

class { 'postfix':
  service_manage => false,
  mailx_ensure   => absent
}

Parameters

The following parameters are available in the postfix class.

mailx_ensure

Data type: Enum['installed', 'present', 'latest']

The state of the mailx package to ensure.

mailx_manage

Data type: Boolean

Should the mailx package me managed.

mailx_package

Data type: String

The name of the mailx package.

main_config

Data type: Hash[String, Any]

A hash of config key-value entries for main.cf

master_services

Data type: Hash[String, Hash[String, Any]]

A hash of config key-value entries for master.cf

package_ensure

Data type: Enum['installed', 'present', 'latest']

The state the postfix package should be ensured.

package_manage

Data type: Boolean

Whether to install the postfix and plugin packages.

package_name

Data type: String

The name of the postfix package to install.

plugin

Data type: Hash

Contains a package_name parameter for each plugin (if available).

plugins

Data type: Array[String[1]]

The list of plugins to install.

purge_main

Data type: Variant[Boolean, Enum['true', 'false', 'noop']]

Purge all unmanaged entries from main.cf if true.

purge_master

Data type: Variant[Boolean, Enum['true', 'false', 'noop']]

Purge all unmanaged entries from master.cf if true.

restart_cmd

Data type: String

The command that should be used to restart the Postfix service upon configuration changes.

service_ensure

Data type: Enum['absent', 'running', 'stopped']

The state of the postfix service which should be ensured.

service_name

Data type: String

The name of the postfix service.

service_manage

Data type: Boolean

Should the postfix service be managed at all.

Resource types

postconf

Create a new postconf entry.

Puppet does not really support generating/prefetching resources with multiple namevars, so this type represents the whole parameter identifier in the :parameter property. This includes the postmulti instance. Valid formats are:

• service/type

• instance::service/type

  Autorequires: If Puppet is managing the postmulti instance for this entry, it will be autorequired.

Example:

 postconf { 'myhostname':
   value => 'foo.bar'
 }

Properties

The following properties are available in the postconf type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

value

The value the postconf parameter should be set to.

Parameters

The following parameters are available in the postconf type.

parameter

Valid values: %r{^([^/]+::)?[a-zA-Z0-9]+(?:_[a-zA-Z0-9]+)*$}

The postconf parameter which should be set.

provider

The specific backend to use for this postconf resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

postconf_master

Create a new postconf master.cf entry.

Puppet does not really support generating/prefetching resources with multiple namevars, so this type represents the whole service identifier in the :name property. This includes the postmulti instance. Valid formats are:

• service/type
• instance::service/type

Autorequires: If Puppet is managing the postmulti instance for this entry, it will be autorequired.

Example:

 postconf_master { 'smtp/inet':
   command => 'postscreen'
 }

Properties

The following properties are available in the postconf_master type.

chroot

Whether or not the service runs chrooted to the mail queue directory.

Default value: undef

command

The command to be executed.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

private

Whether or not access is restricted to the mail system.

Default value: undef

process_limit

Valid values: undef, %r{^\d+$}

The maximum number of processes that may execute this service simultaneously.

Default value: undef

unprivileged

Whether the service runs with root privileges or as the owner of the Postfix system.

Default value: undef

wakeup

Valid values: undef, %r{^\d+\??$}

Automatically wake up the named service after the specified number of seconds.

Default value: undef

Parameters

The following parameters are available in the postconf_master type.

name

namevar

The postconf master.cf service/type which should be managed.

provider

The specific backend to use for this postconf_master resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

postmulti

Manage postfix instances.

Example:

postmulti { 'postfix-out': }

Properties

The following properties are available in the postmulti type.

ensure

Valid values: active, inactive, absent, present

Aliases: "present"=>"active"

The basic property that the resource should be in.

group

Name of the instance group.

Parameters

The following parameters are available in the postmulti type.

name

namevar

Name of the postmulti instance. Must must start with 'postfix-'

provider

The specific backend to use for this postmulti resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

2.1.0 - 2023-08-21

Changed

• Allow $package_ensure to specify specific versions (#16)

2.0.0 - 2023-08-09

This module has a new home, so it's time to make a new major release.

Added

• Add GitHub Actions

Changed

• Update OS support, module dependency and Puppet version
• Remove the confine on EOL postfix version for postconf_master provider (#9)
• Convert documentation to Puppet Strings
• Convert module to PDK

Fixed

• Fix undefined method `scan' for nil:NilClass (#13)
• Gracefully handle warnings from postconf output
• Fix for specifying custom instance directory
• Fix for multi instance support with the postmulti resource
• Fix documentation regarding multi instance support and the config_dir parameter
• Fix unit/acceptance tests

1.0.2 - 2018-10-28

This release fixes postfix reloading on config changes.

Fixed

• Notify service on config changes, causing it to reload postfix to pick up the changes (#7)

1.0.1 - 2018-09-27

This release fixes support for systems where postfix is not installed, and bumps stdlib version compatibility.

Added

• Support for puppetlabs/stdlib 5
• Support for Ubuntu 18.04

Fixed

• Make postfix fact not cause trouble on systems where postfix is not installed (#6)

1.0.0 - 2018-03-03

First stable release

Added

• Add new parameter $plugins to specify a list of postfix plugins that should be installed (#2)
• Add new parameter $plugin to configure plugin package names (#2)
• Add new parameter $package_manage to control wether packages should be installed or not (#2)
• Add new parameters $main_config and $master_services to easily specify configuration via Hiera (#4)
• Add CLI script to convert an existing master.cf to hiera YAML (#4)
• Add new parameters $purge_main and $purge_master to remove unmanaged entries (default: warn about unmanaged entries) (#5)

Changed

• Boolean properties in postconf_master now accept more values
• Add stdlib dependency for unique() function on Puppet 4.x (#2)

Fixed

• Handle unused main.cf parameters that are unknown by postfix and not referenced in any other parameter (#3).
• Fix service logic: move exec restart after package install to class postfix::package (#2)
• Fix rspec unit tests
• Fix lots of rubocop-reported logic and style issues

0.2.1 - 2018-02-05

Cosmetic release that removes outdated badges from README

Fixed

• Remove oudated badges that belong to the upstream project this project was forked from.

0.2.0 - 2018-02-05

First release as oxc-postfix, now requires Puppet 4.9

Added

• Support support for FreeBSD operating system (#1)

Changed

• Minium required puppet version is now 4.9 for Hiera 5 support (#1)
• Move configuration to module hiera data (#1)
• Some lint/style changes (#1)

jiuka-postfix 0.1.0 2016-12-26

• Added postconf_master type and provider.

jiuka-postfix 0.0.1 2016-12-24

• Initial release