Commit edfa9773 authored by Erinn Looney-Triggs's avatar Erinn Looney-Triggs Committed by Mickaël Canévet
Browse files

Expand and format docs.

parent b65dc1ac
...@@ -39,139 +39,142 @@ The top-level class, to install and configure Postfix. ...@@ -39,139 +39,142 @@ The top-level class, to install and configure Postfix.
##### `alias_maps` ##### `alias_maps`
A string defining the location of that alias map file. A string defining the location of that alias map file.
Default: 'hash:/etc/aliases' Default: 'hash:/etc/aliases'.
Example: 'hash:/etc/other_aliases'.
##### `inet_interfaces` ##### `inet_interfaces`
A string defining the network interfaces that Postfix will listen on. A string defining the network interfaces that Postfix will listen on.
Default: 'all' Default: 'all'.
Example: '127.0.0.1, [::1]' Example: '127.0.0.1, [::1]'.
##### `ldap` ##### `ldap`
A boolean defining whether to configure Postfix for LDAP use. A boolean defining whether to configure Postfix for LDAP use.
Default: false Default: false.
##### `ldap_base` ##### `ldap_base`
A string defining the LDAP search base to use. This maps to the search_base parameter (ldap_table(5)). A string defining the LDAP search base to use. This maps to the search_base parameter (ldap_table(5)).
Default: Undefined. Default: Undefined.
Example 'cn=Users,dc=example,dc=com' Example 'cn=Users,dc=example,dc=com'.
##### `ldap_host` ##### `ldap_host`
A string defining the LDAP host. This maps to the server_host parameter (ldap_table(5)). A string defining the LDAP host. This maps to the server_host parameter (ldap_table(5)).
Default: Undefined. Default: Undefined.
Example: 'ldaps://ldap.example.com:636 ldap://ldap2.example.com' Example: 'ldaps://ldap.example.com:636 ldap://ldap2.example.com'.
##### `ldap_options` ##### `ldap_options`
A A free form string that can defin any ldap options to be passed through.
Default: Undefined. Default: Undefined.
Example: Example: 'start_tls = yes'.
##### `mail_user` ##### `mail_user`
A string defining the mail user, and optionally group, to execute external commands as. This maps to the user parameter (pipe(8)). A string defining the mail user, and optionally group, to execute external commands as. This maps to the user parameter (pipe(8)).
Default: 'vmail'. Default: 'vmail'.
Example: 'vmail:vmail' Example: 'vmail:vmail'.
##### `mailman` ##### `mailman`
A boolean defining whether to configure a basic smtp server that is able to work for the mailman mailing list manager. A boolean defining whether to configure a basic smtp server that is able to work for the mailman mailing list manager.
Default: false. Default: false.
##### `maincf_source` ##### `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. 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" Default: "puppet:///modules/${module_name}/main.cf".
Example: "puppet:///modules/some/other/location/main.cf" Example: 'puppet:///modules/some/other/location/main.cf'.
##### `manage_conffiles` ##### `manage_conffiles`
A boolean defining whether the puppet module should replace the configuration files for postfix. A boolean defining whether the puppet module should replace the configuration files for postfix.
This setting currently effects the following files: **This setting currently effects the following files:**
* /etc/mailname * /etc/mailname
* /etc/postfix/master.cf * /etc/postfix/master.cf
This setting does NOT effect the following files:
**This setting does NOT effect the following files:**
* /etc/aliases * /etc/aliases
* /etc/postfix/main.cf * /etc/postfix/main.cf
Default: true. Default: true.
##### `mastercf_source` ##### `mastercf_source`
A string defining the location of a skeleton master.cf file to be used. A string defining the location of a skeleton master.cf file to be used.
Default: Undefined. Default: Undefined.
Example: "puppet:///modules/some/other/location/master.cf" Example: 'puppet:///modules/some/other/location/master.cf'.
##### `master_smtp` ##### `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. 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. Default: Undefined.
Example: 'smtp inet n - n - - smtpd' Example: 'smtp inet n - n - - smtpd'.
##### `master smtps` ##### `master smtps`
A string to define the smtps line in the /etc/postfix/master.cf file. A string to define the smtps line in the /etc/postfix/master.cf file.
Default: Undefined. Default: Undefined.
Example: 'smtps inet n - n - - smtpd' Example: 'smtps inet n - n - - smtpd'.
##### `master_submission` ##### `master_submission`
A string to define the submission line in the /etc/postfix/master.cf file. A string to define the submission line in the /etc/postfix/master.cf file.
Default: Undefined. Default: Undefined.
Example: 'submission inet n - n - - smtpd' Example: 'submission inet n - n - - smtpd'.
##### `mta` ##### `mta`
A boolean to define whether to configure Postfix as a mail transfer agent. This option is mutually exclusive with the satellite boolean. A boolean to define whether to configure Postfix as a mail transfer agent. This option is mutually exclusive with the satellite boolean.
Default: False. Default: False.
##### `mydestination` ##### `mydestination`
A string to define the mydestination parameter in main.cf (postconf(5)). A string to define the mydestination parameter in main.cf (postconf(5)).
Default: The systems FQDN. Default: The systems FQDN.
Example: 'example.com, foo.example.com' Example: 'example.com, foo.example.com'.
##### `mynetworks` ##### `mynetworks`
A string to define the mynetworks parameter that holds trusted remote smtp clients (postconf(5)). A string to define the mynetworks parameter that holds trusted remote smtp clients (postconf(5)).
Default: '127.0.0.0/8' Default: '127.0.0.0/8'.
Example: '127.0.0.0/8, [::1]/128' Example: '127.0.0.0/8, [::1]/128'.
##### `myorigin` ##### `myorigin`
A string to define the myorigin parameter that holds the domain name that mail appears to come from (postconf(5)). A string to define the myorigin parameter that holds the domain name that mail appears to come from (postconf(5)).
Default: The systems FQDN. Default: The systems FQDN.
Example: 'example.com' Example: 'example.com'
##### `relayhost` ##### `relayhost`
A string to define the relayhost parameter (postconf(5)). A string to define the relayhost parameter (postconf(5)).
Default: Undefined. Default: Undefined.
Example: 'smtp.example.com' Example: 'smtp.example.com'.
##### `root_mail_recipient` ##### `root_mail_recipient`
A string to define the e-mail address to which all mail directed to root should go (aliases(5)). A string to define the e-mail address to which all mail directed to root should go (aliases(5)).
Default: 'nobody' Default: 'nobody'.
Example: 'root_catch@example.com' Example: 'root_catch@example.com'.
##### `satellite` ##### `satellite`
A boolean to define whether to configure postfix as a sattellite relay host. This setting is mutually exclusive with the mta boolean. A boolean to define whether to configure postfix as a sattellite relay host. This setting is mutually exclusive with the mta boolean.
Default: False. Default: False.
##### `smtp_listen` ##### `smtp_listen`
A string to define the IP on which to listen in the 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. A string to define the IP on which to listen in the 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' Default: '127.0.0.1'.
Example: '::1' Example: '::1'.
##### `use_amavisd` ##### `use_amavisd`
A boolean to define whether to configure master.cf to allow the use of the amavisd scanner. A boolean to define whether to configure master.cf to allow the use of the amavisd scanner.
Default: False. Default: False.
##### `use_dovecot_lda` ##### `use_dovecot_lda`
A boolean to define whether to configure master.cf to use dovecot as the local delivery agent. A boolean to define whether to configure master.cf to use dovecot as the local delivery agent.
Default: False. Default: False.
##### `use_schleuder` ##### `use_schleuder`
A boolean to define whether to configure master.cf to use the Schleuder gpg-enabled mailinglist. A boolean to define whether to configure master.cf to use the Schleuder gpg-enabled mailinglist.
Default: False. Default: False.
##### `use_sympa` ##### `use_sympa`
A boolean to define whether to configure master.cf to use the Sympa mailing list management software. A boolean to define whether to configure master.cf to use the Sympa mailing list management software.
Default: False. Default: False.
#### Examples #### Examples
...@@ -183,14 +186,14 @@ Add/alter/remove options in Postfix main configuration file (main.cf). This uses ...@@ -183,14 +186,14 @@ Add/alter/remove options in Postfix main configuration file (main.cf). This uses
#### Parameters #### Parameters
##### `ensure` ##### `ensure`
A string whose value can be any of 'present', 'absent', 'blank'. A string whose value can be any of 'present', 'absent', 'blank'.
Default: 'present' Default: present.
Example: 'blank' Example: blank.
##### `value` ##### `value`
A string that can contain any text to be used as the configuration value. A string that can contain any text to be used as the configuration value.
Default: Undefined. Default: Undefined.
Example: 'btree:${data_directory}/smtp_tls_session_cache' Example: 'btree:${data_directory}/smtp_tls_session_cache'.
#### Examples #### Examples
##### Configure Postfix to use TLS as a client ##### Configure Postfix to use TLS as a client
...@@ -217,19 +220,19 @@ Creates Postfix hashed "map" files, and builds the corresponding db file. ...@@ -217,19 +220,19 @@ Creates Postfix hashed "map" files, and builds the corresponding db file.
#### Parameters #### Parameters
##### `ensure` ##### `ensure`
Defines whether the hash map file is present or not. Value can either be present or absent. Defines whether the hash map file is present or not. Value can either be present or absent.
Default: present. Default: present.
Example: absent. Example: absent.
##### `content` ##### `content`
A free form string that defines the contents of the file. This parameter is mutually exclusive to the source parameter. A free form string that defines the contents of the file. This parameter is mutually exclusive to the source parameter.
Default: Undefined. Default: Undefined.
Example: '#Destination Credentials\nsmtp.example.com gssapi:nopassword' Example: '#Destination Credentials\nsmtp.example.com gssapi:nopassword'.
##### `source` ##### `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. 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 Default: Undefined.
Example: 'puppet:///modules/some/location/sasl_passwd' Example: 'puppet:///modules/some/location/sasl_passwd'.
#### Examples #### Examples
##### Create a sasl_passwd hash from a source file ##### Create a sasl_passwd hash from a source file
...@@ -250,23 +253,109 @@ postfix::hash { '/etc/postfix/sasl_passwd': ...@@ -250,23 +253,109 @@ postfix::hash { '/etc/postfix/sasl_passwd':
Manages content of the /etc/postfix/transport map. Manages content of the /etc/postfix/transport map.
#### Requirements
Augeas is of course required.
The following code is required to use transport maps.
```
include postfix
postfix::hash{'/etc/postfix/transport':
ensure => present,
}
postfix::config{'transport_maps'
ensure => present,
value => 'hash:/etc/postfix/transport',
}
```
#### Parameters #### Parameters
##### `ensure` ##### `ensure`
Defines whether the transport entry is presnet or not. Value can either be present or absent. Defines whether the transport entry is presnet or not. Value can either be present or absent.
Default: present. Default: present.
Example: absent. Example: absent.
##### `destination` ##### `destination`
The destinationa to be delivered to (transport(5)). The destinationa to be delivered to (transport(5)).
Default: Undefined. Default: Undefined.
Example: 'mailman' Example: 'mailman'.
##### `nexthop` ##### `nexthop`
A string to define where and how to deliver the mail (transport(5)).
Default: Undefined.
Example: '[smtp.google.com]:25'.
#### Examples
### postfix::virtual ### postfix::virtual
Manages content in the virtual map. Manages the contents of the virtual map.
#### Requirements
Augeas is of course required.
The following code is necessary to make virtual maps work:
```
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.
```
postfix:: virtual {'user@example.com':
ensure => present,
destination => 'root',
}
```
## Contributing
Please report bugs and feature request using [GitHub issue
tracker](https://github.com/camptocamp/puppet-postfix/issues).
For pull requests, it is very much appreciated to check your Puppet manifest
with [puppet-lint](https://github.com/camptocamp/puppet-postfix/issues) to follow the recommended Puppet style guidelines from the
[Puppet Labs style guide](http://docs.puppetlabs.com/guides/style_guide.html).
## License
Copyright (c) 2015 <mailto:puppet@camptocamp.com> All rights reserved.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
...@@ -7,6 +7,7 @@ ...@@ -7,6 +7,7 @@
# [*name*] - name of address postfix will lookup. See transport(5). # [*name*] - name of address postfix will lookup. See transport(5).
# [*destination*] - where the emails will be delivered to. See transport(5). # [*destination*] - where the emails will be delivered to. See transport(5).
# [*ensure*] - present/absent, defaults to present. # [*ensure*] - present/absent, defaults to present.
# [*nexthop*] - A string to define where and how to deliver the mail. See transport(5).
# #
# === Requires # === Requires
# #
......
...@@ -7,6 +7,7 @@ ...@@ -7,6 +7,7 @@
# [*name*] - name of address postfix will lookup. See virtual(8). # [*name*] - name of address postfix will lookup. See virtual(8).
# [*destination*] - where the emails will be delivered to. See virtual(8). # [*destination*] - where the emails will be delivered to. See virtual(8).
# [*ensure*] - present/absent, defaults to present. # [*ensure*] - present/absent, defaults to present.
# [*file*] - A string defining the location of the pre-hash map.
# #
# === Requires # === Requires
# #
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment