sendmail

Overview
Module Description - What the module does and why it is useful
Setup - The basics of getting started with sendmail
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

Overview

Install and manage the Sendmail MTA.

Module Description

Sendmail is a powerful mail transfer agent, and this modules provides an easier way to generate and manage the main Sendmail configuration files /etc/mail/sendmail.mc and /etc/mail/submit.mc. It also manages entries in various Sendmail database files (e.g. /etc/mail/access and /etc/mail/mailertable).

Setup

What sendmail affects

The module installs the operating system package to run the Sendmail MTA and possibly some other packages (make, m4, ...) to support it.
In a default installation almost all the managed files are in the /etc/mail directory. A notably exception is the /etc/aliases file.
The module may generate a new /etc/mail/sendmail.mc which is the source for /etc/mail/sendmail.cf. This file is the main Sendmail configuration file and it affects how Sendmail operates.

WARNING: Make sure to understand and test everything in these files before putting it in production. You alone are accountable for deploying a safe mailer configuration. If you do not know how to configure Sendmail without this module, then you should not assume you can do it with it.

Setup Requirements

The sendmail module uses a custom Augeas lense so the Puppet configuration setting pluginsync must be enabled. It also requires the Puppetlabs modules stdlib and concat.

Beginning with Sendmail

Declare the Sendmail class to install and run Sendmail with the default parameters.

class { 'sendmail': }

This installs the necessary packages and starts the Sendmail service. With this setup Sendmail will send messages to other hosts and also accept mail for the local host.

Sendmail has a lot of configuration knobs and a complete setup may need more than just a few parameters. So it is probably a good idea to encapsulate your Sendmail settings by using the roles and profiles pattern.

Usage

The Sendmail module provides classes and defined types to individually manage many of the configuration parameters used in the sendmail.mc file. This offers the possibility to manage even complex and unusual configurations with Puppet. The main Sendmail class also has parameters to directly enable certain configuration items without the need to provide a complete user defined sendmail.mc configuration.

I need a couple of macros and features in my Sendmail setting

Normally the configuration of Sendmail is done by adding define statements to the main sendmail.mc configuration file. The m4 macro processor is used to convert the settings into a sendmail.cf file that Sendmail understands.

The same mechanism is used to add features like greylisting, virtual user setups or DNS blacklists. Sendmail uses the feature statement in the sendmail.mc configuration to enable the features.

With the Sendmail module these settings are defined by adding resources using the sendmail::mc::define or sendmail::mc::feature defined types.

# Manage Sendmail and set a smart host and the maximum message size
class { 'sendmail':
  smart_host       => 'relay.example.com',
  max_message_size => '32MB',
}

# Set maximum number of daemon processes
sendmail::mc::define { 'confMAX_DAEMON_CHILDREN':
  expansion => '8',
}

# Include ratecontrol feature with parameters
sendmail::mc::feature { 'ratecontrol':
  args => [ 'nodelay', 'terminate', ],
}

# Enable access_db feature
sendmail::mc::feature { 'access_db': }

# Manage access_db entries in hiera
class { 'sendmail::access': }

# Manage aliases file using a template
class { 'sendmail::aliases':
  content => template('site/aliases.erb'),
}

See the Reference section for the complete list of available types that can be used.

Most hosts do not need to receive mail

Use the sendmail::nullclient class to create a setup where no mail can be received from the outside and all local mail is forwarded to a central mail hub. This configuration is appropriate for the majority of satellite hosts.

class { 'sendmail::nullclient':
  mail_hub => '[192.168.1.1]',
}

I already have a working config and like to keep it

Disable the internal management of the sendmail configuration files by setting the parameters manage_sendmail_mc or manage_submit_mc to false:

class { 'sendmail':
  manage_sendmail_mc => false,
  manage_submit_mc   => false,
}

Note: These settings also disable the automatic generation of the sendmail.cf and submit.cf files. You will have to do that yourself if you change one of the files.

I am behind a firewall and need to forward outgoing mail to a relay host

Use the smart_host parameter to set the host where all outgoing mail should be forwarded to.

class { 'sendmail':
  smart_host => 'relay.example.com',
}

I have a host that should not receive any mail from the outside

You can use the enable_ipv4_daemon and enable_ipv6_daemon parameters to prevent Sendmail from listening on all available network interfaces. Use the sendmail::mc::daemon_options defined type to explicitly define the addresses to use.

class { 'sendmail':
  enable_ipv4_daemon => false,
  enable_ipv6_daemon => false,
}

