COOK-831 - add README.md where it was missing completely
This commit is contained in:
jtimberman
parent
9df4d3e603
commit
563a8e6f24
174
README.md
Normal file
174
README.md
Normal file
@ -0,0 +1,174 @@
|
||||
Description
|
||||
===========
|
||||
|
||||
Installs and configures postfix for client or outbound relayhost, or
|
||||
to do SASL authentication.
|
||||
|
||||
Changes
|
||||
=======
|
||||
|
||||
## v0.8.4:
|
||||
|
||||
* Current public release.
|
||||
|
||||
Roadmap
|
||||
-------
|
||||
|
||||
* [COOK-880] - add client/server recipes for search
|
||||
* [COOK-881] - add (encrypted) data bag support for sasl credentials
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
## Platform:
|
||||
|
||||
* Ubuntu 10.04+
|
||||
* Debian 6.0+
|
||||
|
||||
Attributes
|
||||
==========
|
||||
|
||||
See `attributes/default.rb` for default values.
|
||||
|
||||
* `node['postfix']['mail_type']` - Sets the kind of mail
|
||||
configuration. `master` will set up a server (relayhost).
|
||||
* `node['postfix']['myhostname']` - corresponds to the myhostname
|
||||
option in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['mydomain']` - corresponds to the mydomain option
|
||||
in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['myorigin']` - corresponds to the myorigin option
|
||||
in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['relayhost']` - corresponds to the relayhost option
|
||||
in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['mail_relay_networks']` - corresponds to the
|
||||
mynetworks option in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['smtpd_use_tls']` - set to "yes" to use TLS for
|
||||
SMTPD, which will use the snakeoil certs.
|
||||
* `node['postfix']['smtp_sasl_auth_enable']` - set to "yes" to enable
|
||||
SASL authentication for SMTP.
|
||||
* `node['postfix']['smtp_sasl_password_maps']` - corresponds to the
|
||||
`smtp_sasl_password_maps` option in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['smtp_sasl_security_options']` - corresponds to the
|
||||
`smtp_sasl_security_options` option in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['smtp_tls_cafile']` - corresponds to the `smtp_tls_CAfile`
|
||||
option in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['smtp_use_tls']` - corresponds to the
|
||||
`smtp_use_tls` option in `/etc/postfix/main.cf`.
|
||||
* `node['postfix']['smtp_sasl_user_name']` - mapped in the
|
||||
`sasl_passwd` file as the user to authenticate as.
|
||||
* `node['postfix']['smtp_sasl_passwd']` - mapped in the `sasl_passwd`
|
||||
file as the password to use.
|
||||
|
||||
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.
|
||||
|
||||
sasl\_auth
|
||||
----------
|
||||
|
||||
Sets up the system to authenticate with a remote mail relay using SASL
|
||||
authentication.
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
If you need to use SASL authentication to send mail through your ISP
|
||||
(such as on a home network), use `recipe[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(
|
||||
"postfix" => {
|
||||
"mail_type" => "client",
|
||||
"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]")
|
||||
override_attributes(
|
||||
"postfix" => {
|
||||
"mail_relay_networks" => "10.3.3.0/24",
|
||||
"mail_type" => "master",
|
||||
"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_relay_networks" => "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/
|
||||
|
||||
License and Author
|
||||
==================
|
||||
|
||||
Author:: Joshua Timberman <joshua@opscode.com>
|
||||
|
||||
Copyright:: 2009-2011, 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.
|
||||
Loading…
x
Reference in New Issue
Block a user