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
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
16
17
18
postfix::config { 'relay_domains':
    ensure  => present,
    value   => 'localhost host.foo.com',
}
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.

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

#### Examples
##### Configure Postfix to use TLS as a client
Mickaël Canévet's avatar
Mickaël Canévet committed
202
```puppet
203
204
205
206
207
208
209
210
211
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
Mickaël Canévet's avatar
Mickaël Canévet committed
212
```puppet
213
214
215
216
217
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

#### Examples
##### Create a sasl_passwd hash from a source file
Mickaël Canévet's avatar
Mickaël Canévet committed
241
```puppet
242
243
244
245
246
247
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
Mickaël Canévet's avatar
Mickaël Canévet committed
248
```puppet
249
250
251
252
253
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

The following code is required to use transport maps.
Mickaël Canévet's avatar
Mickaël Canévet committed
263
```puppet
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
264
265
266
267
268
269
270
271
272
273
274
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

The following code is necessary to make virtual maps work:
Mickaël Canévet's avatar
Mickaël Canévet committed
302
```puppet
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
303
304
305
306
307
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
##### `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
333
```puppet
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
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
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/>.