README.md 12.4 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
[![By Camptocamp](https://img.shields.io/badge/by-camptocamp-fb7047.svg)](http://www.camptocamp.com)
7

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

10
## Simple usage
Mickaël Canévet's avatar
Mickaël Canévet committed
11 12
```puppet
include postfix
13

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

20 21
## Classes

Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
22 23 24
### postfix

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

26 27 28 29
#### Parameters

##### `alias_maps`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
30
A string defining the location of the alias map file.  
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
31 32
Default: 'hash:/etc/aliases'.  
Example: 'hash:/etc/other_aliases'.
33

34 35 36 37 38 39
##### `configs`

A hash containing optional configuration values for main.cf. The values are configured using postfix::config.  
Default: An empty hash.  
Example: '{message_size_limit': {'value': '51200000'}}.

40 41
##### `inet_interfaces`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
42 43 44
A string defining the network interfaces that Postfix will listen on.  
Default: 'all'.  
Example: '127.0.0.1, [::1]'.
45

46 47 48 49 50 51
##### `inet_protocols`

A string defining the internet protocols that Postfix will use.  
Default: 'all'.  
Example: 'ipv4'.

52 53
##### `ldap`

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

##### `ldap_base`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
59
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
60 61
Default: Undefined.  
Example 'cn=Users,dc=example,dc=com'.
62 63 64

##### `ldap_host`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
65
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
66 67
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
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
72 73
Default: Undefined.  
Example: 'start_tls = yes'.
74 75 76

##### `mail_user`

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
77
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
78 79
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
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
89 90
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 only 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.

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

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

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

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

132 133 134 135 136
##### `master_entries`
Array of strings containing additional entries for the /etc/postfix/master.cf file.
Default: Undefined.
Example: 'submission inet n       -       n       -       -       smtpd'.

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

##### `mydestination`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
142 143 144
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
145 146

##### `mynetworks`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
147 148 149
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
150 151

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

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

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

Angel L. Mateo's avatar
Angel L. Mateo committed
166 167 168 169 170
##### `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
171
##### `satellite`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
172
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
173 174 175
Default: False.

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

##### `use_amavisd`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
181
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
182 183
Default: False.

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

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

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

196
#### Examples
197

Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
198 199
### postfix::config

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
200
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.
201 202 203 204

#### Parameters

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

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

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

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

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

236 237 238
#### Parameters

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

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

##### `source`
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
249 250 251
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'.
252 253 254

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

270 271
Manages content of the /etc/postfix/transport map.

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
272 273
#### Requirements

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
274
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
275 276

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

280 281 282
postfix::hash { '/etc/postfix/transport':
  ensure  => present,
}
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
283

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

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

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

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
306
#### Examples
Raphaël Pinson's avatar
Doc  
Raphaël Pinson committed
307 308 309

### postfix::virtual

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
310 311 312
Manages the contents of the virtual map.

#### Requirements
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
313
Augeas is, of course, required.
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
314 315

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

319 320
postfix::hash { '/etc/postfix/virtual':
  ensure => present,
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
321
}
322

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

Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
334 335 336 337 338 339 340 341 342 343 344 345 346
##### `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
347
```puppet
348
postfix::virtual {'user@example.com':
Erinn Looney-Triggs's avatar
Erinn Looney-Triggs committed
349 350 351 352
    ensure      => present,
    destination => 'root',
}
```
Angel L. Mateo's avatar
Angel L. Mateo committed
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 397 398 399

### 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
400 401 402 403 404 405 406 407
## 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).