Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


postfix (70) Versions 6.0.1

Installs and configures postfix for client or outbound relayhost, or to do SASL auth

cookbook 'postfix', '= 6.0.1', :supermarket
cookbook 'postfix', '= 6.0.1'
knife supermarket install postfix
knife supermarket download postfix
Quality 83%

postfix Cookbook

Cookbook Version
CI State

Installs and configures postfix for client or outbound relayhost, or to do SASL authentication.

On RHEL-family systems, sendmail will be replaced with postfix.


This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit or come chat with us on the Chef Community Slack in #sous-chefs.



  • Ubuntu
  • Debian
  • RHEL/CentOS/Scientific
  • Amazon Linux (as of AMIs created after 4/9/2012)
  • FreeBSD

May work on other platforms with or without modification.


  • Chef 12.1+


  • none


See attributes/default.rb for default values.

Generic cookbook attributes

  • node['postfix']['mail_type'] - Sets the kind of mail configuration. master will set up a server (relayhost).
  • node['postfix']['relayhost_role'] - name of a role used for search in the client recipe.
  • node['postfix']['relayhost_port'] - listening network port of the relayhost.
  • node['postfix']['multi_environment_relay'] - set to true if nodes should not constrain search for the relayhost in their own environment.
  • node['postfix']['use_procmail'] - set to true if nodes should use procmail as the delivery agent.
  • node['postfix']['use_alias_maps'] - set to true if you want the cookbook to use/configure alias maps
  • node['postfix']['use_transport_maps'] - set to true if you want the cookbook to use/configure transport maps
  • node['postfix']['use_access_maps'] - set to true if you want the cookbook to use/configure access maps
  • node['postfix']['use_virtual_aliases'] - set to true if you want the cookbook to use/configure virtual alias maps
  • node['postfix']['use_relay_restrictions_maps'] - set to true if you want the cookbook to use/configure a list of domains to which postfix will allow relay
  • node['postfix']['aliases'] - hash of aliases to create with recipe[postfix::aliases], see below under Recipes for more information.
  • node['postfix']['transports'] - hash of transports to create with recipe[postfix::transports], see below under Recipes for more information.
  • node['postfix']['access'] - hash of access to create with recipe[postfix::access], see below under Recipes for more information.
  • node['postfix']['virtual_aliases'] - hash of virtual_aliases to create with recipe[postfix::virtual_aliases], see below under Recipes for more information.
  • node['postfix']['main_template_source'] - Cookbook source for template. Default 'postfix'
  • node['postfix']['master_template_source'] - Cookbook source for template. Default 'postfix' and sasl_passwd template attributes

The template has been simplified to include any attributes in the node['postfix']['main'] data structure. The following attributes are still included with this cookbook to maintain some semblance of backwards compatibility.

This change in namespace to node['postfix']['main'] should allow for greater flexibility, given the large number of configuration variables for the postfix daemon. All of these cookbook attributes correspond to the option of the same name in /etc/postfix/

  • node['postfix']['main']['biff'] - (yes/no); default no
  • node['postfix']['main']['append_dot_mydomain'] - (yes/no); default no
  • node['postfix']['main']['myhostname'] - defaults to fqdn from Ohai
  • node['postfix']['main']['mydomain'] - defaults to domain from Ohai
  • node['postfix']['main']['myorigin'] - defaults to $myhostname
  • node['postfix']['main']['mynetworks'] - default is nil, which forces Postfix to default to loopback addresses.
  • node['postfix']['main']['inet_interfaces'] - set to loopback-only, or all for server recipe
  • node['postfix']['main']['alias_maps'] - set to hash:/etc/aliases
  • node['postfix']['main']['mailbox_size_limit'] - set to 0 (disabled)
  • node['postfix']['main']['mydestination'] - default fqdn, hostname, localhost.localdomain, localhost
  • node['postfix']['main']['smtpd_use_tls'] - (yes/no); default yes. See conditional cert/key attributes.
  • node['postfix']['main']['smtpd_tls_cert_file'] - conditional attribute, set to full path of server's x509 certificate.
  • node['postfix']['main']['smtpd_tls_key_file'] - conditional attribute, set to full path of server's private key
  • node['postfix']['main']['smtpd_tls_CAfile'] - set to platform specific CA bundle
  • node['postfix']['main']['smtpd_tls_session_cache_database'] - set to btree:${data_directory}/smtpd_scache
  • node['postfix']['main']['smtp_use_tls'] - (yes/no); default yes. See following conditional attributes.
  • node['postfix']['main']['smtp_tls_CAfile'] - set to platform specific CA bundle
  • node['postfix']['main']['smtp_tls_session_cache_database'] - set to btree:${data_directory}/smtpd_scache
  • node['postfix']['main']['smtp_sasl_auth_enable'] - (yes/no); default no. If enabled, see following conditional attributes.
  • node['postfix']['main']['smtp_sasl_password_maps'] - Set to hash:/etc/postfix/sasl_passwd template file
  • node['postfix']['main']['smtp_sasl_security_options'] - Set to noanonymous
  • node['postfix']['main']['relayhost'] - Set to empty string
  • node['postfix']['sender_canonical_map_entries'] - (hash with key value pairs); default not configured. Setup generic canonical maps. See man 5 canonical. If has at least one value, then will be enabled in config.
  • node['postfix']['smtp_generic_map_entries'] - (hash with key value pairs); default not configured. Setup generic postfix maps. See man 5 generic. If has at least one value, then will be enabled in config.
  • node['postfix']['recipient_canonical_map_entries'] - (hash with key value pairs); default not configured. Setup generic canonical maps. See man 5 canonical. If has at least one value, then will be enabled in config.
  • node['postfix']['sasl']['smtp_sasl_user_name'] - SASL user to authenticate as. Default empty. You can only use this until the current version. The new syntax is below.
  • node['postfix']['sasl']['smtp_sasl_passwd'] - SASL password to use. Default empty. You can only use this until the current version. The new syntax is below.
  • node['postfix']['sasl'] = json { "relayhost1" => { 'username' => 'foo', 'password' => 'bar' }, "relayhost2" => { ... } } - You must set the following attribute, otherwise the attribute will default to empty

Example of json role config, for setup *_map_entries:

postfix : {


"smtp_generic_map_entries" : { "root@youinternaldomain.local" : "", "admin@youinternaldomain.local" : "" }

} template attributes

The template has been changed to allow full customization of the file content. For purpose of backwards compatibility default attributes generate the same But via node['postfix']['master'] data structure in your role for instance it can be completelly rewritten.

Examples of json role config, for customize

