postfix: added/reformated documentation

4 files changed, 133 insertions, 0 deletions

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,