sendmail::mc::daemon_options { 'MTA-v4':
  addr   => '127.0.0.1',
  family => 'inet',
  port   => 'smtp',
}

Transport layer encryption (TLS) is a must in my setup

The Sendmail class has a comprehensive set of TLS related parameters. The following configuration creates a simple TLS enabled setup. Remember to adjust the pathnames to your setup.

class { 'sendmail':
  ca_cert_file     => '/etc/mail/tls/my-ca-cert.pem',
  server_cert_file => '/etc/mail/tls/server.pem',
  server_key_file  => '/etc/mail/tls/server.key',
  client_cert_file => '/etc/mail/tls/server.pem',
  client_key_file  => '/etc/mail/tls/server.key',
  cipher_list      => 'HIGH:!MD5:!eNULL',
}

Note: The Sendmail module does not manage any X.509 certificates or keys.

All my users are managed using LDAP

A complex configuration like this is supported by using the provided defined types as building blocks. The following example configuration reflects a setup that is actually in use.

sendmail::mc::define { 'confLDAP_CLUSTER':
  expansion => 'example.net',
}

sendmail::mc::define { 'confLDAP_DEFAULT_SPEC':
  expansion => '-H ldapi:/// -w 3 -b dc=example,dc=net',
}

sendmail::mc::ldaproute_domain { 'example.net': }

$ldap_filter = '(&(objectClass=inetLocalMailRecipient)(mailLocalAddress=%0))'

sendmail::mc::feature { 'ldap_routing':
  args => [
    "ldap -1 -T<TMPF> -v mailHost -k ${ldap_filter}",
    "ldap -1 -T<TMPF> -v mailRoutingAddress -k ${ldap_filter}",
    'bounce',
    'preserve',
    'nodomain',
    'tempfail',
  ]
}

sendmail::mc::feature { 'virtusertable':
  args => "ldap -1 -T<TMPF> -v uid -k ${ldap_filter}",
}

Reference

Public Classes
Private Classes
Public Defined Types
Augeas Lenses
- Augeas Lens: sendmail_map
Templates

Public Classes

Class: `sendmail`

Performs the basic setup and installation of Sendmail on the system.

Parameters for the sendmail class:

`smart_host`

Servers behind a firewall may not be able to deliver mail directly to the outside world. In this case the host may need to forward the mail to a gateway machine defined by this parameter. All nonlocal mail is forwarded to this gateway. Default value: undef

`domain_name`

Sets the official canonical name of the local machine. Normally this parameter is not required as Sendmail uses the fully qualified domain name by default. Setting this parameter will override the value of the $j macro in the sendmail.cf file. Default value: undef

`max_message_size`

Define the maximum message size that will be accepted. This can be a pure numerical value given in bytes (e.g. 33554432) or a number with a prefixed byte unit (e.g. 32MB). The conversion is done using the 1024 convention (see the to_bytes function in the stdlib module), so valid prefixes are either k for 1024 bytes or M for 1048576 bytes. Default value: undef

`log_level`

The loglevel for the sendmail process. Valid options: a numeric value. Default value: undef

`dont_probe_interfaces`

Sendmail normally probes all network interfaces to get all hostnames that the server may have. These hostnames are then considered local. This option can be used to prevent the reverse lookup of the network addresses. If this option is set to localhost then all network interfaces except for the loopback interface is probed. Valid options: the strings true, false or localhost. Default value: undef

`enable_ipv4_daemon`

Should the host accept mail on all IPv4 network adresses. Valid options: true or false. Default value: true

`enable_ipv6_daemon`

Should the host accept mail on all IPv6 network adresses. Valid options: true or false. Default value: true

`features`

A hash of features to include in the configuration. Each hash key should be a feature name while the value should be a hash itself. The value hash is used as parameters for the sendmail::mc::feature defined type. Check the documentation of this type for details. Default value: {}

Some features (e.g. mailertable, access_db, ...) may need to be managed individually. So the mailertable feature could be enabled using this parameter but that does not manage the mailertable file itself. So in addition you would have to use the sendmail::mailertable class or the sendmail::mailertable::entry defined type.

The following two code blocks are equivalent:

class { 'sendmail':
  ...
  features => {
    'delay_checks' => {},
    'mailertable'  => { 'args' => 'hash /etc/mail/mailertable' },
    'local_lmtp'   => { 'args' => [ '[IPC]', 'FILE /var/run/dovecot/lmtp' ] },
  },
  ...
}

class { 'sendmail':
  ...
}

sendmail::mc::feature { 'delay_checks': }

sendmail::mc::feature { 'mailertable':
  args => 'hash /etc/mail/mailertable',
}

