README.md 12.8 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
Mickaël Canévet's avatar
Mickaël Canévet committed
12
13
```puppet
include postfix
14

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
22
In order to not have any path problem, you should add the following line in some globally included .pp file:
Mickaël Canévet's avatar
Mickaël Canévet committed
23
24
25
26
```puppet
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:
Mickaël Canévet's avatar
Mickaël Canévet committed
29
30
31
32
```puppet
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.

108
109
110
111
112
113
##### `manage_mailx`

A Boolean defining whether the puppet module should manage the mailx package. See also $mailx_ensure.

Default: true.

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

##### `master_smtp`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
120
121
122
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
123
124

##### `master smtps`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
125
126
127
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
128
129

##### `master_submission`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
130
131
132
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
133
134

##### `mta`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
135
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
136
137
138
Default: False.

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

##### `mynetworks`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
144
145
146
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
147
148

##### `myorigin`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
149
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
150
Default: The FQDN of the host.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
151
152
153
Example: 'example.com'

##### `relayhost`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
154
155
156
A string to define the relayhost parameter (postconf(5)).  
Default: Undefined.  
Example: 'smtp.example.com'. 
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
157
158

##### `root_mail_recipient`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
159
160
161
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
162
163

##### `satellite`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
164
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
165
166
167
Default: False.

##### `smtp_listen`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
168
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
169
170
Default: '127.0.0.1'.  
Example: '::1'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
171
172

##### `use_amavisd`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
173
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
174
175
Default: False.

176
##### `use_dovecot_lda`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
177
A Boolean to define whether to configure master.cf to use dovecot as the local delivery agent.  
178
179
180
Default: False.

##### `use_schleuder`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
181
A Boolean to define whether to configure master.cf to use the Schleuder GPG-enabled mailing list.  
182
183
184
Default: False.

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

188
#### Examples
189

Raphaël Pinson's avatar
Doc    
Raphaël Pinson committed
190
191
### postfix::config

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
192
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.
193
194
195
196

#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
197
198
199
A string whose value can be any of 'present', 'absent', 'blank'.  
Default: present.  
Example: blank.  
200
201

##### `value`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
202
203
204
A string that can contain any text to be used as the configuration value.  
Default: Undefined.  
Example: 'btree:${data_directory}/smtp_tls_session_cache'.
205
206
207

#### Examples
##### Configure Postfix to use TLS as a client
Mickaël Canévet's avatar
Mickaël Canévet committed
208
```puppet
209
postfix::config {
210
211
212
213
  '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';
214
215
216
217
}
```

##### Configure Postfix to disable the vrfy command
Mickaël Canévet's avatar
Mickaël Canévet committed
218
```puppet
219
postfix::config { 'disable_vrfy_command':
220
221
  ensure  => present,
  value   => 'yes',
222
223
}
```
Raphaël Pinson's avatar
Doc    
Raphaël Pinson committed
224
225

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

228
229
230
#### Parameters

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

235
##### `content`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
236
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
237
238
Default: Undefined.  
Example: '#Destination                Credentials\nsmtp.example.com            gssapi:nopassword'. 
239
240

##### `source`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
241
242
243
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'.
244
245
246

#### Examples
##### Create a sasl_passwd hash from a source file
Mickaël Canévet's avatar
Mickaël Canévet committed
247
```puppet
248
postfix::hash { '/etc/postfix/sasl_passwd':
249
250
  ensure  => 'present',
  source  => 'puppet:///modules/profile/postfix/client/sasl_passwd',
251
252
253
}
```
##### Create a sasl_passwd hash with contents defined in the manifest
Mickaël Canévet's avatar
Mickaël Canévet committed
254
```puppet
255
postfix::hash { '/etc/postfix/sasl_passwd':
256
257
  ensure  => 'present',
  content => '#Destination                Credentials\nsmtp.example.com            gssapi:nopassword',
258
259
}
```
Raphaël Pinson's avatar
Doc    
Raphaël Pinson committed
260
261
### postfix::transport

262
263
Manages content of the /etc/postfix/transport map.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
264
265
#### Requirements

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
266
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
267
268

The following code is required to use transport maps.
Mickaël Canévet's avatar
Mickaël Canévet committed
269
```puppet
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
270
271
include postfix

272
273
274
postfix::hash { '/etc/postfix/transport':
  ensure  => present,
}
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
275

276
277
278
postfix::config { 'transport_maps'
  ensure  => present,
  value   => 'hash:/etc/postfix/transport',
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
279
280
}
```
281
282
283
#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
284
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
285
Default: present.  
286
287
288
Example: absent.

##### `destination`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
289
The destination to be delivered to (transport(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
290
291
Default: Undefined.  
Example: 'mailman'.
292
293

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
298
#### Examples
Raphaël Pinson's avatar
Doc    
Raphaël Pinson committed
299
300
301

### postfix::virtual

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
302
303
304
Manages the contents of the virtual map.

#### Requirements
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
305
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
306
307

The following code is necessary to make virtual maps work:
Mickaël Canévet's avatar
Mickaël Canévet committed
308
```puppet
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
309
310
include postfix

311
312
postfix::hash { '/etc/postfix/virtual':
  ensure => present,
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
313
}
314

315
316
317
postfix::config { 'virtual_alias_maps':
  ensure  => present,
  value   => 'hash:/etc/postfix/virtual',
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
318
319
320
321
322
323
324
}
```
#### Parameters
##### `ensure`
A string whose valid values are present or absent.  
Default: present.  
Example: absent.
325

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
326
327
328
329
330
331
332
333
334
335
336
337
338
##### `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.
Mickaël Canévet's avatar
Mickaël Canévet committed
339
```puppet
340
postfix::virtual {'user@example.com':
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
341
342
343
344
    ensure      => present,
    destination => 'root',
}
```
Angel L. Mateo's avatar
Angel L. Mateo committed
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
## 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/>.