kosmos/postfix-cookbook
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix README formatting

Browse Source
This commit is contained in:
Seth Vargo 2013-08-28 17:10:40 -04:00
parent 9e0b1449ce
commit 8662b05ac3
1 changed files with 154 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
README.md
View File

@ -1,55 +1,38 @@
Description postfix Cookbook
=========== ================
Installs and configures postfix for client or outbound relayhost, or to do SASL authentication.
Installs and configures postfix for client or outbound relayhost, or
to do SASL authentication.
On RHEL-family systems, sendmail will be replaced with postfix. On RHEL-family systems, sendmail will be replaced with postfix.
Requirements Requirements
============ ------------
### Platforms
## Platform: - Ubuntu 10.04+
- Debian 6.0+
* Ubuntu 10.04+ - RHEL/CentOS/Scientific 5.7+, 6.2+
* Debian 6.0+ - Amazon Linux (as of AMIs created after 4/9/2012)
* 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. May work on other platforms with or without modification.
Attributes
==========
Attributes
----------
See `attributes/default.rb` for default values. See `attributes/default.rb` for default values.
### Generic cookbook attributes
## 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']['mail_type']` - Sets the kind of mail * `node['postfix']['multi_environment_relay']` - set to true if nodes should not constrain search for the relayhost in their own environment.
configuration. `master` will set up a server (relayhost). * `node['postfix']['use_procmail']` - set to true if nodes should use procmail as the delivery agent.
* `node['postfix']['relayhost_role']` - name of a role used for search * `node['postfix']['aliases']` - hash of aliases to create with `recipe[postfix::aliases]`, see below under __Recipes__ for more information.
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']['main_template_source']` - Cookbook source for main.cf template. Default 'postfix'
* `node['postfix']['master_template_source']` - Cookbook source for master.cf template. Default 'postfix' * `node['postfix']['master_template_source']` - Cookbook source for master.cf template. Default 'postfix'
## main.cf and sasl\_passwd template attributes ### 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.
The main.cf template has been simplified to include any attributes in the `node['postfix']['main']` 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`.
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']['biff']` - (yes/no); default no
* `node['postfix']['main']['append_dot_mydomain']` - (yes/no); default no * `node['postfix']['main']['append_dot_mydomain']` - (yes/no); default no
@ -77,98 +60,60 @@ attributes correspond to the option of the same name in `/etc/postfix/main.cf`.
- `node['postfix']['sasl']['smtp_sasl_user_name']` - SASL user to authenticate as. Default empty - `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. - `node['postfix']['sasl']['smtp_sasl_passwd']` - SASL password to use. Default empty.
## master.cf template attributes ### master.cf template attributes
* `node['postfix']['master']['submission'] - Whether to use submission (TCP 587) daemon. (true/false); default false * `node['postfix']['master']['submission'] - Whether to use submission (TCP 587) daemon. (true/false); default false
Recipes Recipes
=======
default
------- -------
### 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.
Installs the postfix package and manages the service and the main For a more dynamic approach to discovery for the relayhost, see the `client` and `server` recipes below.
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
`client` and `server` recipes below. 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.
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. Includes the default recipe to install, configure and start postfix.
Does not work with `chef-solo`. Does not work with `chef-solo`.
sasl\_auth ### sasl\_auth
---------- Sets up the system to authenticate with a remote mail relay using SASL authentication.
Sets up the system to authenticate with a remote mail relay using SASL ### server
authentication. 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.
server **Note** This recipe will set the `node['postfix']['mail_type']` to "master" with an override attribute.
------
To use Chef Server search to automatically detect a node that is the ### aliases
relayhost, use this recipe in a role that will be relayhost. By 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.
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 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.
"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 http://wiki.opscode.com/display/chef/Templates#Templates-TemplateLocationSpecificity
Usage 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 simply send mail directly to a relay, or out to 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.
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 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.
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. For each of these implementations, see __Examples__ for role usage.
Examples
--------
The example roles below only have the relevant postfix usage. You may ### Examples
have other contents depending on what you're configuring on your The example roles below only have the relevant postfix usage. You may have other contents depending on what you're configuring on your systems.
systems.
The `base` role is applied to all nodes in the environment. The `base` role is applied to all nodes in the environment.
name "base" ```ruby
run_list("recipe[postfix]") name "base"
override_attributes( run_list("recipe[postfix]")
override_attributes(
"mail_type" => "client", "mail_type" => "client",
"postfix" => { "postfix" => {
"main" => { "main" => {
@ -178,14 +123,15 @@ The `base` role is applied to all nodes in the environment.
"smtp_use_tls" => "no" "smtp_use_tls" => "no"
} }
} }
) )
```
The `relayhost` role is applied to the nodes that are relayhosts. The `relayhost` role is applied to the nodes that are relayhosts. Often this is 2 systems using a CNAME of `smtp.example.com`.
Often this is 2 systems using a CNAME of `smtp.example.com`.
name "relayhost" ```ruby
run_list("recipe[postfix::server]") name "relayhost"
override_attributes( run_list("recipe[postfix::server]")
override_attributes(
"postfix" => { "postfix" => {
"mail_type" => "master", "mail_type" => "master",
"main" => { "main" => {
@ -194,16 +140,15 @@ Often this is 2 systems using a CNAME of `smtp.example.com`.
"mydomain" => "example.com", "mydomain" => "example.com",
"myorigin" => "example.com" "myorigin" => "example.com"
} }
) )
```
The `sasl_relayhost` role is applied to the nodes that are relayhosts 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.
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" ```ruby
run_list("recipe[postfix], recipe[postfix::sasl_auth]") name "sasl_relayhost"
override_attributes( run_list("recipe[postfix], recipe[postfix::sasl_auth]")
override_attributes(
"postfix" => { "postfix" => {
"mail_type" => "master", "mail_type" => "master",
"main" => { "main" => {
@ -217,20 +162,20 @@ access to SMTP.
"smtp_sasl_user_name" => "your_username" "smtp_sasl_user_name" => "your_username"
} }
} }
) )
```
For an example of using encrypted data bags to encrypt the SASL For an example of using encrypted data bags to encrypt the SASL password, see the following blog post:
password, see the following blog post:
* http://jtimberman.github.com/blog/2011/08/06/encrypted-data-bag-for-postfix-sasl-authentication/ * http://jtimberman.github.com/blog/2011/08/06/encrypted-data-bag-for-postfix-sasl-authentication/
**Examples using the client & server recipes** #### 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. 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" ```ruby
run_list("recipe[postfix::server]") name "relayhost"
override_attributes( run_list("recipe[postfix::server]")
override_attributes(
"postfix" => { "postfix" => {
"main" => { "main" => {
"mynetworks" => "10.3.3.0/24", "mynetworks" => "10.3.3.0/24",
@ -238,13 +183,15 @@ If you'd like to use the more dynamic search based approach for discovery, use t
"myorigin" => "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. Then, add the `postfix::client` recipe to the run list of your `base` role or equivalent role for postfix clients.
name "base" ```ruby
run_list("recipe[postfix::client]") name "base"
override_attributes( run_list("recipe[postfix::client]")
override_attributes(
"postfix" => { "postfix" => {
"mail_type" => "client", "mail_type" => "client",
"main" => { "main" => {
@ -252,14 +199,16 @@ Then, add the `postfix::client` recipe to the run list of your `base` role or eq
"myorigin" => "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: 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" ```ruby
description "a role for postfix master that isn't relayhost" name "postfix_master"
run_list("recipe[postfix::server]") description "a role for postfix master that isn't relayhost"
override_attributes( run_list("recipe[postfix::server]")
override_attributes(
"postfix" => { "postfix" => {
"main" => { "main" => {
"mynetworks" => "10.3.3.0/24", "mynetworks" => "10.3.3.0/24",
@ -267,13 +216,15 @@ If you wish to use a different role name for the relayhost, then also set the at
"myorigin" => "example.com" "myorigin" => "example.com"
} }
} }
) )
```
The base role would look something like this: The base role would look something like this:
name "base" ```ruby
run_list("recipe[postfix::client]") name "base"
override_attributes( run_list("recipe[postfix::client]")
override_attributes(
"postfix" => { "postfix" => {
"relayhost_role" => "postfix_master", "relayhost_role" => "postfix_master",
"mail_type" => "client", "mail_type" => "client",
@ -282,13 +233,14 @@ The base role would look something like this:
"myorigin" => "example.com" "myorigin" => "example.com"
} }
} }
) )
```
License and Author License & Authors
================== -----------------
- Author:: Joshua Timberman <joshua@opscode.com>
Author:: Joshua Timberman <joshua@opscode.com>
```text
Copyright:: 2009-2012, Opscode, Inc Copyright:: 2009-2012, Opscode, Inc
Licensed under the Apache License, Version 2.0 (the "License"); Licensed under the Apache License, Version 2.0 (the "License");
@ -302,3 +254,4 @@ distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and See the License for the specific language governing permissions and
limitations under the License. limitations under the License.
```