postfix: added/reformated documentation

8 files changed, 197 insertions, 29 deletions

diff --git a/manifests/classes/postfix-mailman.pp b/manifests/classes/postfix-mailman.pp
index ace2af1..c6c7981 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 451ac36..9046bad 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 a3ea320..cb92a9f 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 d79199e..8c4173e 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 58fc590..aaf73b5 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 e012458..bb4156a 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 0e462cb..cf44faf 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 7511340..c40e64b 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,