sendmail::mc::feature { 'local_lmtp':
  args => [ '[IPC]', 'FILE /var/run/dovecot/lmtp' ],
}

`mailers`

An array of mailers to add to the configuration. Default value: [ 'smtp', 'local' ]

`local_host_names`

An array of hostnames that Sendmail recognizes for local delivery. Default value: [ $::fqdn ]

`relay_domains`

An array of domains that Sendmail accepts as relay target. This setting is required for secondary MX setups. Default value: []

`trusted_users`

An array of user names that will be written into the trusted users file. Leading or trailing whitespace is ignored. Empty entries are also ignored. Default value: []

`trust_auth_mech`

The value of trusted authentication mechanisms to set. If this is a string it is used as-is. For an array the value will be concatenated into a string. Default value: undef

`ca_cert_file`

The filename of the SSL CA certificate. Default value: undef

`ca_cert_path`

The directory where SSL CA certificates are kept. Default value: undef

`server_cert_file`

The filename of the SSL server certificate for inbound connections. Default value: undef

`server_key_file`

The filename of the SSL server key for inbound connections. Default value: undef

`client_cert_file`

The filename of the SSL client certificate for outbound connections. Default value: undef

`client_key_file`

The filename of the SSL client key for outbound connections. Default value: undef

`crl_file`

The filename with a list of revoked certificates. Default value: undef

`dh_params`

The DH parameters used for encryption. This can be one of the numbers 512, 1024, 2048 or a filename with pregenerated parameters. Default value: undef

`cipher_list`

Set the available ciphers for encrypted connections. Default value: undef

`server_ssl_options`

Configure the SSL connection flags for inbound connections. Default value: undef

`client_ssl_options`

Configure the SSL connection flags for outbound connections. Default value: undef

`cf_version`

The configuration version string for Sendmail. This string will be appended to the Sendmail version in the HELO message. If unset, no configuration version will be used. Default value: undef

`version_id`

The version id string included in the sendmail.mc file. This has no practical meaning other than having a user defined identifier in the file. Default value: undef

`msp_host`

The host where the message submission program should deliver to. This can be a hostname or IP address. To prevent MX lookups for the host, put it in square brackets (e.g., [hostname]). Delivery to the local host would therefore use either [127.0.0.1] for IPv4 or [IPv6:::1] for IPv6. Default value: [127.0.0.1]

`msp_port`

The port used for the message submission program. Can be a port number (e.g., 25) or the literal MSA for delivery to the message submission agent on port 587. Make sure to configure a daemon that listens on this port or local mail will remain stuck in the submission queue. Default value: MSA

`enable_msp_trusted_users`

Whether the trusted users file feature is enabled for the message submission program. This may be necessary if you want to allow certain users to change the sender address using sendmail -f. Valid options: true or false. Default value: false

`manage_sendmail_mc`

Whether to automatically manage the sendmail.mc file. Valid options: true or false. Default value: true

`manage_submit_mc`

Whether to automatically manage the submit.mc file. Valid options: true or false. Default value: true

`auxiliary_packages`

Additional packages that will be installed by the Sendmail module. Valid options: array of strings. Default value: varies by operating system.

`package_ensure`

Configure whether the Sendmail package should be installed, and what version. Valid options: present, latest, or a specific version number. Default value: present

`package_manage`

Configure whether Puppet should manage the Sendmail package(s). Valid options: true or false. Default value: true

`service_name`

The service name to use on this operating system.

`service_enable`

Configure whether the Sendmail MTA should be enabled at boot. Valid options: true or false. Default value: true

`service_manage`

Configure whether Puppet should manage the Sendmail service. Valid options: true or false. Default value: true

`service_ensure`

Configure whether the Sendmail service should be running. Valid options: running or stopped. Default value: running

`service_hasstatus`

Define whether the service type can rely on a working init script status. Valid options: true or false. Default value depends on the operating system and release.

Class: `sendmail::nullclient`

Create a simple Sendmail nullclient configuration. No mail can be received from the outside since the Sendmail daemon only listens on the localhost address 127.0.0.1. All local mail is forwarded to a given mail hub.

This is a convenience class to make the configuration simple. Internally it declares the sendmail class using appropriate parameters. Normally no other configuration should be necessary.

class { 'sendmail::nullclient':
  mail_hub           => '[192.168.1.1]',
  port_option_modify => 'S',
  enable_ipv6_msa    => false,
}

Parameters for the sendmail::nullclient class:

`mail_hub`

