kosmos/postfix-cookbook
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
postfix-cookbook/README.md
Eric G. Wolfe 0108248ac4 [COOK-3328] Refactor main.cf template and attributes 
Signed-off-by: Seth Vargo <sethvargo@gmail.com>
2013-08-24 14:04:22 -04:00

305 lines
11 KiB
Markdown
Raw Blame History

Description
===========
Installs and configures postfix for client or outbound relayhost, or
to do SASL authentication.
On RHEL-family systems, sendmail will be replaced with postfix.
Requirements
============
## Platform:
* Ubuntu 10.04+
* Debian 6.0+
* RHEL/CentOS/Scientific 5.7+, 6.2+
* Amazon Linux (as of AMIs created after 4/9/2012)
May work on other platforms with or without modification.
Attributes
==========
See `attributes/default.rb` for default values.
## Generic cookbook attributes
* `node['postfix']['mail_type']` - Sets the kind of mail
configuration. `master` will set up a server (relayhost).
* `node['postfix']['relayhost_role']` - name of a role used for search
in the client recipe.
* `node['postfix']['multi_environment_relay']` - set to true if nodes
should not constrain search for the relayhost in their own
environment.
* `node['postfix']['use_procmail']` - set to true if nodes should use
procmail as the delivery agent.
* `node['postfix']['aliases']` - hash of aliases to create with
`recipe[postfix::aliases]`, see below under __Recipes__ for more
information.
* `node['postfix']['main_template_source']` - Cookbook source for main.cf template. Default 'postfix'
* `node['postfix']['master_template_source']` - Cookbook source for master.cf template. Default 'postfix'
## main.cf and sasl\_passwd template attributes
The main.cf template has been simplified to include any attributes in the `node['postfix']['main']`
data structure. The following attributes are still included with this cookbook
to maintain some semblance of backwards compatibility.
This change in namespace to `node['postfix']['main']` should allow for greater flexibility,
given the large number of configuration variables for the postfix daemon. All of these cookbook
attributes correspond to the option of the same name in `/etc/postfix/main.cf`.
* `node['postfix']['main']['biff']` - (yes/no); default no
* `node['postfix']['main']['append_dot_mydomain']` - (yes/no); default no
* `node['postfix']['main']['myhostname']` - defaults to fqdn from Ohai
* `node['postfix']['main']['mydomain']` - defaults to domain from Ohai
* `node['postfix']['main']['myorigin']` - defaults to $myhostname
* `node['postfix']['main']['mynetworks']` - default is `127.0.0.0/8`
* `node['postfix']['main']['inet_interfaces']` - set to `loopback-only`, or `all` for server recipe
* `node['postfix']['main']['alias_maps']` - set to `hash:/etc/aliases`
* `node['postfix']['main']['mailbox_size_limit']` - set to `0` (disabled)
* `node['postfix']['main']['recipient_delimiter']` - set to `+`
* `node['postfix']['main']['mydestination']` - default fqdn, hostname, localhost.localdomain, localhost
* `node['postfix']['main']['smtpd_use_tls']` - (yes/no); default yes. See conditional cert/key attributes.
- `node['postfix']['main']['smtpd_tls_cert_file']` - conditional attribute, set to full path of server's x509 certificate.
- `node['postfix']['main']['smtpd_tls_key_file']` - conditional attribute, set to full path of server's private key
- `node['postfix']['main']['smtpd_tls_CAfile']` - set to platform specific CA bundle
- `node['postfix']['main']['smtpd_tls_session_cache_database']` - set to `btree:${data_directory}/smtpd_scache`
* `node['postfix']['main']['smtp_use_tls']` - (yes/no); default yes. See following conditional attributes.
- `node['postfix']['main']['smtp_tls_CAfile']` - set to platform specific CA bundle
- `node['postfix']['main']['smtp_tls_session_cache_database']` - set to `btree:${data_directory}/smtpd_scache`
* `node['postfix']['main']['smtp_sasl_auth_enable']` - (yes/no); default no. If enabled, see following conditional attributes.
- `node['postfix']['main']['smtp_sasl_password_maps']` - Set to `hash:/etc/postfix/sasl_passwd` template file
- `node['postfix']['main']['smtp_sasl_security_options']` - Set to noanonymous
- `node['postfix']['main']['relayhost']` - Set to empty string
- `node['postfix']['sasl']['smtp_sasl_user_name']` - SASL user to authenticate as. Default empty
- `node['postfix']['sasl']['smtp_sasl_passwd']` - SASL password to use. Default empty.
## master.cf template attributes
* `node['postfix']['master']['submission'] - Whether to use submission (TCP 587) daemon. (true/false); default false
Recipes
=======
default
-------
Installs the postfix package and manages the service and the main
configuration files (`/etc/postfix/main.cf` and
`/etc/postfix/master.cf`). See __Usage__ and __Examples__ to see how
to affect behavior of this recipe through configuration.
For a more dynamic approach to discovery for the relayhost, see the
`client` and `server` recipes below.
client
------
Use this recipe to have nodes automatically search for the mail relay
based which node has the `node['postfix']['relayhost_role']` role. Sets the
`node['postfix']['relayhost']` attribute to the first result from the
search.
Includes the default recipe to install, configure and start postfix.
Does not work with `chef-solo`.
sasl\_auth
----------
Sets up the system to authenticate with a remote mail relay using SASL
authentication.
server
------
To use Chef Server search to automatically detect a node that is the
relayhost, use this recipe in a role that will be relayhost. By
default, the role should be "relayhost" but you can change the
attribute `node['postfix']['relayhost_role']` to modify this.
**Note** This recipe will set the `node['postfix']['mail_type']` to
"master" with an override attribute.
aliases
-------
Manage `/etc/aliases` with this recipe. Currently only Ubuntu 10.04
platform has a template for the aliases file. Add your aliases
template to the `templates/default` or to the appropriate
platform+version directory per the File Specificity rules for
templates. Then specify a hash of aliases for the
`node['postfix']['aliases']` attribute.
Arrays are supported as alias values, since postfix supports
comma separated values per alias, simply specify your alias
as an array to use this handy feature.
http://wiki.opscode.com/display/chef/Templates#Templates-TemplateLocationSpecificity
Usage
=====
On systems that should simply send mail directly to a relay, or out to
the internet, use `recipe[postfix]` and modify the
`node['postfix']['relayhost']` attribute via a role.
On systems that should be the MX for a domain, set the attributes
accordingly and make sure the `node['postfix']['mail_type']` attribute
is `master`. See __Examples__ for information on how to use
`recipe[postfix::server]` to do this automatically.
If you need to use SASL authentication to send mail through your ISP
(such as on a home network), use `postfix::sasl_auth` and set
the appropriate attributes.
For each of these implementations, see __Examples__ for role usage.
Examples
--------
The example roles below only have the relevant postfix usage. You may
have other contents depending on what you're configuring on your
systems.
The `base` role is applied to all nodes in the environment.
name "base"
run_list("recipe[postfix]")
override_attributes(
"mail_type" => "client",
"postfix" => {
"main" => {
"mydomain" => "example.com",
"myorigin" => "example.com",
"relayhost" => "[smtp.example.com]",
"smtp_use_tls" => "no"
}
}
)
The `relayhost` role is applied to the nodes that are relayhosts.
Often this is 2 systems using a CNAME of `smtp.example.com`.
name "relayhost"
run_list("recipe[postfix::server]")
override_attributes(
"postfix" => {
"mail_type" => "master",
"main" => {
"mynetworks" => [ "10.3.3.0/24", "127.0.0.0/8" ],
"inet-interfaces" => "all",
"mydomain" => "example.com",
"myorigin" => "example.com"
}
)
The `sasl_relayhost` role is applied to the nodes that are relayhosts
and require authenticating with SASL. For example this might be on a
household network with an ISP that otherwise blocks direct internet
access to SMTP.
name "sasl_relayhost"
run_list("recipe[postfix], recipe[postfix::sasl_auth]")
override_attributes(
"postfix" => {
"mail_type" => "master",
"main" => {
"mynetworks" => "10.3.3.0/24",
"mail_type" => "master",
"mydomain" => "example.com",
"myorigin" => "example.com",
"relayhost" => "[smtp.comcast.net]:587",
"smtp_sasl_auth_enable" => "yes",
"smtp_sasl_passwd" => "your_password",
"smtp_sasl_user_name" => "your_username"
}
}
)
For an example of using encrypted data bags to encrypt the SASL
password, see the following blog post:
* http://jtimberman.github.com/blog/2011/08/06/encrypted-data-bag-for-postfix-sasl-authentication/
**Examples using the client & server recipes**
If you'd like to use the more dynamic search based approach for discovery, use the server and client recipes. First, create a relayhost role.
name "relayhost"
run_list("recipe[postfix::server]")
override_attributes(
"postfix" => {
"main" => {
"mynetworks" => "10.3.3.0/24",
"mydomain" => "example.com",
"myorigin" => "example.com"
}
}
)
Then, add the `postfix::client` recipe to the run list of your `base` role or equivalent role for postfix clients.
name "base"
run_list("recipe[postfix::client]")
override_attributes(
"postfix" => {
"mail_type" => "client",
"main" => {
"mydomain" => "example.com",
"myorigin" => "example.com"
}
}
)
If you wish to use a different role name for the relayhost, then also set the attribute in the `base` role. For example, `postfix_master` as the role name:
name "postfix_master"
description "a role for postfix master that isn't relayhost"
run_list("recipe[postfix::server]")
override_attributes(
"postfix" => {
"main" => {
"mynetworks" => "10.3.3.0/24",
"mydomain" => "example.com",
"myorigin" => "example.com"
}
}
)
The base role would look something like this:
name "base"
run_list("recipe[postfix::client]")
override_attributes(
"postfix" => {
"relayhost_role" => "postfix_master",
"mail_type" => "client",
"main" => {
"mydomain" => "example.com",
"myorigin" => "example.com"
}
}
)
License and Author
==================
Author:: Joshua Timberman <joshua@opscode.com>
Copyright:: 2009-2012, Opscode, Inc
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Reference in New Issue View Git Blame Copy Permalink