README.md 11.1 KB
Newer Older
Raphaël Pinson's avatar
Update  
Raphaël Pinson committed
1
# Postfix Puppet Module
2

Raphaël Pinson's avatar
Raphaël Pinson committed
3 4
[![Puppet Forge Version](http://img.shields.io/puppetforge/v/camptocamp/postfix.svg)](https://forge.puppetlabs.com/camptocamp/postfix)
[![Puppet Forge Downloads](http://img.shields.io/puppetforge/dt/camptocamp/postfix.svg)](https://forge.puppetlabs.com/camptocamp/postfix)
Raphaël Pinson's avatar
Update  
Raphaël Pinson committed
5
[![Build Status](https://img.shields.io/travis/camptocamp/puppet-postfix/master.svg)](https://travis-ci.org/camptocamp/puppet-postfix)
Raphaël Pinson's avatar
Raphaël Pinson committed
6 7
[![Gemnasium](https://img.shields.io/gemnasium/camptocamp/puppet-postfix.svg)](https://gemnasium.com/camptocamp/puppet-postfix)
[![By Camptocamp](https://img.shields.io/badge/by-camptocamp-fb7047.svg)](http://www.camptocamp.com)
8

Raphaël Pinson's avatar
Raphaël Pinson committed
9 10
This module requires Augeas.

11
## Simple usage
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
12
```
13 14
    include postfix

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
15
    postfix::config { 'relay_domains':
Erinn Looney-Triggs's avatar
Typo.  
Erinn Looney-Triggs committed
16
        ensure  => present,
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
17 18 19
        value   => 'localhost host.foo.com',
    }
```
Simon Séhier's avatar
Simon Séhier committed
20 21
## Exec paths

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
22 23
In order to not have any path problem, you should add the following line in some globally included .pp file:
```
Simon Séhier's avatar
Simon Séhier committed
24 25 26
    Exec {
      path => '/some/relevant/path:/some/other:...',
    }
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
27
```
Simon Séhier's avatar
Simon Séhier committed
28
For example:
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
29
```
Simon Séhier's avatar
Simon Séhier committed
30 31 32
    Exec {
      path => '/bin:/sbin:/usr/sbin:/usr/bin',
    }
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
33
```
34 35
## Classes

Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
36 37 38
### postfix

The top-level class, to install and configure Postfix.
39

40 41 42 43
#### Parameters

##### `alias_maps`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
44
A string defining the location of the alias map file.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
45 46
Default: 'hash:/etc/aliases'.  
Example: 'hash:/etc/other_aliases'.
47 48 49

##### `inet_interfaces`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
50 51 52
A string defining the network interfaces that Postfix will listen on.  
Default: 'all'.  
Example: '127.0.0.1, [::1]'.
53 54 55

##### `ldap`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
56
A Boolean defining whether to configure Postfix for LDAP use.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
57
Default: false.
58 59 60

##### `ldap_base`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
61
A string defining the LDAP search base to use. This parameter maps to the search_base parameter (ldap_table(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
62 63
Default: Undefined.  
Example 'cn=Users,dc=example,dc=com'.
64 65 66

##### `ldap_host`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
67
A string defining the LDAP host. This parameter maps to the server_host parameter (ldap_table(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
68 69
Default: Undefined.  
Example: 'ldaps://ldap.example.com:636 ldap://ldap2.example.com'.
70 71 72

##### `ldap_options`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
73
A free form string that can define any ldap options to be passed through (ldap_table(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
74 75
Default: Undefined.  
Example: 'start_tls = yes'.
76 77 78

##### `mail_user`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
79
A string defining the mail user, and optionally group, to execute external commands as. This parameter maps to the user parameter (pipe(8)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
80 81
Default: 'vmail'.  
Example: 'vmail:vmail'.
82 83 84

##### `mailman`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
85
A Boolean defining whether to configure a basic smtp server that is able to work for the mailman mailing list manager.  
86 87 88 89
Default: false.

##### `maincf_source`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
90
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.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
91 92
Default: "puppet:///modules/${module_name}/main.cf".  
Example: 'puppet:///modules/some/other/location/main.cf'.
93 94 95

##### `manage_conffiles`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
96 97
A Boolean defining whether the puppet module should replace the configuration files for postfix.  
**This setting currently effects only the following files:**
98
* /etc/mailname
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
99 100 101 102
* /etc/postfix/master.cf  


**This setting does NOT effect the following files:**
103 104 105 106 107
* /etc/aliases
* /etc/postfix/main.cf

Default: true.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
108
##### `mastercf_source`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
109 110 111
A string defining the location of a skeleton master.cf file to be used.  
Default: Undefined.  
Example: 'puppet:///modules/some/other/location/master.cf'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
112 113

##### `master_smtp`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
114 115 116
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'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
117 118

##### `master smtps`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
119 120 121
A string to define the smtps line in the /etc/postfix/master.cf file.  
Default: Undefined.  
Example: 'smtps     inet  n       -       n       -       -       smtpd'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
122 123

##### `master_submission`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
124 125 126
A string to define the submission line in the /etc/postfix/master.cf file.  
Default: Undefined.  
Example: 'submission inet n       -       n       -       -       smtpd'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
127 128

##### `mta`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
129
A Boolean to define whether to configure Postfix as a mail transfer agent. This option is mutually exclusive with the satellite Boolean.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
130 131 132
Default: False.

##### `mydestination`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
133 134 135
A string to define the mydestination parameter in main.cf (postconf(5)).  
Default: The systems FQDN.  
Example: 'example.com, foo.example.com'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
136 137

##### `mynetworks`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
138 139 140
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'.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
141 142

##### `myorigin`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
143
A string to define the myorigin parameter that holds the domain name that mail appears to come from (postconf(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
144
Default: The FQDN of the host.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
145 146 147
Example: 'example.com'

##### `relayhost`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
148 149 150
A string to define the relayhost parameter (postconf(5)).  
Default: Undefined.  
Example: 'smtp.example.com'. 
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
151 152

##### `root_mail_recipient`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
153 154 155
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'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
156 157

##### `satellite`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
158
A Boolean to define whether to configure postfix as a satellite relay host.  This setting is mutually exclusive with the mta Boolean.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
159 160 161
Default: False.

##### `smtp_listen`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
162
A string to define the IP 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.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
163 164
Default: '127.0.0.1'.  
Example: '::1'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
165 166

##### `use_amavisd`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
167
A Boolean to define whether to configure master.cf to allow the use of the amavisd scanner.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
168 169
Default: False.

170
##### `use_dovecot_lda`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
171
A Boolean to define whether to configure master.cf to use dovecot as the local delivery agent.  
172 173 174
Default: False.

##### `use_schleuder`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
175
A Boolean to define whether to configure master.cf to use the Schleuder GPG-enabled mailing list.  
176 177 178
Default: False.

##### `use_sympa`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
179
A Boolean to define whether to configure master.cf to use the Sympa mailing list management software.  
180
Default: False.
181

182
#### Examples
183

Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
184 185
### postfix::config

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
186
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.
187 188 189 190

#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
191 192 193
A string whose value can be any of 'present', 'absent', 'blank'.  
Default: present.  
Example: blank.  
194 195

##### `value`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
196 197 198
A string that can contain any text to be used as the configuration value.  
Default: Undefined.  
Example: 'btree:${data_directory}/smtp_tls_session_cache'.
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217

#### Examples
##### 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';
}
```

##### Configure Postfix to disable the vrfy command
```
postfix::config { 'disable_vrfy_command':
    ensure  => present,
    value   => 'yes',
}
```
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
218 219

### postfix::hash
220
Creates Postfix hashed "map" files, and builds the corresponding db file.
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
221

222 223 224
#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
225 226
Defines whether the hash map file is present or not. Value can either be present or absent.  
Default: present.  
227
Example: absent.
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
228

229
##### `content`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
230
A free form string that defines the contents of the file. This parameter is mutually exclusive with the source parameter.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
231 232
Default: Undefined.  
Example: '#Destination                Credentials\nsmtp.example.com            gssapi:nopassword'. 
233 234

##### `source`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
235 236 237
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'.
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253

#### Examples
##### 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',
}
```
##### 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',
}
```
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
254 255
### postfix::transport

256 257
Manages content of the /etc/postfix/transport map.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
258 259
#### Requirements

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
260
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
261 262 263 264 265 266 267 268 269 270 271 272 273 274

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',
}
```
275 276 277
#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
278
Defines whether the transport entry is present or not. Value can either be present or absent.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
279
Default: present.  
280 281 282
Example: absent.

##### `destination`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
283
The destination to be delivered to (transport(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
284 285
Default: Undefined.  
Example: 'mailman'.
286 287

##### `nexthop`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
288 289 290
A string to define where and how to deliver the mail (transport(5)).  
Default: Undefined.  
Example: '[smtp.google.com]:25'.
291

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
292
#### Examples
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
293 294 295

### postfix::virtual

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
296 297 298
Manages the contents of the virtual map.

#### Requirements
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
299
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
300 301 302 303 304 305 306 307

The following code is necessary to make virtual maps work:
```
include postfix

postfix::hash {'/etc/postfix/virtual':
    ensure  => present,
}
308

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
309 310 311 312 313 314 315 316 317 318
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.
319

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
##### `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/>.