diff --git a/README b/README
index 5778bf7bb0b067088aa899abedb806c30654b608..964125f5f8aed33f9703b637831fcc009110c5f4 100644
--- a/README
+++ b/README
@@ -1,4 +1,12 @@
-include postfix
+= Postfix Puppet module
-postfix::config { "relay_domains": value => "localhost host.foo.com" }
+This module will help install and configure postfix.
+
+A couple of classes will preconfigure postfix for common needs.
+
+== Example:
+
+ include postfix
+
+ postfix::config { "relay_domains": value => "localhost host.foo.com" }
diff --git a/manifests/classes/postfix-mailman.pp b/manifests/classes/postfix-mailman.pp
index ace2af1e1e69825f127fcbf3ee557d05536e6cc1..c6c79816b597c2076ed3a30e6a12c422d848396c 100644
--- a/manifests/classes/postfix-mailman.pp
+++ b/manifests/classes/postfix-mailman.pp
@@ -1,3 +1,19 @@
+#
+# == Class: postfix::mailman
+#
+# Configures a basic smtp server, able to work for the mailman mailing-list
+# manager.
+#
+# Parameters:
+# - every global variable which works for class "postfix" will work here.
+#
+# Example usage:
+#
+# node "toto.example.com" {
+# include mailman
+# include postfix::mailman
+# }
+#
class postfix::mailman {
$postfix_ng_smtp_listen = "0.0.0.0"
include postfix
diff --git a/manifests/classes/postfix-mta.pp b/manifests/classes/postfix-mta.pp
index 451ac3624fb6f65a2054b0baa26e6fb6ffefd0b5..9046bad4c91843abcf1408153d40848f05b2da7d 100644
--- a/manifests/classes/postfix-mta.pp
+++ b/manifests/classes/postfix-mta.pp
@@ -1,4 +1,5 @@
-#########################################################################
+#
+# == Class: postfix::mta
#
# This class configures a minimal MTA, listening on
# $postfix_ng_smtp_listen (default to localhost) and delivering mail to
@@ -9,22 +10,26 @@
# transport & virtual maps get configured and can be populated with
# postfix::transport and postfix::virtual
#
-# Example:
+# Parameters:
+# - *$postfix_relayhost*
+# - *$postfix_mydestination*
+# - every global variable which works for class "postfix" will work here.
+#
+# Example usage:
#
-# node "toto.example.com" {
-# $postfix_relayhost = "mail.example.com"
-# $postfix_ng_smtp_listen = "0.0.0.0"
-# $postfix_mydestination = "\$myorigin, myapp.example.com"
+# node "toto.example.com" {
+# $postfix_relayhost = "mail.example.com"
+# $postfix_ng_smtp_listen = "0.0.0.0"
+# $postfix_mydestination = "\$myorigin, myapp.example.com"
#
-# include postfix::mta
+# include postfix::mta
#
-# postfix::transport { "myapp.example.com":
-# ensure => present,
-# destination => "local:",
+# postfix::transport { "myapp.example.com":
+# ensure => present,
+# destination => "local:",
+# }
# }
-# }
#
-
class postfix::mta {
case $postfix_relayhost {
diff --git a/manifests/classes/postfix-satellite.pp b/manifests/classes/postfix-satellite.pp
index a3ea3209546ac62b0994e8103d961dd38d93a2c6..cb92a9f7e168a62fa3135ae48df0fe4ef8cf3448 100644
--- a/manifests/classes/postfix-satellite.pp
+++ b/manifests/classes/postfix-satellite.pp
@@ -1,26 +1,29 @@
-#########################################################################
+#
+# == Class: postfix::satellite
#
# This class configures all local email (cron, mdadm, etc) to be forwarded
# to $root_mail_recipient, using $postfix_relayhost as a relay.
-#
+#
# $valid_fqdn can be set to override $fqdn in the case where the FQDN is
# not recognized as valid by the destination server.
#
-# All other parameters for postfix::mta are valid.
+# Parameters:
+# - *valid_fqdn*
+# - every global variable which works for class "postfix" will work here.
+#
+# Example usage:
#
-# Example:
+# node "toto.local.lan" {
+# $postfix_relayhost = "mail.example.com"
+# $valid_fqdn = "toto.example.com"
+# $root_mail_recipient = "the.sysadmin@example.com"
#
-# node "toto.local.lan" {
-# $postfix_relayhost = "mail.example.com"
-# $valid_fqdn = "toto.example.com"
-# $root_mail_recipient = "the.sysadmin@example.com"
+# include postfix::satellite
+# }
#
-# include postfix::satellite
-# }
-
class postfix::satellite {
- # If $fake_fqdn exists, use it to override $fqdn
+ # If $valid_fqdn exists, use it to override $fqdn
case $valid_fqdn {
"": { $valid_fqdn = $fqdn }
default: { $fqdn = "${valid_fqdn}" }
diff --git a/manifests/classes/postfix.pp b/manifests/classes/postfix.pp
index d79199eef633cf2ec9d1f33520d6aa20080816b3..8c4173ebeabd78b3413f43dc59888a839468394e 100644
--- a/manifests/classes/postfix.pp
+++ b/manifests/classes/postfix.pp
@@ -1,11 +1,23 @@
-#########################################################################
+#
+# == Class: postfix
#
# This class provides a basic setup of postfix with local and remote
# delivery and an SMTP server listening on the loopback interface.
#
-
+# Parameters:
+# - *$postfix_ng_smtp_listen*: address on which the smtp service will listen to. defaults to 127.0.0.1
+# - *$root_mail_recipient*: who will recieve root's emails. defaults to "nobody"
+#
+# Example usage:
+#
+# node "toto.example.com" {
+# $postfix_ng_smtp_listen = "192.168.1.10"
+# include postfix
+# }
+#
class postfix {
+ # selinux labels differ from one distribution to another
case $operatingsystem {
RedHat: {
@@ -46,7 +58,6 @@ class postfix {
}
# Aliases
-
file { "/etc/aliases":
ensure => present,
content => "# file managed by puppet\n",
@@ -55,6 +66,7 @@ class postfix {
notify => Exec["newaliases"],
}
+ # Aliases
exec { "newaliases":
command => "/usr/bin/newaliases",
refreshonly => true,
@@ -63,7 +75,6 @@ class postfix {
}
# Config files
-
file { "/etc/postfix/master.cf":
ensure => present,
owner => "root",
@@ -77,6 +88,7 @@ class postfix {
require => Package["postfix"],
}
+ # Config files
file { "/etc/postfix/main.cf":
ensure => present,
owner => "root",
@@ -89,7 +101,6 @@ class postfix {
}
# Default configuration parameters
-
postfix::config {
"myorigin": value => "${fqdn}";
"alias_maps": value => "hash:/etc/aliases";
diff --git a/manifests/definitions/config.pp b/manifests/definitions/config.pp
index 58fc590bec761b9feb45d5f74946793112266706..aaf73b56836e7b6b362881a6f30e660fe2447038 100644
--- a/manifests/definitions/config.pp
+++ b/manifests/definitions/config.pp
@@ -1,3 +1,34 @@
+/*
+== Definition: postfix::config
+
+Uses the "postconf" command to add/alter/remove options in postfix main
+configuation file (/etc/postfix/main.cf).
+
+Parameters:
+- *name*: name of the parameter.
+- *ensure*: present/absent. defaults to present.
+- *value*: value of the parameter.
+- *nonstandard*: inform postfix::config that this parameter is not recognized
+ by the "postconf" command. defaults to false.
+
+Requires:
+- Class["postfix"]
+
+Example usage:
+
+ node "toto.example.com" {
+
+ include postfix
+
+ postfix::config {
+ "smtp_use_tls" => "yes";
+ "smtp_sasl_auth_enable" => "yes";
+ "smtp_sasl_password_maps" => "hash:/etc/postfix/my_sasl_passwords";
+ "relayhost" => "[mail.example.com]:587";
+ }
+ }
+
+*/
define postfix::config ($ensure = present, $value, $nonstandard = false) {
case $ensure {
present: {
diff --git a/manifests/definitions/hash.pp b/manifests/definitions/hash.pp
index e012458c4af326f29d3b339298d3e50149ebb0b4..bb4156aba6c363953cf8bfcccb9d87e226a063f8 100644
--- a/manifests/definitions/hash.pp
+++ b/manifests/definitions/hash.pp
@@ -1,5 +1,37 @@
+/*
+== Definition: postfix::hash
+
+Creates postfix hashed "map" files. It will create "${name}", and then build
+"${name}.db" using the "postmap" command. The map file can then be referred to
+using postfix::config.
+
+Note: the content of the file is not managed by this definition.
+
+Parameters:
+- *name*: the name of the map file.
+- *ensure*: present/absent
+
+Requires:
+- Class["postfix"]
+
+Example usage:
+
+ node "toto.example.com" {
+
+ include postfix
+
+ postfix::hash { "/etc/postfix/virtual":
+ ensure => present,
+ }
+ postfix::config { "virtual_alias_maps":
+ value => "hash:/etc/postfix/virtual"
+ }
+ }
+
+*/
define postfix::hash ($ensure) {
+ # selinux labels differ from one distribution to another
case $operatingsystem {
RedHat: {
diff --git a/manifests/definitions/transport.pp b/manifests/definitions/transport.pp
index 0e462cb840c6435f53977ee9c134da67bed09eed..cf44faf472f09da65b7883dae5b3f9c18cf5cc90 100644
--- a/manifests/definitions/transport.pp
+++ b/manifests/definitions/transport.pp
@@ -1,3 +1,38 @@
+/*
+== Definition: postfix::transport
+
+Manages content of the /etc/postfix/transport map.
+
+Parameters:
+- *name*: name of address postfix will lookup. See transport(5).
+- *destination*: where the emails will be delivered to. See transport(5).
+- *ensure*: present/absent
+
+Requires:
+- Class["postfix"]
+- Postfix::Hash["/etc/postfix/transport"]
+- Postfix::Config["transport_maps"]
+- common::line (from module common)
+
+Example usage:
+
+ node "toto.example.com" {
+
+ include postfix
+
+ postfix::hash { "/etc/postfix/transport":
+ ensure => present,
+ }
+ postfix::config { "transport_maps":
+ value => "hash:/etc/postfix/transport"
+ }
+ postfix::transport { "mailman.example.com":
+ ensure => present,
+ destination => "mailman",
+ }
+ }
+
+*/
define postfix::transport ($ensure, $destination) {
line {"${name} ${destination}":
ensure => present,
diff --git a/manifests/definitions/virtual.pp b/manifests/definitions/virtual.pp
index 75113409b474bebd2b8b50e7e2fb002cfe545c73..c40e64bd70377a67e00e27ad20b4cdf480a4b4c4 100644
--- a/manifests/definitions/virtual.pp
+++ b/manifests/definitions/virtual.pp
@@ -1,3 +1,38 @@
+/*
+== Definition: postfix::virtual
+
+Manages content of the /etc/postfix/virtual map.
+
+Parameters:
+- *name*: name of address postfix will lookup. See virtual(8).
+- *destination*: where the emails will be delivered to. See virtual(8).
+- *ensure*: present/absent
+
+Requires:
+- Class["postfix"]
+- Postfix::Hash["/etc/postfix/virtual"]
+- Postfix::Config["virtual_alias_maps"]
+- common::line (from module common)
+
+Example usage:
+
+ node "toto.example.com" {
+
+ include postfix
+
+ postfix::hash { "/etc/postfix/virtual":
+ ensure => present,
+ }
+ postfix::config { "virtual_alias_maps":
+ value => "hash:/etc/postfix/virtual"
+ }
+ postfix::virtual { "user@example.com":
+ ensure => present,
+ destination => "root",
+ }
+ }
+
+*/
define postfix::virtual ($ensure, $destination) {
line {"${name} ${destination}":
ensure => present,