Fix README formatting
This commit is contained in:
Seth Vargo
parent
9e0b1449ce
commit
8662b05ac3
179
README.md
179
README.md
@ -1,55 +1,38 @@
|
||||
Description
|
||||
===========
|
||||
|
||||
Installs and configures postfix for client or outbound relayhost, or
|
||||
to do SASL authentication.
|
||||
postfix Cookbook
|
||||
================
|
||||
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)
|
||||
------------
|
||||
### Platforms
|
||||
- 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
|
||||
==========
|
||||
|
||||
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.
|
||||
### 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
|
||||
### 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']`
|
||||
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`.
|
||||
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
|
||||
@ -77,95 +60,57 @@ 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_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
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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.
|
||||
### 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
|
||||
----------
|
||||
### 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
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
### 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.
|
||||
|
||||
**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.
|
||||
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 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.
|
||||
|
||||
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.
|
||||
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.
|
||||
### 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.
|
||||
|
||||
```ruby
|
||||
name "base"
|
||||
run_list("recipe[postfix]")
|
||||
override_attributes(
|
||||
@ -179,10 +124,11 @@ The `base` role is applied to all nodes in the environment.
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
The `relayhost` role is applied to the nodes that are relayhosts.
|
||||
Often this is 2 systems using a CNAME of `smtp.example.com`.
|
||||
The `relayhost` role is applied to the nodes that are relayhosts. Often this is 2 systems using a CNAME of `smtp.example.com`.
|
||||
|
||||
```ruby
|
||||
name "relayhost"
|
||||
run_list("recipe[postfix::server]")
|
||||
override_attributes(
|
||||
@ -195,12 +141,11 @@ Often this is 2 systems using a CNAME of `smtp.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.
|
||||
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.
|
||||
|
||||
```ruby
|
||||
name "sasl_relayhost"
|
||||
run_list("recipe[postfix], recipe[postfix::sasl_auth]")
|
||||
override_attributes(
|
||||
@ -218,16 +163,16 @@ access to SMTP.
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
For an example of using encrypted data bags to encrypt the SASL
|
||||
password, see the following blog post:
|
||||
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**
|
||||
|
||||
#### 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.
|
||||
|
||||
```ruby
|
||||
name "relayhost"
|
||||
run_list("recipe[postfix::server]")
|
||||
override_attributes(
|
||||
@ -239,9 +184,11 @@ If you'd like to use the more dynamic search based approach for discovery, use t
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
Then, add the `postfix::client` recipe to the run list of your `base` role or equivalent role for postfix clients.
|
||||
|
||||
```ruby
|
||||
name "base"
|
||||
run_list("recipe[postfix::client]")
|
||||
override_attributes(
|
||||
@ -253,9 +200,11 @@ Then, add the `postfix::client` recipe to the run list of your `base` role or eq
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```ruby
|
||||
name "postfix_master"
|
||||
description "a role for postfix master that isn't relayhost"
|
||||
run_list("recipe[postfix::server]")
|
||||
@ -268,9 +217,11 @@ If you wish to use a different role name for the relayhost, then also set the at
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
The base role would look something like this:
|
||||
|
||||
```ruby
|
||||
name "base"
|
||||
run_list("recipe[postfix::client]")
|
||||
override_attributes(
|
||||
@ -283,12 +234,13 @@ The base role would look something like this:
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
License and Author
|
||||
==================
|
||||
|
||||
Author:: Joshua Timberman <joshua@opscode.com>
|
||||
License & Authors
|
||||
-----------------
|
||||
- Author:: Joshua Timberman <joshua@opscode.com>
|
||||
|
||||
```text
|
||||
Copyright:: 2009-2012, Opscode, Inc
|
||||
|
||||
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.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user