README.md 13 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

Angel L. Mateo's avatar
Angel L. Mateo committed
163 164 165 166 167
##### `chroot`
A boolean to define if postfix should be run in a chroot jail or not. If not defined, '-' is used (OS dependant)
Default: Undefined.
Example: true

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

##### `smtp_listen`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
173
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
174 175
Default: '127.0.0.1'.  
Example: '::1'.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
176 177

##### `use_amavisd`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
178
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
179 180
Default: False.

181
##### `use_dovecot_lda`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
182
A Boolean to define whether to configure master.cf to use dovecot as the local delivery agent.  
183 184 185
Default: False.

##### `use_schleuder`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
186
A Boolean to define whether to configure master.cf to use the Schleuder GPG-enabled mailing list.  
187 188 189
Default: False.

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

193
#### Examples
194

Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
195 196
### postfix::config

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
197
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.
198 199 200 201

#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
202 203 204
A string whose value can be any of 'present', 'absent', 'blank'.  
Default: present.  
Example: blank.  
205 206

##### `value`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
207 208 209
A string that can contain any text to be used as the configuration value.  
Default: Undefined.  
Example: 'btree:${data_directory}/smtp_tls_session_cache'.
210 211 212

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

##### Configure Postfix to disable the vrfy command
Mickaël Canévet's avatar
Mickaël Canévet committed
223
```puppet
224
postfix::config { 'disable_vrfy_command':
225 226
  ensure  => present,
  value   => 'yes',
227 228
}
```
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
229 230

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

233 234 235
#### Parameters

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

240
##### `content`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
241
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
242 243
Default: Undefined.  
Example: '#Destination                Credentials\nsmtp.example.com            gssapi:nopassword'. 
244 245

##### `source`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
246 247 248
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'.
249 250 251

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

267 268
Manages content of the /etc/postfix/transport map.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
269 270
#### Requirements

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
271
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
272 273

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

277 278 279
postfix::hash { '/etc/postfix/transport':
  ensure  => present,
}
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
280

281 282 283
postfix::config { 'transport_maps'
  ensure  => present,
  value   => 'hash:/etc/postfix/transport',
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
284 285
}
```
286 287 288
#### Parameters

##### `ensure`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
289
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
290
Default: present.  
291 292 293
Example: absent.

##### `destination`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
294
The destination to be delivered to (transport(5)).  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
295 296
Default: Undefined.  
Example: 'mailman'.
297 298

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
303
#### Examples
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
304 305 306

### postfix::virtual

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
307 308 309
Manages the contents of the virtual map.

#### Requirements
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
310
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
311 312

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

316 317
postfix::hash { '/etc/postfix/virtual':
  ensure => present,
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
318
}
319

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
331 332 333 334 335 336 337 338 339 340 341 342 343
##### `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
344
```puppet
345
postfix::virtual {'user@example.com':
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
346 347 348 349
    ensure      => present,
    destination => 'root',
}
```
Angel L. Mateo's avatar
Angel L. Mateo committed
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 392 393 394 395 396

### 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
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421
## 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/>.