The hostname or IP address of the mail hub where all mail is forwarded to. It can be enclosed in brackets to prevent MX lookups.

`domain_name`

Sets the official canonical name of the local machine. Normally this parameter is not required as Sendmail uses the fully qualified domain name by default. Setting this parameter will override the value of the $j macro in the sendmail.cf file. Default value: undef

`max_message_size`

Define the maximum message size that will be accepted. This can be a pure numerical value given in bytes (e.g. 33554432) or a number with a prefixed byte unit (e.g. 32MB). The conversion is done using the 1024 convention (see the to_bytes function in the stdlib module), so valid prefixes are either k for 1024 bytes or M for 1048576 bytes. Default value: undef

`log_level`

The loglevel for the sendmail process. Valid options: a numeric value. Default value: undef

`enable_ipv4_msa`

Enable the local message submission agent on the IPv4 loopback address (127.0.0.1). Valid options: true or false. Default value: true

`enable_ipv6_msa`

Enable the local message submission agent on the IPv6 loopback address (::1). Valid options: true or false. Default value: true

`port`

The port used for the local message submission agent. Default value: 587

`port_option_modify`

Port option modifiers for the local message submission agent. This parameter is used for the daemon port options. A useful value for the nullclient configuration might be S to prevent offering STARTTLS on the MSA port. Default value: undef

`enable_msp_trusted_users`

Whether the trusted users file feature is enabled for the message submission program. This may be necessary if you want to allow certain users to change the sender address using sendmail -f. Valid options: true or false. Default value: false

`trusted_users`

An array of user names that will be written into the trusted users file. Leading or trailing whitespace is ignored. Empty entries are also ignored. Default value: []

`ca_cert_file`

The filename of the SSL CA certificate. Default value: undef

`ca_cert_path`

The directory where SSL CA certificates are kept. Default value: undef

`server_cert_file`

The filename of the SSL server certificate for inbound connections. Default value: undef

`server_key_file`

The filename of the SSL server key for inbound connections. Default value: undef

`client_cert_file`

The filename of the SSL client certificate for outbound connections. Default value: undef

`client_key_file`

The filename of the SSL client key for outbound connections. Default value: undef

`crl_file`

The filename with a list of revoked certificates. Default value: undef

`dh_params`

The DH parameters used for encryption. This can be one of the numbers 512, 1024, 2048 or a filename with pregenerated parameters. Default value: undef

`tls_srv_options`

The parameter adjusts the server TLS settings. This can currently be either the letter V or the empty string. Setting this parameter to V disables the request for a client certificate. Default value: undef

`cipher_list`

Set the available ciphers for encrypted connections. Default value: undef

`server_ssl_options`

Configure the SSL connection flags for inbound connections. Default value: undef

`client_ssl_options`

Configure the SSL connection flags for outbound connections. Default value: undef

Class: `sendmail::aliases`

Manage the Sendmail aliases file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::aliases':
  source => 'puppet:///modules/site/aliases',
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::aliases': }

Parameters for the sendmail::aliases class:

`content`

The desired contents of the aliases file. This allows managing the aliases file as a whole. Changes to the file automatically triggers a rebuild of the aliases database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the aliases file. This allows managing the aliases file as a whole. Changes to the file automatically triggers a rebuild of the aliases database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::aliases::entry resources. This attribute is mutually exclusive with content and source.

The class can be used to create aliases defined in hiera. The hiera hash should look like this:

sendmail::aliases::entries:
  'fred':
    recipient: '[email protected]'

Class: `sendmail::access`

Manage the Sendmail access db file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::access':
  source => 'puppet:///modules/site/access',
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::access': }

This class is only used to manage the access db file. You will also need to enable the access_db feature using sendmail::mc::feature to tell Sendmail to actually use the file.

Parameters for the sendmail::access class:

`content`

The desired contents of the access file. This allows managing the access file as a whole. Changes to the file automatically triggers a rebuild of the access database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the access file. This allows managing the access file as a whole. Changes to the file automatically triggers a rebuild of the access database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::access::entry resources. This attribute is mutually exclusive with content and source.

The class can be used to create access entries defined in hiera. The hiera hash should look like this:

sendmail::access::entries:
  'example.com':
    value: 'OK'
  'example.org':
    value: 'REJECT'

Class: `sendmail::domaintable`

Manage the Sendmail domaintable file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::domaintable':
  source => 'puppet:///modules/site/domaintable,
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::domaintable': }

Parameters for the sendmail::domaintable class:

`content`

