add more documenation to new krb5.conf defined type

NEWS

@@ -3,8 +3,9 @@ release/005.007 (unreleased)
     [kerberos] Add option to completely override /etc/krb5.conf using
     the parameter 'source'. [adamhl]
 
-    [kerberos] Add a new 'define' that makes it easier to setup a
-    krb5.conf file. The define is base::kerberos::krb5_conf [adamhl]
+    [kerberos] Add a new defined resource type that makes it easier to
+    setup a krb5.conf file. The defined resource type is
+    base::kerberos::krb5_conf [adamhl]
 
     [newsyslog] Pull out filter-syslog from newsyslog so filtersyslog can
     be used separately from newsyslog. [adamhl]

manifests/kerberos/krb5_conf.pp

-# A define that creates a krb5.conf file.
+# A define that creates a krb5.conf file for use with the stanford.edu realm.
 #
-# The $name parameter is where the file will be put.
+# INTRODUCTION
+# This defined resource type generates a krb5.conf file suitable for use
+# on a Stanford Kerberos client. It should _not_ be used on a KDC; KDC's
+# should use the kdc class instead.
+#
+# This defined resource type allows a great deal of customization, but it
+# can be used to generate the default production krb5.conf file.
+#
+# EXAMPLES
+#
+# #######################################################################
+# 1. To generate the standard /etc/krb5.conf for use in the production
+# stanford.edu environment:
+#
+#   base::kerberos::krb5_conf { '/etc/krb5.conf': }
+#
+# That's it!
+#
+# #######################################################################
+# 2. If you need a krb5.conf for use with one of the non-production
+# environments, use the 'env' parameter. For example, to generate the
+# krb5.conf file suitable for authentication against the 'test' Kerberos
+# environment:
+#
+#   base::kerberos::krb5_conf { '/etc/krb5.conf':
+#     env => 'test',
+#   }
+#
+# This will generate a krb5.conf file whose [realms] section contains this
+# definition for stanford.edu:
+#
+#   [realms]
+#       stanford.edu = {
+#           kdc            = krb5auth-<env>1.stanford.edu:88
+#           kdc            = krb5auth-<env>2.stanford.edu:88
+#           kdc            = krb5auth-<env>3.stanford.edu:88
+#           kdc            = krb5auth-<env>4.stanford.edu:88
+#           master_kdc     = master-kdc-<env>.stanford.edu:88
+#           admin_server   = krb5-admin-<env>.stanford.edu
+#           kpasswd_server = krb5-admin-<env>.stanford.edu
+#           default_domain = stanford.edu
+#           kadmind_port   = 749
+#       }
+#
+# #######################################################################
+# 3. You can do complete customization by setting the 'env' to the value
+# 'custom':
+#
+#   base::kerberos::krb5_conf { '/etc/krb5.conf':
+#     env  => 'custom',
+#     kdcs => [
+#       'kerberos-abc1.stanford.edu',
+#       'kerberos-abc2.stanford.edu',
+#     master_kdc     => 'master-kdc-abc.stanford.edu',
+#     admin_server   => 'kerberos-abc1.stanford.edu',
+#     kpasswd_server => 'kerberos-abc1.stanford.edu',
+#   }
+#
+#
+#
+# PARAMETERS
+#
+## BASIC
+#
+# The $name parameter should be the full path to where the file will be put.
 #
 # $prefer_tcp:
 #   Normal kerberos traffic uses UDP, but some applications
@@ -137,6 +201,19 @@ define base::kerberos::krb5_conf (
       $kpasswd_server_actual = "krb5-admin-${env}.stanford.edu"
     }
     'custom': {
+      # Verify that the needed parameters are set.
+      if (length($kdcs) == 0) {
+        fail("when using a 'custom' environment you must define the kdc's")
+      }
+      if ($master_kdc == undef) {
+        fail("when using a 'custom' environment you must define the master_kdc")
+      }
+      if ($admin_server == undef) {
+        fail("when using a 'custom' environment you must define the admin_server")
+      }
+      if ($kpasswd_server == undef) {
+        fail("when using a 'custom' environment you must define the kpasswd_server")
+      }
       $kdcs_actual           = $kdcs
       $master_kdc_actual     = $master_kdc
       $admin_server_actual   = $admin_server