README.md 11 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
12
13
14
15
16
## Simple usage

    include postfix

    postfix::config { "relay_domains": value  => "localhost host.foo.com" }

Simon Séhier's avatar
Simon Séhier committed
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
## Exec paths

In order to not have any path problem, you should add the following line in
some globally included .pp file:

    Exec {
      path => '/some/relevant/path:/some/other:...',
    }

For example:

    Exec {
      path => '/bin:/sbin:/usr/sbin:/usr/bin',
    }

32
33
## Classes

Raphaël Pinson's avatar
Doc    
Raphaël Pinson committed
34
35
36
### postfix

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

38
39
40
41
#### Parameters

##### `alias_maps`

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

##### `inet_interfaces`

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

##### `ldap`

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

##### `ldap_base`

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

##### `ldap_host`

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

##### `ldap_options`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
71
72
73
A free form string that can defin any ldap options to be passed through.  
Default: Undefined.  
Example: 'start_tls = yes'.
74
75
76

##### `mail_user`

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

##### `mailman`

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

##### `maincf_source`

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

##### `manage_conffiles`

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


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

Default: true.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
106
##### `mastercf_source`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
107
108
109
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
110
111

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

##### `master smtps`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
117
118
119
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
120
121

##### `master_submission`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
122
123
124
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
125
126

##### `mta`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
127
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
128
129
130
Default: False.

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

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

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

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

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

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

##### `smtp_listen`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
160
161
162
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'.  
Example: '::1'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
163
164

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

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

##### `use_schleuder`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
173
A boolean to define whether to configure master.cf to use the Schleuder gpg-enabled mailinglist.  
174
175
176
Default: False.

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

180
#### Examples
181

Raphaël Pinson's avatar
Doc    
Raphaël Pinson committed
182
183
### postfix::config

184
185
186
187
188
Add/alter/remove options in Postfix main configuration file (main.cf). This uses augeas to do the editing of the confiugration file, as such any configuration value can be used.

#### Parameters

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

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

#### 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
216
217

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

220
221
222
#### Parameters

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

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

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

#### 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
252
253
### postfix::transport

254
255
Manages content of the /etc/postfix/transport map.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
#### 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',
}
```
273
274
275
#### Parameters

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

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

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

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

### postfix::virtual

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
294
295
296
297
298
299
300
301
302
303
304
305
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,
}
306

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
318
319
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
##### `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/>.