diff --git a/README.md b/README.md
index b4a9a5836a6acdbbf177f0b654bb7739be219683..739fc773e4842816799ea648890ec66dac8df2f2 100644
--- a/README.md
+++ b/README.md
@@ -1,439 +1,44 @@
# Postfix Puppet Module
+[](https://github.com/voxpupuli/puppet-postfix/blob/master/LICENSE)
[](https://forge.puppetlabs.com/puppet/postfix)
[](https://forge.puppetlabs.com/puppet/postfix)
-[](https://travis-ci.org/voxpupuli/puppet-postfix)
+[](https://github.com/voxpupuli/puppet-postfix/actions?query=workflow%3ACI)
[](#transfer-notice)
-This module requires Augeas.
+## Features
-## Simple usage
-```puppet
-include postfix
+* Configure postfix as mta or satellite
+* Support for amavis scanner config
+* Dovecot as the local delivery agent config
+* Support Schleuder GPG-enabled mailing list
+* Sympa mailing list management software
+* Support for mailman
+* Support for LDAP
-postfix::config { 'relay_domains':
- ensure => present,
- value => 'localhost host.foo.com',
-}
-```
+## Supported OS
-## Classes
+* Ubuntu
+* Debian
+* CentOS
+* RedHat
+* Alpine
+* Fedora
+* FreeBSD
-### postfix
+## Dependencies
+ - [camptocamp-augeas 1.0.0+](https://github.com/camptocamp/puppet-augeas)
+ - [puppet-alternatives 2.0.0+](https://github.com/voxpupuli/puppet-alternatives)
+ - [puppetlabs-mailalias_core 1.0.5+](https://github.com/puppetlabs/puppetlabs-mailalias_core)
+ - [puppetlabs-stdlib 4.13.0+](https://github.com/puppetlabs/puppetlabs-stdlib)
-The top-level class, to install and configure Postfix.
+## Puppet
-#### Parameters
+The supported Puppet versions are listed in the [metadata.json](metadata.json)
-##### `alias_maps`
+## REFERENCES
-A string defining the location of the alias map file.
-Default: 'hash:/etc/aliases'.
-Example: 'hash:/etc/other_aliases'.
-
-##### `configs`
-
-A hash containing optional configuration values for main.cf. The values are configured using postfix::config.
-Default: An empty hash.
-Example: '{message_size_limit': {'value': '51200000'}}.
-
-##### `inet_interfaces`
-
-A string defining the network interfaces that Postfix will listen on.
-Default: 'all'.
-Example: '127.0.0.1, [::1]'.
-
-##### `inet_protocols`
-
-
-A string defining the internet protocols that Postfix will use.
-Default: 'all'.
-Example: 'ipv4'.
-
-##### `ldap`
-
-A Boolean defining whether to configure Postfix for LDAP use.
-Default: false.
-
-##### `ldap_base`
-
-A string defining the LDAP search base to use. This parameter maps to the search_base parameter (ldap_table(5)).
-Default: Undefined.
-Example 'cn=Users,dc=example,dc=com'.
-
-##### `ldap_host`
-
-A string defining the LDAP host. This parameter maps to the server_host parameter (ldap_table(5)).
-Default: Undefined.
-Example: 'ldaps://ldap.example.com:636 ldap://ldap2.example.com'.
-
-##### `ldap_options`
-
-A free form string that can define any ldap options to be passed through (ldap_table(5)).
-Default: Undefined.
-Example: 'start_tls = yes'.
-
-##### `mail_user`
-
-A string defining the mail user, and optionally group, to execute external commands as. This parameter maps to the user parameter (pipe(8)).
-Default: 'vmail'.
-Example: 'vmail:vmail'.
-
-##### `mailman`
-
-A Boolean defining whether to configure a basic smtp server that is able to work for the mailman mailing list manager.
-Default: false.
-
-##### `maincf_source`
-
-A string defining the location of a skeleton main.cf file to be used. The default file supplied is blank. However, if the main.cf file already exists on the system the contents will **NOT** be replaced by the contents from maincf_source.
-Default: "puppet:///modules/${module_name}/main.cf".
-Example: 'puppet:///modules/some/other/location/main.cf'.
-
-##### `manage_conffiles`
-
-A Boolean defining whether the puppet module should replace the configuration files for postfix.
-**This setting currently effects only the following files:**
-* /etc/mailname
-* /etc/postfix/master.cf
-
-
-**This setting does NOT effect the following files:**
-* /etc/aliases
-* /etc/postfix/main.cf
-
-Default: true.
-
-##### `manage_mailname`
-
-A Boolean defining whether the puppet module should manage '/etc/mailname'.
-See also $manage_conffiles
-
-Default: true.
-
-##### `manage_mailx`
-
-A Boolean defining whether the puppet module should manage the mailx package. See also $mailx_ensure.
-
-Default: true.
-
-##### `masquerade_classes`
-An array defining the masquerade_classes to use.
-Default: Undefined.
-Example: ['envelope_sender', 'envelope_recipient', 'header_sender', 'header_recipient']
-
-##### `masquerade_domains`
-An array defining the masquerade_domains to use.
-The order of elements matters here, so be aware of how you define the elements.
-Default: Undefined.
-Example: ['foo.example.com', 'example.com']
-
-##### `masquerade_exceptions`
-An array defining the masquerade_exceptions to use.
-Default: Undefined.
-Example: ['root']
-
-##### `mastercf_source`
-A string defining the location of a skeleton master.cf file to be used.
-Default: Undefined.
-Example: 'puppet:///modules/some/other/location/master.cf'.
-
-##### `master_smtp`
-A string to define the smtp line in the /etc/postfix/master.cf file. If this is defined the smtp_listen parameter will be ignored.
-Default: Undefined.
-Example: 'smtp inet n - n - - smtpd'.
-
-##### `master smtps`
-A string to define the smtps line in the /etc/postfix/master.cf file.
-Default: Undefined.
-Example: 'smtps inet n - n - - smtpd'.
-
-##### `master_submission`
-A string to define the submission line in the /etc/postfix/master.cf file.
-Default: Undefined.
-Example: 'submission inet n - n - - smtpd'.
-
-##### `master_entries`
-Array of strings containing additional entries for the /etc/postfix/master.cf file.
-Default: Undefined.
-Example: 'submission inet n - n - - smtpd'.
-
-##### `mta`
-A Boolean to define whether to configure Postfix as a mail transfer agent. This option is mutually exclusive with the satellite Boolean.
-Default: False.
-
-##### `mydestination`
-A string to define the mydestination parameter in main.cf (postconf(5)).
-Default: The systems FQDN.
-Example: 'example.com, foo.example.com'.
-
-##### `mynetworks`
-A string to define the mynetworks parameter that holds trusted remote smtp clients (postconf(5)).
-Default: '127.0.0.0/8'.
-Example: '127.0.0.0/8, [::1]/128'.
-
-##### `myorigin`
-A string to define the myorigin parameter that holds the domain name that mail appears to come from (postconf(5)).
-Default: The FQDN of the host.
-Example: 'example.com'
-
-##### `relayhost`
-A string to define the relayhost parameter (postconf(5)).
-Default: Undefined.
-Example: 'smtp.example.com'.
-
-##### `root_mail_recipient`
-A string to define the e-mail address to which all mail directed to root should go (aliases(5)).
-Default: 'nobody'.
-Example: 'root_catch@example.com'.
-
-##### `chroot`
-A boolean to define if postfix should be run in a chroot jail or not. If not defined, '-' is used (OS dependant)
-Default: Undefined.
-Example: true
-
-##### `satellite`
-A Boolean to define whether to configure postfix as a satellite relay host. This setting is mutually exclusive with the mta Boolean.
-Default: False.
-
-##### `smtp_listen`
-A string or an array of strings to define the IPs on which to listen in master.cf. This can also be set to 'all' to listen on all interfaces. If master_smtp is defined smtp_listen will not be used.
-Default: '127.0.0.1'.
-Example: '::1'.
-
-##### `use_amavisd`
-A Boolean to define whether to configure master.cf to allow the use of the amavisd scanner.
-Default: False.
-
-##### `use_dovecot_lda`
-A Boolean to define whether to configure master.cf to use dovecot as the local delivery agent.
-Default: False.
-
-##### `use_schleuder`
-A Boolean to define whether to configure master.cf to use the Schleuder GPG-enabled mailing list.
-Default: False.
-
-##### `use_sympa`
-A Boolean to define whether to configure master.cf to use the Sympa mailing list management software.
-Default: False.
-
-#### Examples
-##### Include
-```puppet
-include postfix
-```
-or
-##### Class Resource
-```puppet
-class { 'postfix':
- inet_interfaces => 'localhost',
- inet_protocols => 'ipv4',
- relayhost => "mail.${facts['domain']}",
- root_mail_recipient => 'dont_bother_the_sysadmins@example.com',
-}
-```
-
-### postfix::config
-
-Add/alter/remove options in Postfix main configuration file (main.cf). This uses Augeas to do the editing of the configuration file, as such any configuration value can be used.
-
-#### Parameters
-
-##### `ensure`
-A string whose value can be any of 'present', 'absent', 'blank'.
-Default: present.
-Example: blank.
-
-##### `value`
-A string that can contain any text to be used as the configuration value.
-Default: Undefined.
-Example: 'btree:${data_directory}/smtp_tls_session_cache'.
-
-#### Examples
-##### Configure Postfix to use TLS as a client
-```puppet
-postfix::config {
- 'smtp_tls_mandatory_ciphers': value => 'high';
- 'smtp_tls_security_level': value => 'secure';
- 'smtp_tls_CAfile': value => '/etc/pki/tls/certs/ca-bundle.crt';
- 'smtp_tls_session_cache_database': value => 'btree:${data_directory}/smtp_tls_session_cache';
-}
-```
-
-##### Configure Postfix to disable the vrfy command
-```puppet
-postfix::config { 'disable_vrfy_command':
- ensure => present,
- value => 'yes',
-}
-```
-
-### postfix::hash
-Creates Postfix hashed "map" files, and builds the corresponding db file.
-
-#### Parameters
-
-##### `ensure`
-Defines whether the hash map file is present or not. Value can either be present or absent.
-Default: present.
-Example: absent.
-
-##### `content`
-A free form string that defines the contents of the file. This parameter is mutually exclusive with the source parameter.
-Default: Undefined.
-Example: '#Destination Credentials\nsmtp.example.com gssapi:nopassword'.
-
-##### `source`
-A string whose value is a location for the source file to be used. This parameter is mutually exclusive with the content parameter, one or the other must be present, but both cannot be present.
-Default: Undefined.
-Example: 'puppet:///modules/some/location/sasl_passwd'.
-
-#### Examples
-##### Create a sasl_passwd hash from a source file
-```puppet
-postfix::hash { '/etc/postfix/sasl_passwd':
- ensure => 'present',
- source => 'puppet:///modules/profile/postfix/client/sasl_passwd',
-}
-```
-##### Create a sasl_passwd hash with contents defined in the manifest
-```puppet
-postfix::hash { '/etc/postfix/sasl_passwd':
- ensure => 'present',
- content => '#Destination Credentials\nsmtp.example.com gssapi:nopassword',
-}
-```
-### postfix::transport
-
-Manages content of the /etc/postfix/transport map.
-
-#### Requirements
-
-Augeas is, of course, required.
-
-The following code is required to use transport maps.
-```puppet
-include postfix
-
-postfix::hash { '/etc/postfix/transport':
- ensure => present,
-}
-
-postfix::config { 'transport_maps'
- ensure => present,
- value => 'hash:/etc/postfix/transport',
-}
-```
-#### Parameters
-
-##### `ensure`
-Defines whether the transport entry is present or not. Value can either be present or absent.
-Default: present.
-Example: absent.
-
-##### `destination`
-The destination to be delivered to (transport(5)).
-Default: Undefined.
-Example: 'mailman'.
-
-##### `nexthop`
-A string to define where and how to deliver the mail (transport(5)).
-Default: Undefined.
-Example: '[smtp.google.com]:25'.
-
-#### Examples
-
-### postfix::virtual
-
-Manages the contents of the virtual map.
-
-#### Requirements
-Augeas is, of course, required.
-
-The following code is necessary to make virtual maps work:
-```puppet
-include postfix
-
-postfix::hash { '/etc/postfix/virtual':
- ensure => present,
-}
-
-postfix::config { 'virtual_alias_maps':
- ensure => present,
- value => 'hash:/etc/postfix/virtual',
-}
-```
-#### Parameters
-##### `ensure`
-A string whose valid values are present or absent.
-Default: present.
-Example: absent.
-
-##### `file`
-A string defining the location of the virtual map, pre hash.
-Default: '/etc/postfix/virtual'.
-Example: '/etc/postfix/my_virtual_map'.
-
-##### `destination`
-A string defining where the e-mails will be delivered to, (virtual(8)).
-Default: Undefined.
-Example: 'root'
-
-#### Examples
-
-##### Route mail bound for 'user@example.com' to root.
-```puppet
-postfix::virtual {'user@example.com':
- ensure => present,
- destination => 'root',
-}
-```
-
-### postfix::conffile
-
-Manages postfix configuration files. With it, you could create configuration files (other than, main.cf, master.cf, etc.) restarting postfix when necessary.
-
-#### Parameters
-##### `ensure`
-A string whose valid values are present, absent or directory.
-Default: present.
-Example: absent.
-
-##### `source`
-A string with the source of the file. This is the `source` parameter of the underlying file resource.
-Default: `undef`
-Example: 'puppet:///modules/postfix/configfile.cf'
-
-##### `content`
-The content of the postfix configuration file. This is an alternative to the `source` parameter. If you don't provide `source` neither `content` parameters a default template is used and the content is created with values in the `options` hash.
-Default: `undef`
-
-##### `path`
-Path where to create the configuration file.
-Default: '/etc/postfix/${name}'
-
-##### `mode`
-Permissions of the configuration file. This option is useful if you want to create the file with specific permissions (for example, because you have passwords in it).
-Default: '0644'
-Example: '0640'
-
-##### `options`
-Hash with the options used in the default template that is used when neither `source` neither `content`parameters are provided.
-Default: {}
-Example:
-```
- postfix::conffile { 'ldapoptions.cf':
- options => {
- server_host => ldap.mydomain.com,
- bind => 'yes',
- bind_dn => 'cn=admin,dc=mydomain,dc=com',
- bind_pw => 'password',
- search_base => 'dc=example, dc=com',
- query_filter => 'mail=%s',
- result_attribute => 'uid',
- }
- }
-```
+Please see [REFERENCE.md](https://github.com/voxpupuli/puppet-postfix/blob/master/REFERENCE.md) for more details.
## Contributing
diff --git a/REFERENCE.md b/REFERENCE.md
new file mode 100644
index 0000000000000000000000000000000000000000..0a03839943d3d493f29c34be93e4975bcc275bde
--- /dev/null
+++ b/REFERENCE.md
@@ -0,0 +1,1147 @@
+# Reference
+
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+### Classes
+
+#### Public Classes
+
+* [`postfix`](#postfix): The top-level class, to install and configure Postfix
+
+#### Private Classes
+
+* `postfix::augeas`: Provides augeas lenses for postfix files
+* `postfix::files`: Manages the postfix realted files
+* `postfix::ldap`: Provides the postfix ldap support
+* `postfix::mailman`: Configure postfix to work with mailman
+* `postfix::mta`: Configures postfix as minimal MTA
+* `postfix::packages`: Install the required packages for postfix
+* `postfix::params`: Default parameters
+* `postfix::satellite`: Configure postfix as satellite
+* `postfix::service`: Manage service resources for postfix
+
+### Defined types
+
+* [`postfix::canonical`](#postfixcanonical): Manage content of the postfix canonical map
+* [`postfix::conffile`](#postfixconffile): Manage a postfix configuration file
+* [`postfix::config`](#postfixconfig): Set values in postfix config file
+* [`postfix::hash`](#postfixhash): Creates Postfix hashed "map" files, and builds the corresponding db file
+* [`postfix::mailalias`](#postfixmailalias): Manage the content of the postfix alias map
+* [`postfix::map`](#postfixmap): Create a postfix map file
+* [`postfix::virtual`](#postfixvirtual): Manages the contents of the virtual map.
+
+## Classes
+
+### <a name="postfix"></a>`postfix`
+
+This class provides a basic setup of postfix with local and remote
+delivery and an SMTP server listening on the loopback interface.
+
+#### Examples
+
+##### Default postfix with listen address
+
+```puppet
+class { 'postfix':
+ smtp_listen => '192.168.1.10',
+}
+```
+
+##### Minimal MTA setup
+
+```puppet
+# This class configures a minimal MTA, delivering mail to
+# $mydestination. Either a valid relay host or the special
+# word 'direct' is required ($relayhost) for outbound email.
+#
+# transport & virtual maps get configured and can be populated with
+# postfix::transport and postfix::virtual
+#
+class { 'postfix':
+ relayhost => 'mail.example.com',
+ smtp_listen => '0.0.0.0',
+ mydestination => '$myorigin, myapp.example.com',
+ mta => true,
+}
+```
+
+##### Configure postfix as satellite
+
+```puppet
+# This configures all local email (cron, mdadm, etc) to be forwarded
+# to $root_mail_recipient, using $relayhost as a relay.
+#
+# This will call postfix::mta and override its parameters.
+# You shouldn't call postfix::mta yourself or use mta=true in the postfix class.
+class { 'postfix':
+ relayhost => 'mail.example.com',
+ myorigin => 'toto.example.com',
+ root_mail_recipient => 'the.sysadmin@example.com',
+ satellite => true,
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix` class:
+
+* [`alias_maps`](#alias_maps)
+* [`amavis_procs`](#amavis_procs)
+* [`chroot`](#chroot)
+* [`confdir`](#confdir)
+* [`conffiles`](#conffiles)
+* [`configs`](#configs)
+* [`hashes`](#hashes)
+* [`inet_interfaces`](#inet_interfaces)
+* [`inet_protocols`](#inet_protocols)
+* [`ldap`](#ldap)
+* [`ldap_base`](#ldap_base)
+* [`ldap_host`](#ldap_host)
+* [`ldap_options`](#ldap_options)
+* [`mail_user`](#mail_user)
+* [`mailman`](#mailman)
+* [`mailx_ensure`](#mailx_ensure)
+* [`maincf_source`](#maincf_source)
+* [`manage_aliases`](#manage_aliases)
+* [`manage_conffiles`](#manage_conffiles)
+* [`manage_mailname`](#manage_mailname)
+* [`manage_mailx`](#manage_mailx)
+* [`manage_root_alias`](#manage_root_alias)
+* [`maps`](#maps)
+* [`master_bounce_command`](#master_bounce_command)
+* [`master_defer_command`](#master_defer_command)
+* [`master_entries`](#master_entries)
+* [`master_smtp`](#master_smtp)
+* [`master_smtps`](#master_smtps)
+* [`master_submission`](#master_submission)
+* [`mastercf_content`](#mastercf_content)
+* [`mastercf_source`](#mastercf_source)
+* [`mastercf_template`](#mastercf_template)
+* [`masquerade_classes`](#masquerade_classes)
+* [`masquerade_domains`](#masquerade_domains)
+* [`masquerade_exceptions`](#masquerade_exceptions)
+* [`mta`](#mta)
+* [`mydestination`](#mydestination)
+* [`mynetworks`](#mynetworks)
+* [`myorigin`](#myorigin)
+* [`postfix_ensure`](#postfix_ensure)
+* [`relayhost`](#relayhost)
+* [`root_group`](#root_group)
+* [`root_mail_recipient`](#root_mail_recipient)
+* [`satellite`](#satellite)
+* [`service_enabled`](#service_enabled)
+* [`service_ensure`](#service_ensure)
+* [`smtp_listen`](#smtp_listen)
+* [`transports`](#transports)
+* [`use_amavisd`](#use_amavisd)
+* [`use_dovecot_lda`](#use_dovecot_lda)
+* [`use_schleuder`](#use_schleuder)
+* [`use_sympa`](#use_sympa)
+* [`virtuals`](#virtuals)
+
+##### <a name="alias_maps"></a>`alias_maps`
+
+Data type: `String`
+
+A string defining the location of the alias map file.
+Example: `hash:/etc/other_aliases`
+
+Default value: `'hash:/etc/aliases'`
+
+##### <a name="amavis_procs"></a>`amavis_procs`
+
+Data type: `Integer`
+
+Number of amavis scanner processes to spawn
+
+Default value: `2`
+
+##### <a name="chroot"></a>`chroot`
+
+Data type: `Optional[Boolean]`
+
+A boolean to define if postfix should be run in a chroot jail or not.
+If not defined, '-' is used (OS dependant)
+Example: `true`
+
+Default value: ``undef``
+
+##### <a name="confdir"></a>`confdir`
+
+Data type: `Stdlib::Absolutepath`
+
+The base path which should be used as confdir
+
+Default value: `'/etc/postfix'`
+
+##### <a name="conffiles"></a>`conffiles`
+
+Data type: `Hash`
+
+A hash of postfix::conffile resources
+
+Default value: `{}`
+
+##### <a name="configs"></a>`configs`
+
+Data type: `Hash`
+
+A hash of postfix::config resources. The hash containing optional configuration values for main.cf.
+The values are configured using postfix::config.
+Example: `{'message_size_limit': {'value': '51200000'}}`
+
+Default value: `{}`
+
+##### <a name="hashes"></a>`hashes`
+
+Data type: `Hash`
+
+A hash of postfix::hash resources
+
+Default value: `{}`
+
+##### <a name="inet_interfaces"></a>`inet_interfaces`
+
+Data type: `String`
+
+A string defining the network interfaces that Postfix will listen on.
+Example: `127.0.0.1, [::1]`
+
+Default value: `'all'`
+
+##### <a name="inet_protocols"></a>`inet_protocols`
+
+Data type: `String`
+
+A string defining the internet protocols that Postfix will use.
+Example: `ipv4`
+
+Default value: `'all'`
+
+##### <a name="ldap"></a>`ldap`
+
+Data type: `Boolean`
+
+A Boolean defining whether to configure Postfix for LDAP use.
+
+Default value: ``false``
+
+##### <a name="ldap_base"></a>`ldap_base`
+
+Data type: `Optional[String]`
+
+A string defining the LDAP search base to use. This parameter maps to the
+search_base parameter (ldap_table(5)).
+Example: `cn=Users,dc=example,dc=com`
+
+Default value: ``undef``
+
+##### <a name="ldap_host"></a>`ldap_host`
+
+Data type: `Optional[String]`
+
+A string defining the LDAP host. This parameter maps to the server_host parameter (ldap_table(5)).
+Example: `ldaps://ldap.example.com:636 ldap://ldap2.example.com`.
+
+Default value: ``undef``
+
+##### <a name="ldap_options"></a>`ldap_options`
+
+Data type: `Optional[String]`
+
+A free form string that can define any ldap options to be passed through (ldap_table(5)).
+Example: `start_tls = yes`.
+
+Default value: ``undef``
+
+##### <a name="mail_user"></a>`mail_user`
+
+Data type: `String`
+
+A string defining the mail user, and optionally group, to execute external commands as.
+This parameter maps to the user parameter (pipe(8)).
+Example: `vmail:vmail`.
+
+Default value: `'vmail'`
+
+##### <a name="mailman"></a>`mailman`
+
+Data type: `Boolean`
+
+A Boolean defining whether to configure a basic smtp server that is able to work for the
+mailman mailing list manager.
+
+Default value: ``false``
+
+##### <a name="mailx_ensure"></a>`mailx_ensure`
+
+Data type: `String`
+
+Installs mailx package
+
+Default value: `'present'`
+
+##### <a name="maincf_source"></a>`maincf_source`
+
+Data type: `String`
+
+A string defining the location of a skeleton main.cf file to be used. The default file
+supplied is blank. However, if the main.cf file already exists on the system the contents
+will **NOT** be replaced by the contents from maincf_source.
+Example: `puppet:///modules/some/other/location/main.cf`.
+
+Default value: `"puppet:///modules/${module_name}/main.cf"`
+
+##### <a name="manage_aliases"></a>`manage_aliases`
+
+Data type: `Boolean`
+
+Manage /etc/aliases file
+
+Default value: ``true``
+
+##### <a name="manage_conffiles"></a>`manage_conffiles`
+
+Data type: `Boolean`
+
+A Boolean defining whether the puppet module should replace the configuration files for postfix.
+This setting currently effects only the following files:
+- /etc/mailname
+- /etc/postfix/master.cf
+
+This setting does NOT effect the following files:
+- /etc/aliases
+- /etc/postfix/main.cf
+
+Default value: ``true``
+
+##### <a name="manage_mailname"></a>`manage_mailname`
+
+Data type: `Boolean`
+
+A Boolean defining whether the puppet module should manage '/etc/mailname'.
+See also $manage_conffiles
+
+Default value: ``true``
+
+##### <a name="manage_mailx"></a>`manage_mailx`
+
+Data type: `Boolean`
+
+A Boolean defining whether the puppet module should manage the mailx package. See also $mailx_ensure.
+
+Default value: ``true``
+
+##### <a name="manage_root_alias"></a>`manage_root_alias`
+
+Data type: `Boolean`
+
+Wheter to manage the mailalias for root user
+
+Default value: ``true``
+
+##### <a name="maps"></a>`maps`
+
+Data type: `Hash`
+
+A hash of postfix::map resources
+
+Default value: `{}`
+
+##### <a name="master_bounce_command"></a>`master_bounce_command`
+
+Data type: `String`
+
+The bounce command which should be used in master.cf
+
+Default value: `'bounce'`
+
+##### <a name="master_defer_command"></a>`master_defer_command`
+
+Data type: `String`
+
+The defer command which should be used in master.cf
+
+Default value: `'bounce'`
+
+##### <a name="master_entries"></a>`master_entries`
+
+Data type: `Array[String]`
+
+Array of strings containing additional entries for the /etc/postfix/master.cf file.
+Example: `['submission inet n - n - - smtpd']`.
+
+Default value: `[]`
+
+##### <a name="master_smtp"></a>`master_smtp`
+
+Data type: `Optional[String]`
+
+A string to define the smtp line in the /etc/postfix/master.cf file.
+If this is defined the smtp_listen parameter will be ignored.
+Example: `smtp inet n - n - - smtpd`.
+
+Default value: ``undef``
+
+##### <a name="master_smtps"></a>`master_smtps`
+
+Data type: `Optional[String]`
+
+A string to define the smtps line in the /etc/postfix/master.cf file.
+Example: `smtps inet n - n - - smtpd`.
+
+Default value: ``undef``
+
+##### <a name="master_submission"></a>`master_submission`
+
+Data type: `Optional[String]`
+
+A string to define the submission line in the /etc/postfix/master.cf file.
+Example: `submission inet n - n - - smtpd`.
+
+Default value: ``undef``
+
+##### <a name="mastercf_content"></a>`mastercf_content`
+
+Data type: `Optional[String]`
+
+Set the content parameter for the master.cf file resource.
+
+Default value: ``undef``
+
+##### <a name="mastercf_source"></a>`mastercf_source`
+
+Data type: `Optional[String]`
+
+A string defining the location of a skeleton master.cf file to be used.
+Example: `puppet:///modules/some/other/location/master.cf`.
+
+Default value: ``undef``
+
+##### <a name="mastercf_template"></a>`mastercf_template`
+
+Data type: `Optional[String]`
+
+Set the epp template path which will be used for master.cf file resource.
+
+Default value: ``undef``
+
+##### <a name="masquerade_classes"></a>`masquerade_classes`
+
+Data type: `Optional[Array[String[1]]]`
+
+Postfix config parameter masquerade_classes as an array.
+What addresses are subject to address masquerading.
+Example: `['envelope_sender', 'envelope_recipient', 'header_sender', 'header_recipient']`
+
+Default value: ``undef``
+
+##### <a name="masquerade_domains"></a>`masquerade_domains`
+
+Data type: `Optional[Array[String[1]]]`
+
+An array defining the masquerade_domains to use.
+The order of elements matters here, so be aware of how you define the elements.
+Example: `['foo.example.com', 'example.com']`
+
+Default value: ``undef``
+
+##### <a name="masquerade_exceptions"></a>`masquerade_exceptions`
+
+Data type: `Optional[Array[String[1]]]`
+
+An array defining the masquerade_exceptions to use. This optional list of user names that are not
+subjected to address masquerading, even when their addresses match $masquerade_domains.
+Example: `['root']`
+
+Default value: ``undef``
+
+##### <a name="mta"></a>`mta`
+
+Data type: `Boolean`
+
+A Boolean to define whether to configure Postfix as a mail transfer agent.
+This option is mutually exclusive with the satellite Boolean.
+
+Default value: ``false``
+
+##### <a name="mydestination"></a>`mydestination`
+
+Data type: `String`
+
+A string to define the mydestination parameter in main.cf (postconf(5)).
+Example: `example.com, foo.example.com`.
+
+Default value: `'$myorigin'`
+
+##### <a name="mynetworks"></a>`mynetworks`
+
+Data type: `String`
+
+A string to define the mynetworks parameter that holds trusted remote smtp clients (postconf(5)).
+Example: `127.0.0.0/8, [::1]/128`.
+
+Default value: `'127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128'`
+
+##### <a name="myorigin"></a>`myorigin`
+
+Data type: `String`
+
+A string to define the myorigin parameter that holds the domain name that mail appears to come from (postconf(5)).
+Example: `example.com`
+
+Default value: `$facts['networking']['fqdn']`
+
+##### <a name="postfix_ensure"></a>`postfix_ensure`
+
+Data type: `String`
+
+The ensure value of the postfix package
+
+Default value: `'present'`
+
+##### <a name="relayhost"></a>`relayhost`
+
+Data type: `Optional[String]`
+
+A string to define the relayhost parameter (postconf(5)).
+Example: `smtp.example.com`.
+
+Default value: ``undef``
+
+##### <a name="root_group"></a>`root_group`
+
+Data type: `String`
+
+The group permission name for the main.cf and master.cf files.
+
+Default value: `'root'`
+
+##### <a name="root_mail_recipient"></a>`root_mail_recipient`
+
+Data type: `Variant[Array[String], String]`
+
+A string to define the e-mail address to which all mail directed to root should go (aliases(5)).
+Example: `root_catch@example.com`.
+
+Default value: `'nobody'`
+
+##### <a name="satellite"></a>`satellite`
+
+Data type: `Boolean`
+
+A Boolean to define whether to configure postfix as a satellite relay host.
+This setting is mutually exclusive with the mta Boolean.
+
+Default value: ``false``
+
+##### <a name="service_enabled"></a>`service_enabled`
+
+Data type: `Boolean`
+
+Defines if the service 'postfix' is enabled on the system
+
+Default value: ``true``
+
+##### <a name="service_ensure"></a>`service_ensure`
+
+Data type: `String`
+
+Defines the service state of 'postfix' service
+
+Default value: `'running'`
+
+##### <a name="smtp_listen"></a>`smtp_listen`
+
+Data type: `Variant[Array[String[1]], String[1]]`
+
+A string or an array of strings to define the IPs on which to listen in master.cf.
+This can also be set to 'all' to listen on all interfaces. If master_smtp is defined
+smtp_listen will not be used.
+Example: `::1`.
+
+Default value: `'127.0.0.1'`
+
+##### <a name="transports"></a>`transports`
+
+Data type: `Hash`
+
+A hash of postfix::transport resources
+
+Default value: `{}`
+
+##### <a name="use_amavisd"></a>`use_amavisd`
+
+Data type: `Boolean`
+
+A Boolean to define whether to configure master.cf to allow the use of the amavisd scanner.
+
+Default value: ``false``
+
+##### <a name="use_dovecot_lda"></a>`use_dovecot_lda`
+
+Data type: `Boolean`
+
+A Boolean to define whether to configure master.cf to use dovecot as the local delivery agent.
+
+Default value: ``false``
+
+##### <a name="use_schleuder"></a>`use_schleuder`
+
+Data type: `Variant[Integer[2, 3], Boolean]`
+
+A Boolean to define whether to configure master.cf to use the Schleuder GPG-enabled mailing list.
+Can be also set to an integer `2` to use Schleuder v2 instead of v3.
+
+Default value: ``false``
+
+##### <a name="use_sympa"></a>`use_sympa`
+
+Data type: `Boolean`
+
+A Boolean to define whether to configure master.cf to use the Sympa mailing list management software.
+
+Default value: ``false``
+
+##### <a name="virtuals"></a>`virtuals`
+
+Data type: `Hash`
+
+A hash of postfix::virtual resources
+
+Default value: `{}`
+
+## Defined types
+
+### <a name="postfixcanonical"></a>`postfix::canonical`
+
+This type manages content of the /etc/postfix/canonical map.
+
+* **See also**
+ * https://www.postfix.org/canonical.5.html
+
+#### Examples
+
+##### Basic usage and required setup
+
+```puppet
+# This defined type requires the following resources:
+# - Class["postfix"]
+# - Postfix::Hash["/etc/postfix/canonical"]
+# - Postfix::Config["canonical_maps"] or Postfix::Config["sender_canonical_maps"] or Postfix::Config["recipient_canonical_maps"]
+include postfix
+postfix::hash { "/etc/postfix/recipient_canonical":
+ ensure => present,
+}
+postfix::config { "canonical_alias_maps":
+ value => "hash:/etc/postfix/recipient_canonical"
+}
+postfix::canonical {
+ "user@example.com":
+ file => "/etc/postfix/recipient_canonical",
+ ensure => present,
+ destination => "root";
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::canonical` defined type:
+
+* [`ensure`](#ensure)
+* [`destination`](#destination)
+* [`file`](#file)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present','absent']`
+
+Intended state of the resource
+
+Default value: `'present'`
+
+##### <a name="destination"></a>`destination`
+
+Data type: `String`
+
+Where the emails will be delivered to.
+
+##### <a name="file"></a>`file`
+
+Data type: `Stdlib::Absolutepath`
+
+Where to create the file. If not defined "${postfix::confdir}/canonical"
+will be used as path.
+
+Default value: ``undef``
+
+### <a name="postfixconffile"></a>`postfix::conffile`
+
+Manages postfix configuration files. With it, you could create configuration
+files (other than, main.cf, master.cf, etc.) restarting postfix when necessary.
+
+#### Examples
+
+##### Simple config file with module source
+
+```puppet
+postfix::conffile { 'ldapoptions.cf':
+ source => 'puppet:///modules/postfix/ldapoptions.cf',
+}
+```
+
+##### With template options
+
+```puppet
+postfix::conffile { 'ldapoptions.cf':
+ options => {
+ server_host => ldap.mydomain.com,
+ bind => 'yes',
+ bind_dn => 'cn=admin,dc=mydomain,dc=com',
+ bind_pw => 'password',
+ search_base => 'dc=example, dc=com',
+ query_filter => 'mail=%s',
+ result_attribute => 'uid',
+ }
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::conffile` defined type:
+
+* [`ensure`](#ensure)
+* [`source`](#source)
+* [`content`](#content)
+* [`path`](#path)
+* [`mode`](#mode)
+* [`options`](#options)
+* [`show_diff`](#show_diff)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent', 'directory']`
+
+A string whose valid values are present, absent or directory.
+
+Default value: `'present'`
+
+##### <a name="source"></a>`source`
+
+Data type: `Variant[Array[String], String, Undef]`
+
+A string with the source of the file. This is the `source` parameter of the underlying file resource.
+Example: `puppet:///modules/postfix/configfile.cf`
+
+Default value: ``undef``
+
+##### <a name="content"></a>`content`
+
+Data type: `Optional[String]`
+
+The content of the postfix configuration file. This is an alternative to the `source` parameter.
+If you don't provide `source` neither `content` parameters a default template is used and the
+content is created with values in the `options` hash.
+
+Default value: ``undef``
+
+##### <a name="path"></a>`path`
+
+Data type: `Optional[Stdlib::Absolutepath]`
+
+Where to create the file. If not defined "${postfix::confdir}/${name}" will be used as path.
+
+Default value: ``undef``
+
+##### <a name="mode"></a>`mode`
+
+Data type: `String`
+
+Permissions of the configuration file. This option is useful if you want to create the file with
+specific permissions (for example, because you have passwords in it).
+Example: `0640`
+
+Default value: `'0640'`
+
+##### <a name="options"></a>`options`
+
+Data type: `Hash`
+
+Hash with the options used in the default template that is used when neither `source`
+neither `content`parameters are provided.
+
+Default value: `{}`
+
+##### <a name="show_diff"></a>`show_diff`
+
+Data type: `Boolean`
+
+Switch to set file show_diff parameter
+
+Default value: ``true``
+
+### <a name="postfixconfig"></a>`postfix::config`
+
+Add/alter/remove options in Postfix main configuration file (main.cf).
+This uses Augeas to do the editing of the configuration file, as such any
+configuration value can be used.
+
+#### Examples
+
+##### Set value for smtp_use_tls
+
+```puppet
+postfix::config { 'smtp_use_tls':
+ ensure => 'present',
+ value => 'yes',
+}
+```
+
+##### Set a config parameter with empty value
+
+```puppet
+postfix::config { 'relayhost':
+ ensure => 'blank',
+}
+```
+
+##### Configure Postfix to use TLS as a client
+
+```puppet
+postfix::config {
+ 'smtp_tls_mandatory_ciphers': value => 'high';
+ 'smtp_tls_security_level': value => 'secure';
+ 'smtp_tls_CAfile': value => '/etc/pki/tls/certs/ca-bundle.crt';
+ 'smtp_tls_session_cache_database': value => 'btree:${data_directory}/smtp_tls_session_cache';
+}
+```
+
+##### Configure Postfix to disable the vrfy command
+
+```puppet
+postfix::config { 'disable_vrfy_command':
+ ensure => present,
+ value => 'yes',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::config` defined type:
+
+* [`ensure`](#ensure)
+* [`value`](#value)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent', 'blank']`
+
+Defines if the config parameter is present, absent or blank.
+The special value 'blank', will clear the value for the parameter,
+but will not remove it from the config file.
+Example: `blank`
+
+Default value: `'present'`
+
+##### <a name="value"></a>`value`
+
+Data type: `Optional[String]`
+
+A string that can contain any text to be used as the configuration value.
+Example: `btree:${data_directory}/smtp_tls_session_cache`.
+
+Default value: ``undef``
+
+### <a name="postfixhash"></a>`postfix::hash`
+
+Creates postfix hashed "map" files. It will create "${name}", and then build
+"${name}.db" using the "postmap" command. The map file can then be referred to
+using postfix::config.
+
+#### Examples
+
+##### Creates a virtual hashmap
+
+```puppet
+# This example creates a virtual hashmap in the postfix config dir
+# and adds a value into it with the postfix::config type.
+postfix::hash { 'virtual':
+ ensure => present,
+}
+postfix::config { 'virtual_alias_maps':
+ value => 'hash:/etc/postfix/virtual',
+}
+```
+
+##### Create a sasl_passwd hash from a source file
+
+```puppet
+postfix::hash { '/etc/postfix/sasl_passwd':
+ ensure => 'present',
+ source => 'puppet:///modules/profile/postfix/client/sasl_passwd',
+}
+```
+
+##### Create a sasl_passwd hash with contents defined in the manifest
+
+```puppet
+postfix::hash { '/etc/postfix/sasl_passwd':
+ ensure => 'present',
+ content => '#Destination Credentials\nsmtp.example.com gssapi:nopassword',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::hash` defined type:
+
+* [`ensure`](#ensure)
+* [`source`](#source)
+* [`content`](#content)
+* [`mode`](#mode)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent']`
+
+Defines whether the hash map file is present or not. Value can either be present or absent.
+Example: `absent`.
+
+Default value: `'present'`
+
+##### <a name="source"></a>`source`
+
+Data type: `Variant[Array[String], String, Undef]`
+
+A string whose value is a location for the source file to be used. This parameter is mutually
+exclusive with the content parameter, one or the other must be present, but both cannot be present.
+Example: `puppet:///modules/some/location/sasl_passwd`.
+
+Default value: ``undef``
+
+##### <a name="content"></a>`content`
+
+Data type: `Optional[Variant[Sensitive[String],String]]`
+
+A free form string that defines the contents of the file. This parameter is mutually exclusive
+with the source parameter.
+Example: `#Destination Credentials\nsmtp.example.com gssapi:nopassword`.
+
+Default value: ``undef``
+
+##### <a name="mode"></a>`mode`
+
+Data type: `Variant[String[4,4], Undef]`
+
+
+
+Default value: `'0640'`
+
+### <a name="postfixmailalias"></a>`postfix::mailalias`
+
+Creates an email alias in the local alias database and updates the binary
+version of said database.
+
+* **See also**
+ * http://www.postfix.org/aliases.5.html
+
+#### Examples
+
+##### Simple example
+
+```puppet
+include postfix
+postfix::mailalias { 'postmaster':
+ ensure => present,
+ recipient => 'foo',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::mailalias` defined type:
+
+* [`ensure`](#ensure)
+* [`recipient`](#recipient)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent']`
+
+Intended state of the resource
+
+Default value: `'present'`
+
+##### <a name="recipient"></a>`recipient`
+
+Data type: `Variant[String, Array[String]]`
+
+The recipient address where the mail should be sent to.
+
+### <a name="postfixmap"></a>`postfix::map`
+
+Creates postfix "map" files. It will create "${name}", and then build
+"${name}.db" using the "postmap" command. The map file can then be referred to
+using postfix::config.
+
+* **See also**
+ * http://www.postfix.org/postmap.1.html
+
+#### Examples
+
+##### Postfix map file and use in config
+
+```puppet
+postfix::map { '/etc/postfix/virtual':
+ ensure => present,
+}
+postfix::config { 'virtual_alias_maps':
+ value => 'hash:/etc/postfix/virtual',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::map` defined type:
+
+* [`ensure`](#ensure)
+* [`source`](#source)
+* [`content`](#content)
+* [`type`](#type)
+* [`path`](#path)
+* [`mode`](#mode)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent']`
+
+Intended state of the resource
+
+Default value: `'present'`
+
+##### <a name="source"></a>`source`
+
+Data type: `Optional[Variant[Array[String], String]]`
+
+Sets the value of the source parameter for the file. Can't be used
+together with parameter content.
+
+Default value: ``undef``
+
+##### <a name="content"></a>`content`
+
+Data type: `Optional[Variant[Sensitive[String], String]]`
+
+The content of the file. Can't be used together with param source.
+
+Default value: ``undef``
+
+##### <a name="type"></a>`type`
+
+Data type: `String[1]`
+
+Type of the postfix map (valid values are cidr, pcre, hash...)
+
+Default value: `'hash'`
+
+##### <a name="path"></a>`path`
+
+Data type: `Optional[Stdlib::Absolutepath]`
+
+Where to create the file. If not defined "${postfix::confdir}/${name}"
+will be used as path.
+
+Default value: ``undef``
+
+##### <a name="mode"></a>`mode`
+
+Data type: `String[4,4]`
+
+File mode of the created file.
+
+Default value: `'0640'`
+
+### <a name="postfixvirtual"></a>`postfix::virtual`
+
+Manages content of the /etc/postfix/virtual map.
+
+* **See also**
+ * https://www.postfix.org/virtual.8.html
+
+#### Examples
+
+##### Minimum Requirements
+
+```puppet
+include postfix
+postfix::hash { "/etc/postfix/virtual":
+ ensure => present,
+}
+postfix::config { "virtual_alias_maps":
+ value => "hash:/etc/postfix/virtual, regexp:/etc/postfix/virtual_regexp"
+}
+```
+
+##### Route mail to local users
+
+```puppet
+postfix::virtual { "user@example.com":
+ ensure => present,
+ destination => ['root', 'postmaster'],
+}
+```
+
+##### Regex example
+
+```puppet
+postfix::virtual { "/.+@.+/"
+ ensure => present,
+ file => '/etc/postfix/virtual_regexp',
+ destination => 'root',
+}
+```
+
+##### Route mail bound for 'user@example.com' to root.
+
+```puppet
+postfix::virtual {'user@example.com':
+ ensure => present,
+ destination => 'root',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `postfix::virtual` defined type:
+
+* [`ensure`](#ensure)
+* [`destination`](#destination)
+* [`file`](#file)
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent']`
+
+A string whose valid values are present or absent.
+
+Default value: `'present'`
+
+##### <a name="destination"></a>`destination`
+
+Data type: `Variant[String, Array[String]]`
+
+A string defining where the e-mails will be delivered to, (virtual(8)).
+Example: `root`
+
+##### <a name="file"></a>`file`
+
+Data type: `Optional[Stdlib::Absolutepath]`
+
+A string defining the location of the virtual map, pre hash.
+If not defined "${postfix::confdir}/virtual" will be used as path.
+Example: `/etc/postfix/my_virtual_map`.
+
+Default value: ``undef``
+
diff --git a/manifests/augeas.pp b/manifests/augeas.pp
index 762d48fc458aa34de1b5b79699e1f63c93e32bb2..f97b5655c9d921e380d55a760cd1e60bf84f1705 100644
--- a/manifests/augeas.pp
+++ b/manifests/augeas.pp
@@ -1,7 +1,12 @@
-#class postfix::augeas
-# This class provides the augeas lenses used by the postfix class
+# @summary Provides augeas lenses for postfix files
+#
+# This class provides the augeas lenses used by the postfix class
+#
+# @api private
#
class postfix::augeas {
+ assert_private()
+
$module_path = get_module_path($module_name)
augeas::lens { 'postfix_transport':
ensure => present,
diff --git a/manifests/canonical.pp b/manifests/canonical.pp
index 6528ed9d5a90afb54bf19344ff68bb1383490b47..fbb2763cccb132fda89ea1919683a1e775a475ca 100644
--- a/manifests/canonical.pp
+++ b/manifests/canonical.pp
@@ -1,42 +1,42 @@
-#== Definition: postfix::canonical
+# @summary Manage content of the postfix canonical map
#
-#Manages content of the /etc/postfix/canonical map.
+# This type manages content of the /etc/postfix/canonical map.
#
-#Parameters:
-#- *name*: name of address postfix will lookup. See canonical(5).
-#- *destination*: where the emails will be delivered to. See canonical(5).
-#- *ensure*: present/absent, defaults to present.
+# @example Basic usage and required setup
+# # This defined type requires the following resources:
+# # - Class["postfix"]
+# # - Postfix::Hash["/etc/postfix/canonical"]
+# # - Postfix::Config["canonical_maps"] or Postfix::Config["sender_canonical_maps"] or Postfix::Config["recipient_canonical_maps"]
+# include postfix
+# postfix::hash { "/etc/postfix/recipient_canonical":
+# ensure => present,
+# }
+# postfix::config { "canonical_alias_maps":
+# value => "hash:/etc/postfix/recipient_canonical"
+# }
+# postfix::canonical {
+# "user@example.com":
+# file => "/etc/postfix/recipient_canonical",
+# ensure => present,
+# destination => "root";
+# }
#
-#Requires:
-#- Class["postfix"]
-#- Postfix::Hash["/etc/postfix/canonical"]
-#- Postfix::Config["canonical_maps"] or Postfix::Config["sender_canonical_maps"] or Postfix::Config["recipient_canonical_maps"]
-#- augeas
+# @param ensure
+# Intended state of the resource
#
-#Example usage:
+# @param destination
+# Where the emails will be delivered to.
#
-# node "toto.example.com" {
+# @param file
+# Where to create the file. If not defined "${postfix::confdir}/canonical"
+# will be used as path.
#
-# include postfix
-#
-# postfix::hash { "/etc/postfix/recipient_canonical":
-# ensure => present,
-# }
-# postfix::config { "canonical_alias_maps":
-# value => "hash:/etc/postfix/recipient_canonical"
-# }
-# postfix::canonical {
-# "user@example.com":
-# file => "/etc/postfix/recipient_canonical",
-# ensure => present,
-# destination => "root";
-# }
-# }
+# @see https://www.postfix.org/canonical.5.html
#
define postfix::canonical (
- $destination,
- $file=undef,
- $ensure='present'
+ String $destination,
+ Enum['present','absent'] $ensure = 'present',
+ Stdlib::Absolutepath $file = undef
) {
include postfix
include postfix::augeas
diff --git a/manifests/conffile.pp b/manifests/conffile.pp
index cb977650beec55bcd88ac8f81d013ecdb2d17b52..38642bad97b6191aad5166731d67700a647ef70d 100644
--- a/manifests/conffile.pp
+++ b/manifests/conffile.pp
@@ -1,50 +1,52 @@
-# = Define: postfix::conffile
+# @summary Manage a postfix configuration file
#
-# Adds a postfix configuration file.
-# It is mainly a file resource that also restarts postfix
+# Manages postfix configuration files. With it, you could create configuration
+# files (other than, main.cf, master.cf, etc.) restarting postfix when necessary.
#
-# == Parameters
-#
-# [*ensure*]
-# Ensure parameter for the file resource. Defaults to 'present'
+# @example Simple config file with module source
+# postfix::conffile { 'ldapoptions.cf':
+# source => 'puppet:///modules/postfix/ldapoptions.cf',
+# }
#
-# [*source*]
-# Sets the value of the source parameter for the file
+# @example With template options
+# postfix::conffile { 'ldapoptions.cf':
+# options => {
+# server_host => ldap.mydomain.com,
+# bind => 'yes',
+# bind_dn => 'cn=admin,dc=mydomain,dc=com',
+# bind_pw => 'password',
+# search_base => 'dc=example, dc=com',
+# query_filter => 'mail=%s',
+# result_attribute => 'uid',
+# }
+# }
#
-# [*content*]
-# Sets the content of the postfix config file
-# Note: This option is alternative to the source one
+# @param ensure
+# A string whose valid values are present, absent or directory.
#
-# [*path*]
-# Where to create the file.
-# Defaults to "/etc/postfix/${name}".
+# @param source
+# A string with the source of the file. This is the `source` parameter of the underlying file resource.
+# Example: `puppet:///modules/postfix/configfile.cf`
#
-# [*mode*]
-# The file permissions of the file.
-# Defaults to 0640
+# @param content
+# The content of the postfix configuration file. This is an alternative to the `source` parameter.
+# If you don't provide `source` neither `content` parameters a default template is used and the
+# content is created with values in the `options` hash.
#
-# [*options*]
-# Hash with options to use in the template
+# @param path
+# Where to create the file. If not defined "${postfix::confdir}/${name}" will be used as path.
#
-# [*show_diff*]
-# Boolean that sets File show_diff parameter
+# @param mode
+# Permissions of the configuration file. This option is useful if you want to create the file with
+# specific permissions (for example, because you have passwords in it).
+# Example: `0640`
#
-# == Usage:
-# postfix::conffile { 'ldapoptions.cf':
-# options => {
-# server_host => <ldapserver>,
-# bind => 'yes',
-# bind_dn => <bind_dn>,
-# bind_pw => <bind_pw>,
-# search_base => 'dc=example, dc=com',
-# query_filter => 'mail=%s',
-# result_attribute => 'uid',
-# }
-# }
+# @param options
+# Hash with the options used in the default template that is used when neither `source`
+# neither `content`parameters are provided.
#
-# postfix::conffile { 'ldapoptions.cf':
-# source => 'puppet:///modules/postfix/ldapoptions.cf',
-# }
+# @param show_diff
+# Switch to set file show_diff parameter
#
define postfix::conffile (
Enum['present', 'absent', 'directory'] $ensure = 'present',
diff --git a/manifests/config.pp b/manifests/config.pp
index 3c550aa5d1b6ef4e87f26fd36cc566758cee789d..75b933c6591b4f961e128dc064d15fa20e63a175 100644
--- a/manifests/config.pp
+++ b/manifests/config.pp
@@ -1,32 +1,44 @@
+# @summary Set values in postfix config file
#
-# == Definition: postfix::config
-#
-# Uses Augeas to add/alter/remove options in postfix main
-# configuation file (/etc/postfix/main.cf).
-#
-# TODO: make this a type with an Augeas and a postconf providers.
-#
-# === Parameters
-#
-# [*name*] - name of the parameter.
-# [*ensure*] - present/absent/blank. defaults to present.
-# [*value*] - value of the parameter.
-#
-# === Requires
-#
-# - Class["postfix"]
-#
-# === Examples
+# Add/alter/remove options in Postfix main configuration file (main.cf).
+# This uses Augeas to do the editing of the configuration file, as such any
+# configuration value can be used.
#
+# @example Set value for smtp_use_tls
# postfix::config { 'smtp_use_tls':
# ensure => 'present',
# value => 'yes',
# }
#
+# @example Set a config parameter with empty value
# postfix::config { 'relayhost':
# ensure => 'blank',
# }
#
+# @example Configure Postfix to use TLS as a client
+# postfix::config {
+# 'smtp_tls_mandatory_ciphers': value => 'high';
+# 'smtp_tls_security_level': value => 'secure';
+# 'smtp_tls_CAfile': value => '/etc/pki/tls/certs/ca-bundle.crt';
+# 'smtp_tls_session_cache_database': value => 'btree:${data_directory}/smtp_tls_session_cache';
+# }
+#
+# @example Configure Postfix to disable the vrfy command
+# postfix::config { 'disable_vrfy_command':
+# ensure => present,
+# value => 'yes',
+# }
+#
+# @param ensure
+# Defines if the config parameter is present, absent or blank.
+# The special value 'blank', will clear the value for the parameter,
+# but will not remove it from the config file.
+# Example: `blank`
+#
+# @param value
+# A string that can contain any text to be used as the configuration value.
+# Example: `btree:${data_directory}/smtp_tls_session_cache`.
+#
define postfix::config (
Optional[String] $value = undef,
Enum['present', 'absent', 'blank'] $ensure = 'present',
@@ -58,6 +70,7 @@ define postfix::config (
}
}
+ # TODO: make this a type with an Augeas and a postconf providers.
augeas { "manage postfix '${title}'":
incl => "${postfix::confdir}/main.cf",
lens => 'Postfix_Main.lns',
diff --git a/manifests/files.pp b/manifests/files.pp
index 7bd97f568de3148b6efd608693359b53d5078489..39a9d8cdf6c144cd121eb8b89d5bc549c55e1106 100644
--- a/manifests/files.pp
+++ b/manifests/files.pp
@@ -1,3 +1,7 @@
+# @summary Manages the postfix realted files
+#
+# @api private
+#
class postfix::files {
assert_private()
diff --git a/manifests/hash.pp b/manifests/hash.pp
index 21c432369045c9a65688940da9313ad468198677..9bb17a81fb02f7d6d126d9d5b452a103b45ca4f9 100644
--- a/manifests/hash.pp
+++ b/manifests/hash.pp
@@ -1,22 +1,12 @@
-# == Definition: postfix::hash
+# @summary Creates Postfix hashed "map" files, and builds the corresponding db file
#
# Creates postfix hashed "map" files. It will create "${name}", and then build
# "${name}.db" using the "postmap" command. The map file can then be referred to
# using postfix::config.
#
-# === Parameters
-#
-# [*name*] - the name of the map file.
-# [*ensure*] - present/absent, defaults to present.
-# [*source*] - file source. Mutially exclusive with "content".
-# [*content*] - content of the file. Mutially exclusive with "source".
-#
-# === Requires
-#
-# - Class["postfix"]
-#
-# === Examples
-#
+# @example Creates a virtual hashmap
+# # This example creates a virtual hashmap in the postfix config dir
+# # and adds a value into it with the postfix::config type.
# postfix::hash { 'virtual':
# ensure => present,
# }
@@ -24,11 +14,37 @@
# value => 'hash:/etc/postfix/virtual',
# }
#
+# @example Create a sasl_passwd hash from a source file
+# postfix::hash { '/etc/postfix/sasl_passwd':
+# ensure => 'present',
+# source => 'puppet:///modules/profile/postfix/client/sasl_passwd',
+# }
+#
+# @example Create a sasl_passwd hash with contents defined in the manifest
+# postfix::hash { '/etc/postfix/sasl_passwd':
+# ensure => 'present',
+# content => '#Destination Credentials\nsmtp.example.com gssapi:nopassword',
+# }
+#
+# @param ensure
+# Defines whether the hash map file is present or not. Value can either be present or absent.
+# Example: `absent`.
+#
+# @param source
+# A string whose value is a location for the source file to be used. This parameter is mutually
+# exclusive with the content parameter, one or the other must be present, but both cannot be present.
+# Example: `puppet:///modules/some/location/sasl_passwd`.
+#
+# @param content
+# A free form string that defines the contents of the file. This parameter is mutually exclusive
+# with the source parameter.
+# Example: `#Destination Credentials\nsmtp.example.com gssapi:nopassword`.
+#
define postfix::hash (
- Enum['present', 'absent'] $ensure='present',
- Variant[Array[String], String, Undef] $source=undef,
+ Enum['present', 'absent'] $ensure = 'present',
+ Variant[Array[String], String, Undef] $source = undef,
Optional[Variant[Sensitive[String],String]] $content = undef,
- Variant[String[4,4], Undef] $mode='0640',
+ Variant[String[4,4], Undef] $mode = '0640',
) {
include postfix::params
diff --git a/manifests/init.pp b/manifests/init.pp
index 660f0bbb9cd0d140a0348327bedfcfa19e24aa88..70fb03f6ac061f44cf1e3296380a2dc9ce13be32 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -1,169 +1,303 @@
-#
-# == Class: postfix
+# @summary The top-level class, to install and configure Postfix
#
# This class provides a basic setup of postfix with local and remote
# delivery and an SMTP server listening on the loopback interface.
#
-# === Parameters
+# @example Default postfix with listen address
+# class { 'postfix':
+# smtp_listen => '192.168.1.10',
+# }
#
-# [*alias_maps*] - (string)
+# @example Minimal MTA setup
+# # This class configures a minimal MTA, delivering mail to
+# # $mydestination. Either a valid relay host or the special
+# # word 'direct' is required ($relayhost) for outbound email.
+# #
+# # transport & virtual maps get configured and can be populated with
+# # postfix::transport and postfix::virtual
+# #
+# class { 'postfix':
+# relayhost => 'mail.example.com',
+# smtp_listen => '0.0.0.0',
+# mydestination => '$myorigin, myapp.example.com',
+# mta => true,
+# }
#
-# [*configs*] - (hash)
+# @example Configure postfix as satellite
+# # This configures all local email (cron, mdadm, etc) to be forwarded
+# # to $root_mail_recipient, using $relayhost as a relay.
+# #
+# # This will call postfix::mta and override its parameters.
+# # You shouldn't call postfix::mta yourself or use mta=true in the postfix class.
+# class { 'postfix':
+# relayhost => 'mail.example.com',
+# myorigin => 'toto.example.com',
+# root_mail_recipient => 'the.sysadmin@example.com',
+# satellite => true,
+# }
#
-# [*hashes*] - (hash) A hash of postfix::hash resources
+# @param alias_maps
+# A string defining the location of the alias map file.
+# Example: `hash:/etc/other_aliases`
#
-# [*transports*] - (hash) A hash of postfix::transport resources
+# @param amavis_procs
+# Number of amavis scanner processes to spawn
#
-# [*virtuals*] - (hash) A hash of postfix::virtual resources
+# @param chroot
+# A boolean to define if postfix should be run in a chroot jail or not.
+# If not defined, '-' is used (OS dependant)
+# Example: `true`
#
-# [*conffiles*] - (hash) A hash of postfix::conffile resources
+# @param confdir
+# The base path which should be used as confdir
#
-# [*maps*] - (hash) A hash of postfix::map resources
+# @param conffiles
+# A hash of postfix::conffile resources
#
-# [*amavis_procs*] - (integer) Number of amavis scanners to spawn
+# @param configs
+# A hash of postfix::config resources. The hash containing optional configuration values for main.cf.
+# The values are configured using postfix::config.
+# Example: `{'message_size_limit': {'value': '51200000'}}`
#
-# [*inet_interfaces*] - (string)
+# @param hashes
+# A hash of postfix::hash resources
#
-# [*inet_protocols*] - (string)
+# @param inet_interfaces
+# A string defining the network interfaces that Postfix will listen on.
+# Example: `127.0.0.1, [::1]`
#
-# [*ldap*] - (boolean) Whether to use LDAP
+# @param inet_protocols
+# A string defining the internet protocols that Postfix will use.
+# Example: `ipv4`
#
-# [*ldap_base*] - (string)
+# @param ldap
+# A Boolean defining whether to configure Postfix for LDAP use.
#
-# [*ldap_host*] - (string)
+# @param ldap_base
+# A string defining the LDAP search base to use. This parameter maps to the
+# search_base parameter (ldap_table(5)).
+# Example: `cn=Users,dc=example,dc=com`
#
-# [*ldap_options*] - (string)
+# @param ldap_host
+# A string defining the LDAP host. This parameter maps to the server_host parameter (ldap_table(5)).
+# Example: `ldaps://ldap.example.com:636 ldap://ldap2.example.com`.
#
-# [*mail_user*] - (string) The mail user
+# @param ldap_options
+# A free form string that can define any ldap options to be passed through (ldap_table(5)).
+# Example: `start_tls = yes`.
#
-# [*mailman*] - (boolean)
+# @param mail_user
+# A string defining the mail user, and optionally group, to execute external commands as.
+# This parameter maps to the user parameter (pipe(8)).
+# Example: `vmail:vmail`.
#
-# [*maincf_source*] - (string)
+# @param mailman
+# A Boolean defining whether to configure a basic smtp server that is able to work for the
+# mailman mailing list manager.
#
-# [*manage_conffiles*] - (boolean) Whether config files are to be replaced
+# @param mailx_ensure
+# Installs mailx package
#
-# [*manage_mailname*] - (boolean) Whether to manage /etc/mailname.
+# @param maincf_source
+# A string defining the location of a skeleton main.cf file to be used. The default file
+# supplied is blank. However, if the main.cf file already exists on the system the contents
+# will **NOT** be replaced by the contents from maincf_source.
+# Example: `puppet:///modules/some/other/location/main.cf`.
#
-# [*manage_mailx*] - (boolean) Whether to manage mailx package.
+# @param manage_aliases
+# Manage /etc/aliases file
#
-# [*masquerade_classes*] - (array)
+# @param manage_conffiles
+# A Boolean defining whether the puppet module should replace the configuration files for postfix.
+# This setting currently effects only the following files:
+# - /etc/mailname
+# - /etc/postfix/master.cf
#
-# [*masquerade_domains*] - (array)
+# This setting does NOT effect the following files:
+# - /etc/aliases
+# - /etc/postfix/main.cf
#
-# [*masquerade_exceptions*] - (array)
+# @param manage_mailname
+# A Boolean defining whether the puppet module should manage '/etc/mailname'.
+# See also $manage_conffiles
#
-# [*mastercf_source*] - (string)
+# @param manage_mailx
+# A Boolean defining whether the puppet module should manage the mailx package. See also $mailx_ensure.
#
-# [*mastercf_content*] - (string)
+# @param manage_root_alias
+# Wheter to manage the mailalias for root user
#
-# [*mastercf_template*] - (string)
+# @param maps
+# A hash of postfix::map resources
#
-# [*master_smtp*] - (string)
+# @param master_bounce_command
+# The bounce command which should be used in master.cf
#
-# [*master_smtps*] - (string)
+# @param master_defer_command
+# The defer command which should be used in master.cf
#
-# [*master_submission*] - (string)
+# @param master_entries
+# Array of strings containing additional entries for the /etc/postfix/master.cf file.
+# Example: `['submission inet n - n - - smtpd']`.
#
-# [*master_entries*] - (array of strings)
+# @param master_smtp
+# A string to define the smtp line in the /etc/postfix/master.cf file.
+# If this is defined the smtp_listen parameter will be ignored.
+# Example: `smtp inet n - n - - smtpd`.
#
-# [*master_bounce_command*] - (string)
+# @param master_smtps
+# A string to define the smtps line in the /etc/postfix/master.cf file.
+# Example: `smtps inet n - n - - smtpd`.
#
-# [*master_defer_command*] - (string)
+# @param master_submission
+# A string to define the submission line in the /etc/postfix/master.cf file.
+# Example: `submission inet n - n - - smtpd`.
#
-# [*mta*] - (boolean) Configure postfix minimally, as a simple MTA
+# @param mastercf_content
+# Set the content parameter for the master.cf file resource.
#
-# [*mydestination*] - (string)
+# @param mastercf_source
+# A string defining the location of a skeleton master.cf file to be used.
+# Example: `puppet:///modules/some/other/location/master.cf`.
#
-# [*mynetworks*] - (string)
+# @param mastercf_template
+# Set the epp template path which will be used for master.cf file resource.
#
-# [*myorigin*] - (string)
+# @param masquerade_classes
+# Postfix config parameter masquerade_classes as an array.
+# What addresses are subject to address masquerading.
+# Example: `['envelope_sender', 'envelope_recipient', 'header_sender', 'header_recipient']`
#
-# [*manage_aliases*] - (boolean) Manage /etc/aliases file
#
-# [*relayhost*] - (string)
+# @param masquerade_domains
+# An array defining the masquerade_domains to use.
+# The order of elements matters here, so be aware of how you define the elements.
+# Example: `['foo.example.com', 'example.com']`
#
-# [*root_mail_recipient*] - (string)
+# @param masquerade_exceptions
+# An array defining the masquerade_exceptions to use. This optional list of user names that are not
+# subjected to address masquerading, even when their addresses match $masquerade_domains.
+# Example: `['root']`
#
-# [*chroot*] - (undef/boolean) Whether postfix should be run in a chroot
+# @param mta
+# A Boolean to define whether to configure Postfix as a mail transfer agent.
+# This option is mutually exclusive with the satellite Boolean.
#
-# [*satellite*] - (boolean) Whether to use as a satellite
-# (implies MTA)
+# @param mydestination
+# A string to define the mydestination parameter in main.cf (postconf(5)).
+# Example: `example.com, foo.example.com`.
#
-# [*smtp_listen*] - (string) The SMTP listen interface
+# @param mynetworks
+# A string to define the mynetworks parameter that holds trusted remote smtp clients (postconf(5)).
+# Example: `127.0.0.0/8, [::1]/128`.
#
-# [*use_amavisd*] - (boolean) Whether to setup for Amavis
+# @param myorigin
+# A string to define the myorigin parameter that holds the domain name that mail appears to come from (postconf(5)).
+# Example: `example.com`
#
-# [*use_dovecot_lda*] - (boolean) Whether to setup for Dovecot LDA
+# @param postfix_ensure
+# The ensure value of the postfix package
#
-# [*use_schleuder*] - (2/boolean) Whether to setup for Schleuder
-# (2 -> Schleuder 2, 3 or true -> Schleuder 3)
+# @param relayhost
+# A string to define the relayhost parameter (postconf(5)).
+# Example: `smtp.example.com`.
#
-# [*use_sympa*] - (boolean) Whether to setup for Sympa
+# @param root_group
+# The group permission name for the main.cf and master.cf files.
#
-# [*postfix_ensure*] - (string) The ensure value of the postfix package
+# @param root_mail_recipient
+# A string to define the e-mail address to which all mail directed to root should go (aliases(5)).
+# Example: `root_catch@example.com`.
#
-# [*mailx_ensure*] - (string) The ensure value of the mailx package
+# @param satellite
+# A Boolean to define whether to configure postfix as a satellite relay host.
+# This setting is mutually exclusive with the mta Boolean.
#
-# === Examples
+# @param service_enabled
+# Defines if the service 'postfix' is enabled on the system
#
-# class { 'postfix':
-# smtp_listen => '192.168.1.10',
-# }
+# @param service_ensure
+# Defines the service state of 'postfix' service
+#
+# @param smtp_listen
+# A string or an array of strings to define the IPs on which to listen in master.cf.
+# This can also be set to 'all' to listen on all interfaces. If master_smtp is defined
+# smtp_listen will not be used.
+# Example: `::1`.
+#
+# @param transports
+# A hash of postfix::transport resources
+#
+# @param use_amavisd
+# A Boolean to define whether to configure master.cf to allow the use of the amavisd scanner.
+#
+# @param use_dovecot_lda
+# A Boolean to define whether to configure master.cf to use dovecot as the local delivery agent.
+#
+# @param use_schleuder
+# A Boolean to define whether to configure master.cf to use the Schleuder GPG-enabled mailing list.
+# Can be also set to an integer `2` to use Schleuder v2 instead of v3.
+#
+# @param use_sympa
+# A Boolean to define whether to configure master.cf to use the Sympa mailing list management software.
+#
+# @param virtuals
+# A hash of postfix::virtual resources
#
class postfix (
- Stdlib::Absolutepath $confdir = '/etc/postfix',
- String $root_group = 'root',
- String $alias_maps = 'hash:/etc/aliases',
- Hash $configs = {},
- Hash $hashes = {},
- Hash $transports = {},
- Hash $virtuals = {},
- Hash $conffiles = {},
- Hash $maps = {},
- Integer $amavis_procs = 2,
- String $inet_interfaces = 'all',
- String $inet_protocols = 'all',
- Boolean $ldap = false,
- Optional[String] $ldap_base = undef,
- Optional[String] $ldap_host = undef,
- Optional[String] $ldap_options = undef,
- String $mail_user = 'vmail', # postfix_mail_user
- Boolean $mailman = false,
- String $maincf_source = "puppet:///modules/${module_name}/main.cf",
- Boolean $manage_conffiles = true,
- Boolean $manage_mailname = true,
- Boolean $manage_mailx = true,
- Optional[Array[String[1]]] $masquerade_classes = undef,
- Optional[Array[String[1]]] $masquerade_domains = undef,
- Optional[Array[String[1]]] $masquerade_exceptions = undef,
- Optional[String] $mastercf_source = undef,
- Optional[String] $mastercf_content = undef,
- Optional[String] $mastercf_template = undef,
- Optional[String] $master_smtp = undef, # postfix_master_smtp
- Optional[String] $master_smtps = undef, # postfix_master_smtps
- Optional[String] $master_submission = undef, # postfix_master_submission
- Array[String] $master_entries = [], # postfix_master_entries
- String $master_bounce_command = 'bounce',
- String $master_defer_command = 'bounce',
- Boolean $mta = false,
- String $mydestination = '$myorigin', # postfix_mydestination
- String $mynetworks = '127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128', # postfix_mynetworks
- String $myorigin = $facts['networking']['fqdn'],
- Boolean $manage_aliases = true, # /etc/aliases
- Optional[String] $relayhost = undef, # postfix_relayhost
- Boolean $manage_root_alias = true,
- Variant[Array[String], String] $root_mail_recipient = 'nobody', # root_mail_recipient
- Optional[Boolean] $chroot = undef,
- Boolean $satellite = false,
- Variant[Array[String[1]], String[1]] $smtp_listen = '127.0.0.1', # postfix_smtp_listen
- Boolean $use_amavisd = false, # postfix_use_amavisd
- Boolean $use_dovecot_lda = false, # postfix_use_dovecot_lda
- Variant[Integer[2, 3], Boolean] $use_schleuder = false, # postfix_use_schleuder
- Boolean $use_sympa = false, # postfix_use_sympa
- String $postfix_ensure = 'present',
- String $mailx_ensure = 'present',
- String $service_ensure = 'running',
- Boolean $service_enabled = true,
+ String $alias_maps = 'hash:/etc/aliases',
+ Integer $amavis_procs = 2,
+ Optional[Boolean] $chroot = undef,
+ Stdlib::Absolutepath $confdir = '/etc/postfix',
+ Hash $conffiles = {},
+ Hash $configs = {},
+ Hash $hashes = {},
+ String $inet_interfaces = 'all',
+ String $inet_protocols = 'all',
+ Boolean $ldap = false,
+ Optional[String] $ldap_base = undef,
+ Optional[String] $ldap_host = undef,
+ Optional[String] $ldap_options = undef,
+ String $mail_user = 'vmail', # postfix_mail_user
+ Boolean $mailman = false,
+ String $mailx_ensure = 'present',
+ String $maincf_source = "puppet:///modules/${module_name}/main.cf",
+ Boolean $manage_aliases = true, # /etc/aliases
+ Boolean $manage_conffiles = true,
+ Boolean $manage_mailname = true,
+ Boolean $manage_mailx = true,
+ Boolean $manage_root_alias = true,
+ Hash $maps = {},
+ String $master_bounce_command = 'bounce',
+ String $master_defer_command = 'bounce',
+ Array[String] $master_entries = [], # postfix_master_entries
+ Optional[String] $master_smtp = undef, # postfix_master_smtp
+ Optional[String] $master_smtps = undef, # postfix_master_smtps
+ Optional[String] $master_submission = undef, # postfix_master_submission
+ Optional[String] $mastercf_content = undef,
+ Optional[String] $mastercf_source = undef,
+ Optional[String] $mastercf_template = undef,
+ Optional[Array[String[1]]] $masquerade_classes = undef,
+ Optional[Array[String[1]]] $masquerade_domains = undef,
+ Optional[Array[String[1]]] $masquerade_exceptions = undef,
+ Boolean $mta = false,
+ String $mydestination = '$myorigin', # postfix_mydestination
+ String $mynetworks = '127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128', # postfix_mynetworks
+ String $myorigin = $facts['networking']['fqdn'],
+ String $postfix_ensure = 'present',
+ Optional[String] $relayhost = undef, # postfix_relayhost
+ String $root_group = 'root',
+ Variant[Array[String], String] $root_mail_recipient = 'nobody', # root_mail_recipient
+ Boolean $satellite = false,
+ Boolean $service_enabled = true,
+ String $service_ensure = 'running',
+ Variant[Array[String[1]], String[1]] $smtp_listen = '127.0.0.1', # postfix_smtp_listen
+ Hash $transports = {},
+ Boolean $use_amavisd = false, # postfix_use_amavisd
+ Boolean $use_dovecot_lda = false, # postfix_use_dovecot_lda
+ Variant[Integer[2, 3], Boolean] $use_schleuder = false, # postfix_use_schleuder
+ Boolean $use_sympa = false, # postfix_use_sympa
+ Hash $virtuals = {},
) inherits postfix::params {
if (
($mastercf_source and $mastercf_content) or
diff --git a/manifests/ldap.pp b/manifests/ldap.pp
index 165296fb3898a5c1aedfe2e95ccab6e374b09abc..b31f17cf54ef4055f25e2b549ecedb966ca177dd 100644
--- a/manifests/ldap.pp
+++ b/manifests/ldap.pp
@@ -1,19 +1,9 @@
-# == Class: postfix::ldap
+# @summary Provides the postfix ldap support
#
-# Configures postfix for use with LDAP.
-#
-# === Parameters
-#
-# === Requires
-#
-# - Class["postfix"]
-#
-# === Examples
-#
-# include postfix
-# include postfix::ldap
+# @api private
#
class postfix::ldap {
+ assert_private()
assert_type(String, $postfix::ldap_base)
assert_type(String, $postfix::ldap_host)
assert_type(String, $postfix::ldap_options)
diff --git a/manifests/mailalias.pp b/manifests/mailalias.pp
index 8ca6a0f95e05f4328a23b0e91abcfe778d9d1a3b..f74a58da9d35243a5526a3062ee28b95e31a7ada 100644
--- a/manifests/mailalias.pp
+++ b/manifests/mailalias.pp
@@ -1,32 +1,26 @@
-# == Definition: postfix::mailalias
+# @summary Manage the content of the postfix alias map
#
# Creates an email alias in the local alias database and updates the binary
# version of said database.
#
-# === Parameters
+# @example Simple example
+# include postfix
+# postfix::mailalias { 'postmaster':
+# ensure => present,
+# recipient => 'foo',
+# }
#
-# [*name*] - the alias name. See aliases(5).
-# [*ensure*] - present/absent, defaults to present.
-# [*recipient*] - where email should be sent.
+# @param ensure
+# Intended state of the resource
#
-# === Requires
+# @param recipient
+# The recipient address where the mail should be sent to.
#
-# - Class["postfix"]
-#
-# === Examples
-#
-# node "toto.example.com" {
-#
-# include postfix
-#
-# postfix::mailalias { 'postmaster':
-# ensure => present,
-# recipient => 'foo',
-# }
+# @see http://www.postfix.org/aliases.5.html
#
define postfix::mailalias (
Variant[String, Array[String]] $recipient,
- Enum['present', 'absent'] $ensure='present',
+ Enum['present', 'absent'] $ensure = 'present'
) {
mailalias { $title:
ensure => $ensure,
diff --git a/manifests/mailman.pp b/manifests/mailman.pp
index 8a1a4a92353e038a32439eafb0d769b7369f92b4..e5c432e1fcd882ef86e9cc5a554f84c38490e389 100644
--- a/manifests/mailman.pp
+++ b/manifests/mailman.pp
@@ -1,17 +1,13 @@
-# == Class: postfix::mailman
+# @summary Configure postfix to work with mailman
#
# Configures a basic smtp server, able to work for the mailman mailing-list
# manager.
#
-# === Examples
+# @api private
#
-# /!\ Do not include this class directly,
-# use mailman => true in the postfix top class!
-#
-# class { 'postfix':
-# mailman => true,
-# }
class postfix::mailman {
+ assert_private()
+
include postfix
postfix::config {
diff --git a/manifests/map.pp b/manifests/map.pp
index 9d8454cf31343689abea73ef0d70be172e1522bd..70b2e438809f796072977b8382efd74919219995 100644
--- a/manifests/map.pp
+++ b/manifests/map.pp
@@ -1,25 +1,10 @@
-# == Definition: postfix::map
+# @summary Create a postfix map file
#
# Creates postfix "map" files. It will create "${name}", and then build
# "${name}.db" using the "postmap" command. The map file can then be referred to
# using postfix::config.
#
-# === Parameters
-#
-# [*name*] - the name of the map file.
-# [*ensure*] - present/absent, defaults to present.
-# [*source*] - file source.
-# [*type*] - type of the postfix map (valid values are cidr, pcre, hash...)
-# [*path*] - path of the created file. By default it is placed in the
-# postfix directory.
-# [*mode*] - mode of the created file. By default it is '0640'.
-#
-# === Requires
-#
-# - Class["postfix"]
-#
-# === Examples
-#
+# @example Postfix map file and use in config
# postfix::map { '/etc/postfix/virtual':
# ensure => present,
# }
@@ -27,13 +12,35 @@
# value => 'hash:/etc/postfix/virtual',
# }
#
+# @param ensure
+# Intended state of the resource
+#
+# @param source
+# Sets the value of the source parameter for the file. Can't be used
+# together with parameter content.
+#
+# @param content
+# The content of the file. Can't be used together with param source.
+#
+# @param type
+# Type of the postfix map (valid values are cidr, pcre, hash...)
+#
+# @param path
+# Where to create the file. If not defined "${postfix::confdir}/${name}"
+# will be used as path.
+#
+# @param mode
+# File mode of the created file.
+#
+# @see http://www.postfix.org/postmap.1.html
+#
define postfix::map (
- Enum['present', 'absent'] $ensure = 'present',
- Optional[Variant[Array[String], String]] $source = undef,
+ Enum['present', 'absent'] $ensure = 'present',
+ Optional[Variant[Array[String], String]] $source = undef,
Optional[Variant[Sensitive[String], String]] $content = undef,
- String[1] $type = 'hash',
- Optional[Stdlib::Absolutepath] $path = undef,
- String[4,4] $mode = '0640',
+ String[1] $type = 'hash',
+ Optional[Stdlib::Absolutepath] $path = undef,
+ String[4,4] $mode = '0640',
) {
include postfix
include postfix::params
diff --git a/manifests/mta.pp b/manifests/mta.pp
index 2fbb2d8c8d7842d1181a65cabc0eb527646340d0..5ebffe9b2a317d054f7d1272674a2836740c38bf 100644
--- a/manifests/mta.pp
+++ b/manifests/mta.pp
@@ -1,32 +1,6 @@
-# == Class: postfix::mta
+# @summary Configures postfix as minimal MTA
#
-# This class configures a minimal MTA, delivering mail to
-# $mydestination.
-#
-# Either a valid relay host or the special word 'direct' is required
-# ($relayhost) for outbound email.
-#
-# transport & virtual maps get configured and can be populated with
-# postfix::transport and postfix::virtual
-#
-# === Parameters
-#
-# [*relayhost*] - (string) the relayhost to use or 'direct' to send mail
-# directly without a relay.
-# [*mydestination*] - (string)
-# [*mynetworks*] - (string)
-# [*masquerade_classes*] - (array)
-# [*masquerade_domains*] - (array)
-# [*masquerade_exceptions*] - (array)
-#
-# === Examples
-#
-# class { 'postfix':
-# relayhost => 'mail.example.com',
-# smtp_listen => '0.0.0.0',
-# mydestination => '$myorigin, myapp.example.com',
-# mta => true,
-# }
+# @api private
#
class postfix::mta (
Optional[Pattern[/^\S+(?:,\s*\S+)*$/]] $mydestination = undef,
@@ -36,6 +10,7 @@ class postfix::mta (
Optional[Array[String[1]]] $masquerade_domains = undef,
Optional[Array[String[1]]] $masquerade_exceptions = undef,
) {
+ assert_private()
include postfix
$_mydestination = pick($mydestination, $postfix::mydestination)
diff --git a/manifests/packages.pp b/manifests/packages.pp
index f77b8fcb00d55de8193ff61398650849ae3f583f..0755012a2991fcca11e93b815e843dca55185ec9 100644
--- a/manifests/packages.pp
+++ b/manifests/packages.pp
@@ -1,3 +1,7 @@
+# @summary Install the required packages for postfix
+#
+# @api private
+#
class postfix::packages {
assert_private()
diff --git a/manifests/params.pp b/manifests/params.pp
index 9af40762ea350f82c7965f88c21d5211fa9ad2dd..10e879bac3500df320a6322c9293601c48e0d320 100644
--- a/manifests/params.pp
+++ b/manifests/params.pp
@@ -1,19 +1,23 @@
-#
-# == Class: postfix::params
+# @summary Default parameters
#
# This class provides the appropriate values for operating system specific variables.
#
-# === Parameters
+# @param mailx_package
+# Name of package that provides mailx
#
-# [*mailx_package*] - (string) Name of package that provides mailx
+# @param restart_cmd
+# Command to use when restarting postfix
#
-# [*restart_cmd*] - (hash) Command to use when restarting postfix
+# @param aliasesseltype
+# Selinux type for /etc/aliases
#
-# [*aliasesseltype*] - (string) Selinux type for /etc/aliases
+# @param seltype
+# Selinux type for /etc/postfix/* config files
#
-# [*seltype*] - (string) Selinux type for /etc/postfix/* config files
+# @param master_os_template
+# Path to the master template
#
-# [*master_os_template*] - (string) Path to the master template
+# @api private
#
class postfix::params (
String $mailx_package,
diff --git a/manifests/satellite.pp b/manifests/satellite.pp
index 9b745be28dfbb612c1bb1fa5d0d574f0ae7fa730..dbf7fcc72fe28acb1df775fd6d0a3473525093f8 100644
--- a/manifests/satellite.pp
+++ b/manifests/satellite.pp
@@ -1,29 +1,6 @@
+# @summary Configure postfix as satellite
#
-# == Class: postfix::satellite
-#
-# This class configures all local email (cron, mdadm, etc) to be forwarded
-# to $root_mail_recipient, using $relayhost as a relay.
-#
-# This class will call postfix::mta and override its parameters.
-# You shouldn't call postfix::mta yourself or use mta=true in the postfix class.
-#
-# === Parameters
-#
-# [*mydestination*] - (string)
-# [*mynetworks*] - (string)
-# [*relayhost*] - (string)
-# [*masquerade_classes*] - (array)
-# [*masquerade_domains*] - (array)
-# [*masquerade_exceptions*] - (array)
-#
-# === Examples
-#
-# class { 'postfix':
-# relayhost => 'mail.example.com',
-# myorigin => 'toto.example.com',
-# root_mail_recipient => 'the.sysadmin@example.com',
-# satellite => true,
-# }
+# @api private
#
class postfix::satellite (
$mydestination = undef,
@@ -33,6 +10,7 @@ class postfix::satellite (
$masquerade_domains = undef,
$masquerade_exceptions = undef,
) {
+ assert_private()
include postfix
assert_type(Pattern[/^\S+$/], $postfix::myorigin)
diff --git a/manifests/service.pp b/manifests/service.pp
index 64af5a2a53e6d49746c3a7af9bc525e66b866043..126c3a885905d4d013e2b68df6f923d3aa258e3f 100644
--- a/manifests/service.pp
+++ b/manifests/service.pp
@@ -1,3 +1,7 @@
+# @summary Manage service resources for postfix
+#
+# @api private
+#
class postfix::service {
assert_private()
diff --git a/manifests/transport.pp b/manifests/transport.pp
index f3402304352e384c55c79b15f32883ce500cc9fa..42c2fff79d2765ef9091cc994a967224f2f81b9d 100644
--- a/manifests/transport.pp
+++ b/manifests/transport.pp
@@ -1,51 +1,48 @@
-# == Definition: postfix::transport
+# @summary Manage the transport map of postfix
#
# Manages content of the /etc/postfix/transport map.
#
-# === Parameters
-#
-# [*name*] - name of address postfix will lookup. See transport(5).
-# [*destination*] - where the emails will be delivered to. See transport(5).
-# [*ensure*] - present/absent, defaults to present.
-# [*nexthop*] - A string to define where and how to deliver the mail. See transport(5).
-#
-# === Requires
+# @example Simple transport map config
+# include postfix
+# postfix::hash { '/etc/postfix/transport':
+# ensure => present,
+# }
+# postfix::config { 'transport_maps':
+# value => 'hash:/etc/postfix/transport, regexp:/etc/postfix/transport_regexp',
+# }
+# postfix::transport {
+# 'mailman.example.com':
+# ensure => present,
+# destination => 'mailman';
+# 'slow_transport':
+# ensure => present,
+# nexthop => '/^user-.*@mydomain\.com/'
+# file => '/etc/postfix/transport_regexp',
+# destination => 'slow'
+# }
#
-# - Class["postfix"]
-# - Postfix::Hash["/etc/postfix/transport"]
-# - Postfix::Config["transport_maps"]
-# - augeas
+# @param ensure
+# Defines whether the transport entry is present or not. Value can either be present or absent.
#
-# === Examples
+# @param destination
+# The destination to be delivered to (transport(5)).
+# Example: `mailman`.
#
-# node 'toto.example.com' {
+# @param nexthop
+# A string to define where and how to deliver the mail (transport(5)).
+# Example: `[smtp.google.com]:25`.
#
-# include postfix
+# @param file
+# Where to create the file. If not defined "${postfix::confdir}/transport"
+# will be used as path.
#
-# postfix::hash { '/etc/postfix/transport':
-# ensure => present,
-# }
-# postfix::config { 'transport_maps':
-# value => 'hash:/etc/postfix/transport, regexp:/etc/postfix/transport_regexp',
-# }
-# postfix::transport {
-# 'mailman.example.com':
-# ensure => present,
-# destination => 'mailman';
-# 'slow_transport':
-# ensure => present,
-# nexthop => '/^user-.*@mydomain\.com/'
-# file => '/etc/postfix/transport_regexp',
-# destination => 'slow'
-# }
-#
-# }
+# @see https://www.postfix.org/transport.5.html
#
define postfix::transport (
- Optional[String] $destination = undef,
- Optional[String] $nexthop=undef,
- Optional[Stdlib::Absolutepath] $file=undef,
- Enum['present', 'absent'] $ensure='present'
+ Enum['present', 'absent'] $ensure = 'present',
+ Optional[String] $destination = undef,
+ Optional[String] $nexthop = undef,
+ Optional[Stdlib::Absolutepath] $file = undef,
) {
include postfix
include postfix::augeas
diff --git a/manifests/virtual.pp b/manifests/virtual.pp
index aab630030473a6b1cffbc045492bc3f6e2e439dd..d60b3da7fc78dc24df2599a924c6ce1565db2984 100644
--- a/manifests/virtual.pp
+++ b/manifests/virtual.pp
@@ -1,47 +1,53 @@
-# == Definition: postfix::virtual
+# @summary Manages the contents of the virtual map.
#
# Manages content of the /etc/postfix/virtual map.
#
-# === Parameters
-#
-# [*name*] - name of address postfix will lookup. See virtual(8).
-# [*destination*] - a list of destinations where the emails will be delivered to. See virtual(8).
-# [*ensure*] - present/absent, defaults to present.
-# [*file*] - a string defining the location of the pre-hash map.
-#
-# === Requires
-#
-# - Class["postfix"]
-# - Postfix::Hash["/etc/postfix/virtual"]
-# - Postfix::Config["virtual_alias_maps"]
-# - augeas
+# @example Minimum Requirements
+# include postfix
+# postfix::hash { "/etc/postfix/virtual":
+# ensure => present,
+# }
+# postfix::config { "virtual_alias_maps":
+# value => "hash:/etc/postfix/virtual, regexp:/etc/postfix/virtual_regexp"
+# }
#
-# === Examples
+# @example Route mail to local users
+# postfix::virtual { "user@example.com":
+# ensure => present,
+# destination => ['root', 'postmaster'],
+# }
#
-# node "toto.example.com" {
+# @example Regex example
+# postfix::virtual { "/.+@.+/"
+# ensure => present,
+# file => '/etc/postfix/virtual_regexp',
+# destination => 'root',
+# }
#
-# include postfix
-# # postfix::hash { "/etc/postfix/virtual":
-# ensure => present,
-# }
-# postfix::config { "virtual_alias_maps":
-# value => "hash:/etc/postfix/virtual, regexp:/etc/postfix/virtual_regexp"
-# }
-# postfix::virtual { "user@example.com":
+# @example Route mail bound for 'user@example.com' to root.
+# postfix::virtual {'user@example.com':
# ensure => present,
-# destination => ['root', 'postmaster'],
-# }
-# postfix::virtual { "/.+@.+/"
-# ensure => present,
-# file => '/etc/postfix/virtual_regexp',
# destination => 'root',
-# }
# }
-
+#
+# @param ensure
+# A string whose valid values are present or absent.
+#
+# @param destination
+# A string defining where the e-mails will be delivered to, (virtual(8)).
+# Example: `root`
+#
+# @param file
+# A string defining the location of the virtual map, pre hash.
+# If not defined "${postfix::confdir}/virtual" will be used as path.
+# Example: `/etc/postfix/my_virtual_map`.
+#
+# @see https://www.postfix.org/virtual.8.html
+#
define postfix::virtual (
Variant[String, Array[String]] $destination,
- Optional[Stdlib::Absolutepath] $file=undef,
- Enum['present', 'absent'] $ensure='present'
+ Enum['present', 'absent'] $ensure = 'present',
+ Optional[Stdlib::Absolutepath] $file = undef
) {
include postfix
include postfix::augeas