postfix : {


turn some services off or on:

  "master" : {
    "smtps": {
      "active": true
    "old-cyrus": {
      "active": false
    "cyrus": {
      "active": false
    "uucp": {
      "active": false
    "ifmail": {
      "active": false

... define you own service:

    "spamfilter": {
      "comment": "My own spamfilter",
      "active": true,
      "order": 590,
      "type": "unix",
      "unpriv": false,
      "chroot": false,
      "command": "pipe",
      "args": ["flags=Rq user=spamd argv=/usr/bin/ -oi -f ${sender} ${recipient}"]


} }

The possible service hash fields and their meanings: hash key - have to be unique, unless you wish to override default definition.

Field Mandatory Description
active Yes Boolean. Defines whether or not the service needs to be in
comment No String. If you would like to add a comment line before service line
order Yes Integer. Number to define the order of lines in the file
type Yes String. Type of the service (inet, unix, fifo)
private No Boolean. If present replaced by y or n, otherwise by -
unpriv No Boolean. If present replaced by y or n, otherwise by -
chroot No Boolean. If present replaced by y or n, otherwise by -
wakeup No String. If present value placed in file, otherwise replaced by -
maxproc No String. If present value placed in file, otherwise replaced by -
command Yes String. The command to be executed.
args Yes Array of Strings. Arguments passed to command.

For more information about meaning of the fields consult master (5) manual:



Installs the postfix package and manages the service and the main configuration files (/etc/postfix/ and /etc/postfix/ See Usage and Examples to see how to affect behavior of this recipe through configuration. Depending on the node['postfix']['use_alias_maps'], node['postfix']['use_transport_maps'], node['postfix']['use_access_maps'] and node['postfix']['use_virtual_aliases'] attributes the default recipe can call additional recipes to manage additional postfix configuration files

For a more dynamic approach to discovery for the relayhost, see the client and server recipes below.


Use this recipe to have nodes automatically search for the mail relay based which node has the node['postfix']['relayhost_role'] role. Sets the node['postfix']['main']['relayhost'] attribute to the first result from the search.

Includes the default recipe to install, configure and start postfix.

Does not work with chef-solo.


Sets up the system to authenticate with a remote mail relay using SASL authentication.


To use Chef Server search to automatically detect a node that is the relayhost, use this recipe in a role that will be relayhost. By default, the role should be "relayhost" but you can change the attribute node['postfix']['relayhost_role'] to modify this.

Note This recipe will set the node['postfix']['mail_type'] to "master" with an override attribute.


General recipe to manage any number of any type postfix lookup tables. You can replace with it recipes like transport or virtual_aliases, but what is more important - you can create any kinds of maps, which has no own recipe, including database lookup maps configuration. maps is a hash keys of which is a lookup table type and value is another hash with filenames as the keys and hash with file content as the value. File content is an any number of key/value pairs which meaning depends on lookup table type. Examlle:

  "override_attributes": {
    "postfix": {
      "maps": {
        "hash": {
          "/etc/postfix/vmailbox": {
            "": "ok",
            "": "ok",
          "/etc/postfix/virtual": {
            "": "",
            "": "",
            "": ""
          "/etc/postfix/envelope_senders": {
            "": "",
            "": ""
          "/etc/postfix/relay_recipients": {
            "": "ok",
            "": "ok",
            "": "ok",
       "pgsql": {
          "/etc/postfix/pgtest": {
            "hosts": "db.local:2345",
            "user": "postfix",
            "password": "test",
            "dbname": "postdb",
            "query": "SELECT replacement FROM aliases WHERE mailbox = '%s'"

To use these files in your configuration reference them in node['postfix']['main'], for instance:

    "postfix": {
      "main": {
        "smtpd_sender_login_maps": "hash:/etc/postfix/envelope_senders",
        "relay_recipient_maps": "hash:/etc/postfix/relay_recipients",
        "virtual_mailbox_maps": "hash:/etc/postfix/vmailbox",
        "virtual_alias_maps": "hash:/etc/postfix/virtual",


Manage /etc/aliases with this recipe. Currently only Ubuntu 10.04 platform has a template for the aliases file. Add your aliases template to the templates/default or to the appropriate platform+version directory per the File Specificity rules for templates. Then specify a hash of aliases for the node['postfix']['aliases'] attribute.

Arrays are supported as alias values, since postfix supports comma separated values per alias, simply specify your alias as an array to use this handy feature.


Manage /etc/aliases with this recipe.


Manage /etc/postfix/transport with this recipe.


Manage /etc/postfix/access with this recipe.


Manage /etc/postfix/virtual with this recipe.


Manage /etc/postfix/relay_restriction with this recipe The postfix option smtpd_relay_restrictions in will point to this hash map db.


On systems that should simply send mail directly to a relay, or out to the internet, use recipe[postfix] and modify the node['postfix']['main']['relayhost'] attribute via a role.

On systems that should be the MX for a domain, set the attributes accordingly and make sure the node['postfix']['mail_type'] attribute is master. See Examples for information on how to use recipe[postfix::server] to do this automatically.

If you need to use SASL authentication to send mail through your ISP (such as on a home network), use postfix::sasl_auth and set the appropriate attributes.

For each of these implementations, see Examples for role usage.


The example roles below only have the relevant postfix usage. You may have other contents depending on what you're configuring on your systems.

The base role is applied to all nodes in the environment.

name "base"
  "postfix" => {
    "mail_type" => "client",
    "main" => {
      "mydomain" => "",
      "myorigin" => "",
      "relayhost" => "[]",
      "smtp_use_tls" => "no"

The relayhost role is applied to the nodes that are relayhosts. Often this is 2 systems using a CNAME of

name "relayhost"
  "postfix" => {
    "mail_type" => "master",
    "main" => {
      "mynetworks" => [ "", "" ],
      "inet_interfaces" => "all",
      "mydomain" => "",
      "myorigin" => ""

The sasl_relayhost role is applied to the nodes that are relayhosts and require authenticating with SASL. For example this might be on a household network with an ISP that otherwise blocks direct internet access to SMTP.

name "sasl_relayhost"
run_list("recipe[postfix], recipe[postfix::sasl_auth]")
  "postfix" => {
    "mail_type" => "master",
    "main" => {
      "mynetworks" => "",
      "mydomain" => "",
      "myorigin" => "",
      "relayhost" => "[]:587",
      "smtp_sasl_auth_enable" => "yes"
    "sasl" => {
      "relayhost1" => {
        "username" => "your_password",
        "password" => "your_username"
      "relayhost2" => {

For an example of using encrypted data bags to encrypt the SASL password, see the following blog post:

Examples using the client & server recipes

If you'd like to use the more dynamic search based approach for discovery, use the server and client recipes. First, create a relayhost role.

name "relayhost"
  "postfix" => {
    "main" => {
      "mynetworks" => "",
      "mydomain" => "",
      "myorigin" => ""

Then, add the postfix::client recipe to the run list of your base role or equivalent role for postfix clients.

name "base"
  "postfix" => {
    "mail_type" => "client",
    "main" => {
      "mydomain" => "",
      "myorigin" => ""

If you wish to use a different role name for the relayhost, then also set the attribute in the base role. For example, postfix_master as the role name:

name "postfix_master"
description "a role for postfix master that isn't relayhost"
  "postfix" => {
    "main" => {
      "mynetworks" => "",
      "mydomain" => "",
      "myorigin" => ""

The base role would look something like this:

name "base"
  "postfix" => {
    "relayhost_role" => "postfix_master",
    "mail_type" => "client",
    "main" => {
      "mydomain" => "",
      "myorigin" => ""

To use relay restrictions override the relay restrictions attribute in this format:

  "postfix" => {
    "use_relay_restrictions_maps" => true,
    "relay_restrictions" => {
      "" => "OK",
      "" => "OK",
      "" => "OK"


This project exists thanks to all the people who contribute.


Thank you to all our backers!


Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

Dependent cookbooks

This cookbook has no specified dependencies.

Contingent cookbooks

backuppc-server Applicable Versions
base_install Applicable Versions
cloudbees-cjp-ha Applicable Versions
cronapt Applicable Versions
mailcatcher-ng Applicable Versions
mw_server_base Applicable Versions
noosfero Applicable Versions
notifier Applicable Versions
owncloud Applicable Versions
paramount Applicable Versions
pennyworth Applicable Versions
platformstack Applicable Versions
postfix-dkim Applicable Versions
q2a Applicable Versions
rkhunter Applicable Versions
sanity Applicable Versions
ut_base Applicable Versions
zammad Applicable Versions
zarafa Applicable Versions
zeyple Applicable Versions

postfix Cookbook CHANGELOG

This file is used to list changes made in each version of the postfix cookbook.

6.0.1 - 2021-06-01

6.0.0 - 2020-11-23

  • Disabled SSLv3 by default

5.4.1 - 2020-10-20

  • Ensure all postmap files are rebuilt immediately if needed

5.4.0 - 2020-10-11


  • Sous Chefs Adoption
  • Update to use Sous Chefs GH workflow
  • Update README to sous-chefs
  • Update metadata.rb to Sous Chefs
  • Update test-kitchen to Sous Chefs


  • Standardise files with files in sous-chefs/repo-management
  • Add Ubuntu 20.04 testing


  • Cookstyle fixes
  • ChefSpec fixes
  • Yamllint fixes
  • MDL fixes
  • Fix OpenSUSE installation issues


  • Remove EL 6 testing
  • Remove Amazon Linux 1 testing

5.3.1 (2018-07-24)

  • Fixed sbin issue with Chef13

5.3.0 (2018-05-23)

  • support multiple sasl_passwd entries
  • Add packages attribute so different postfix packages can be installed
  • add ability to set network connection port for a remote relayhost

5.2.1 (2017-11-22)

  • Properly support FreeBSD
  • Do not run service restart for solaris which fails

5.2.0 (2017-08-07)

  • Lazily evaluate the config template variables to allow overrides to properly apply
  • Avoid Chefspec deprecation warnings

5.1.1 (2017-07-28)

  • Fix support for Amazon Linux on Chef 13
  • Expand testing to cover Debian 9 in Travis

5.1.0 (2017-07-28)

  • Add an option to allow recipient canonical maps

5.0.3 (2017-06-26)

  • Correct attribute line for use_relay_restrictions_maps to prevent converge failures

5.0.2 (2017-05-17)

  • Fix use_relay_restrictions_maps attribute misspelling in attributes file

5.0.1 (2017-03-03)

  • Fix documentation error on inet-interfaces
  • Test with Local Delivery instead of Rake
  • Fix attributes types on README

5.0.0 (2017-01-17)

  • Manage any hash: tables for postfix with hash_maps recipe
  • Fully customizable file
  • Support for any kind of postfix lookup tables
  • Remove old minitest files
  • Update chef requirement in the readme
  • Update tests for new config comment blocks
  • fixing /etc/aliases syntax for full-mailaddresses

4.0.0 (2016-09-07)

  • Update supported platforms in metadata
  • Remove node name from config file
  • Testing updates
  • Use node.normal vs. node.set to avoid deprecation warnings
  • Require Chef 12+

v3.8.0 (2016-04-01)

  • Updated attributes to use node.default_unless instead of node.default to be more wrapper friendly
  • Added integration and unit testing in Travis CI
  • Added rubocop config and resolved rubocop warnings
  • Added Gemfile with all necessary test deps
  • Added standard gitignore and chefignore files
  • Added updated contributing and testing docs
  • Removed the Kitchen Digital Ocean files and dependencies
  • Added additional platforms to the Test Kitchen config
  • Added a Rakefile for simplified testing
  • Fixed a typo in the use_relay_restrictions_maps attribute that prevented the default from being set
  • Added fedora and oracle as supported platforms in the metadata
  • Removed the attributes from the metadata.
  • Added long_description to the metadata
  • Added Chef 11 compatibility checks to issues_url and source_url in metadata.rb
  • Added and maintainers.toml files

v3.7.0 (2015-04-30)

  • Adding support for relay restrictions
  • Update chefspec and serverspec tests

v3.6.2 (2014-10-31)

  • Fix FreeBSDisms

v3.6.1 (2014-10-28)

  • Fix documentation around node['postfix']['main']['relayhost'] attribute
  • Fix logic around include_recipe 'postfix::virtual_aliases_domains'

v3.6.0 (2014-08-25)

  • restart postfix after updating virtual alias templates #86
  • fixing typo for alias_db location in omnios
  • moving conditional attributes to a recipe so they can be modified
  • via other cookbook attributes

v3.5.0 (2014-08-25)

Adding virtual_domains functionality

v3.4.1 (2014-08-20)

Removing unused parameters from

v3.4.0 (2014-07-25)

Refactoring to fix some logic issues

v3.3.1 (2014-06-11)

Reverting #37 - [COOK-3418] Virtual Domain Support PR - duplicate of #55

v3.3.0 (2014-06-11)

  • 37 - [COOK-3418] - Virtual Domain Support
  • 44 - Fix minor formatting issue in attributes
  • 55 - Add support for virtual aliases
  • 57 - Fixing attributes bug in README
  • 64 - add smtp_generic maps configuration option
  • 66 - [COOK-3652] Add support for transport mappings
  • 67 - [COOK-4662] Added support for access control
  • 68 - Properly handle binding to loopback on mixed IPV4/IPV6 systems

v3.2.0 (2014-05-09)

  • [COOK-4619] - no way to unset recipient_delimiter

v3.1.8 (2014-03-27)

  • [COOK-4410] - Fix sender_canonical configuration by adding template
  • and postmap execution

v3.1.6 (2014-03-19)

  • [COOK-4423] - use platform_family, find cert.pem on rhel

v3.1.4 (2014-02-27)

[COOK-4329] Migrate minitest PITs to latest test-kitchen + serverspec

v3.1.2 (2014-02-19)


  • COOK-4357 - postfix::sasl_auth recipe fails to converge

v3.1.0 (2014-02-19)


  • COOK-4322 - Postfix cookbook has incorrect default path for sasl_passwd

New Feature

  • COOK-4086 - use conf_dir attribute for sasl recipe, and add omnios support
  • COOK-2551 - Support creating the sender_canonical map file




  • COOK-3822 - postfix cookbook readme has an incorrect example
  • Got rubocop errors down to 32

New Feature

  • COOK-2551 - Support creating the sender_canonical map file



  • COOK-3617 - Fix error when no there is no FQDN
  • COOK-3530 - Update client.rb after 3.0.0 refactor
  • COOK-2499 - Do not use resource cloning




  • COOK-3328 - Postfix main/master and attributes refactor

Breaking changes:

  • Attributes are namespaced as node['postfix'], node['postfix']['main'], and node['postfix']['master'].



  • [COOK-2501]: Reference to ['postfix']['domain'] should be ['postfix']['mydomain']
  • [COOK-2715]: uses old name for smtp_fallback_relay (fallback_relay) parameter in


  • [COOK-2281] - postfix aliases uses require_recipe statement


  • [COOK-2010] - postfix sasl_auth does not include the sasl plain package


  • [COOK-1233] - optional configuration for canonical maps
  • [COOK-1660] - allow comma separated arrays in aliases
  • [COOK-1662] - allow inet_interfaces configuration via attribute


This version uses platform_family attribute, making the cookbook incompatible with older versions of Chef/Ohai, hence the major version bump.

  • [COOK-1535] - smtpd_cache should be in data_directory, not queue_directory
  • [COOK-1790] - /etc/aliases template is only in ubuntu directory
  • [COOK-1792] - add minitest-chef tests to postfix cookbook


  • [COOK-1442] - Missing ['postfix']['domain'] Attribute causes initial installation failure
  • [COOK-1520] - Add support for procmail delivery
  • [COOK-1528] - Make aliasses template less specific
  • [COOK-1538] - Add iptables_rule template
  • [COOK-1540] - Add smtpd_milters and non_smtpd_milters parameters to


  • [COOK-880] - add client/server roles for search-based discovery of relayhost


  • [COOK-668] - RHEL/CentOS/Scientific/Amazon platform support
  • [COOK-733] - postfix::aliases recipe to manage /etc/aliases
  • [COOK-821] - add :)


  • Current public release.

Collaborator Number Metric

6.0.1 passed this metric

Contributing File Metric

6.0.1 passed this metric

Foodcritic Metric

6.0.1 passed this metric

No Binaries Metric

6.0.1 passed this metric

Testing File Metric

6.0.1 passed this metric

Version Tag Metric

6.0.1 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must include a tag that matches this cookbook version number