The desired contents of the domaintable file. This allows managing the domaintable file as a whole. Changes to the file automatically triggers a rebuild of the domaintable database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the domaintable file. This allows managing the domaintable file as a whole. Changes to the file automatically triggers a rebuild of the domaintable database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::domaintable::entry resources. This attribute is mutually exclusive with content and source.

This class can be used to create domaintable entries defined in hiera. The hiera hash should look like this:

sendmail::domaintable::entries:
  'example.com':
    value: 'example.org'
  'example.net':
    value: 'example.org'

Class: `sendmail::genericstable`

Manage the Sendmail genericstable file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::genericstable':
  source => 'puppet:///modules/site/genericstable',
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::genericstable': }

Use the sendmail::mc::generics_domain type to configure the domains for which non-local user addresses should be rewritten.

Parameters for the sendmail::genericstable class:

`content`

The desired contents of the genericstable file. This allows managing the genericstable file as a whole. Changes to the file automatically triggers a rebuild of the genericstable database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the genericstable file. This allows managing the genericstable file as a whole. Changes to the file automatically triggers a rebuild of the genericstable database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::genericstable::entry resources. This attribute is mutually exclusive with content and source.

This class can be used to create genericstable entries defined in hiera. The hiera hash should look like this:

sendmail::genericstable::entries:
  '[email protected]':
    value: '[email protected]'
  'barney':
    value: '[email protected]'

Class: `sendmail::mailertable`

Manage the Sendmail mailertable file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::mailertable':
  source => 'puppet:///modules/site/mailertable',
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::mailertable': }

Parameters for the sendmail::mailertable class:

`content`

The desired contents of the mailertable file. This allows managing the mailertable file as a whole. Changes to the file automatically triggers a rebuild of the mailertable database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the mailertable file. This allows managing the mailertable file as a whole. Changes to the file automatically triggers a rebuild of the mailertable database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::mailertable::entry resources. This attribute is mutually exclusive with content and source.

This class can be used to create mailertable entries defined in hiera. The hiera hash should look like this:

sendmail::mailertable::entries:
  '.example.com':
    value: 'smtp:relay.example.com'
  'www.example.org':
    value: 'relay:relay.example.com'
  '.example.net':
    value: 'error:5.7.0:550 mail is not accepted'

Class: `sendmail::userdb`

Manage the Sendmail userdb file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::userdb':
  source => 'puppet:///modules/site/userdb',
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::userdb': }

Parameters for the sendmail::userdb class:

`content`

The desired contents of the userdb file. This allows managing the userdb file as a whole. Changes to the file automatically triggers a rebuild of the userdb database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the userdb file. This allows managing the userdb file as a whole. Changes to the file automatically triggers a rebuild of the userdb database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::userdb::entry resources. This attribute is mutually exclusive with content and source.

This class can be used to create userdb entries defined in hiera. The hiera hash should look like this:

sendmail::userdb::entries:
  'fred:maildrop':
    value: '[email protected]'
  'barney:maildrop':
    value: '[email protected]'

Class: `sendmail::virtusertable`

Manage the Sendmail virtusertable file. The class manages the file either as a single file resource or each entry in the file separately.

The file is managed as a whole using the source or content parameters.

class { 'sendmail::virtusertable':
  source => 'puppet:///modules/site/virtusertable',
}

The entries parameter is used to manage each entry separately. Preferable this is done with hiera using automatic parameter lookup.

class { 'sendmail::virtusertable': }

Parameters for the sendmail::virtusertable class:

`content`

The desired contents of the virtusertable file. This allows managing the virtusertable file as a whole. Changes to the file automatically triggers a rebuild of the virtusertable database file. This attribute is mutually exclusive with source and entries.

`source`

A source file for the virtusertable file. This allows managing the virtusertable file as a whole. Changes to the file automatically triggers a rebuild of the virtusertable database file. This attribute is mutually exclusive with content and entries.

`entries`

A hash that will be used to create sendmail::virtusertable::entry resources. This attribute is mutually exclusive with content and source.

This class can be used to create virtusertable entries defined in hiera. The hiera hash should look like this:

sendmail::virtusertable::entries:
  '[email protected]':
    value: 'fred'
  '@example.org':
    value: 'barney'

Class: `sendmail::mc::privacy_flags`

This class defines privacy options for the main Sendmail daemon. Each option is enabled by setting the associated boolean parameter to true. See the Sendmail documentation for the meaning of the flags.

class { 'sendmail::mc::privacy_flags':
  goaway         => true,
  restrictexpand => true,
  noetrn         => true,
}

Parameters for the sendmail::mc::privacy_flags class: