From 0bf84794ac98b55b5e54e72b7b3f56a129ae5b80 Mon Sep 17 00:00:00 2001
From: Alexander Fisher <alex@linfratech.co.uk>
Date: Mon, 5 Nov 2018 16:27:59 +0000
Subject: [PATCH] Add reference docs and remove redundant `recurse` parameter

---
 README.md               |  23 +-
 REFERENCE.md            | 464 ++++++++++++++++++++++++++++++++++++++++
 manifests/command.pp    |   2 +-
 manifests/config.pp     |   4 +-
 manifests/config/ssl.pp |   2 +
 manifests/init.pp       | 107 ++++++++-
 manifests/install.pp    |   2 +
 manifests/params.pp     |   2 +
 manifests/service.pp    |   2 +
 9 files changed, 596 insertions(+), 12 deletions(-)
 create mode 100644 REFERENCE.md

diff --git a/README.md b/README.md
index 284b454..0d3538d 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
 1. [Module Description - What the module does and why it is useful](#module-description)
 1. [Setup - The basics of getting started with this module](#setup)
 1. [Usage - Configuration options and additional functionality](#usage)
+1. [Reference - Puppet Strings based reference documentation](#reference)
 1. [Limitations - OS compatibility, etc.](#limitations)
 1. [Development - Guide for contributing to the module](#development)
 
@@ -35,7 +36,7 @@ class { 'nrpe':
 ### nrpe
 
 No NRPE commands are configured by default. To make the configuration useful, at a minimum, declare some [`nrpe::command`](#nrpecommand) resources.
-To purge unmanaged nrpe commands:
+To purge unmanaged NRPE commands:
 
 ```puppet
 class { 'nrpe':
@@ -45,9 +46,11 @@ class { 'nrpe':
 }
 ```
 
+Full documentation for the `nrpe` class is available in the [reference](REFERENCE.md#nrpe) documentation.
+
 ### nrpe::command
 
-This define can be used to add nrpe commands to the include directory for nrpe
+This define can be used to add NRPE commands to the include directory for NRPE.
 
 ```puppet
 nrpe::command { 'check_users':
@@ -56,9 +59,11 @@ nrpe::command { 'check_users':
 }
 ```
 
+Full documentation for the `nrpe::command` type is available in the [reference](REFERENCE.md#nrpecommand) documentation.
+
 ### nrpe::plugin
 
-This define can be used to install nrpe plugins
+This define can be used to install NRPE plugins.
 
 ```puppet
 nrpe::plugin { 'check_mem':
@@ -67,6 +72,13 @@ nrpe::plugin { 'check_mem':
 }
 ```
 
+Full documentation for the `nrpe::plugin` type is available in the [reference](REFERENCE.md#nrpeplugin) documentation.
+
+## Reference
+
+See [REFERENCE.md](REFERENCE.md).
+This module has been documented with [puppet-strings](https://github.com/puppetlabs/puppet-strings).
+
 ## Limitations
 
 ### Redhat
@@ -82,6 +94,11 @@ nrpe::plugin { 'check_mem':
 
 Improvements and bug fixes are greatly appreciated.
 
+To regenerate the [REFERENCE.MD](REFERENCE.md) file, please run the rake task as follows.
+```console
+ % bundle exec rake strings:generate\[',,,,false,true']
+```
+
 This module is a fork of [pdxcat/nrpe](https://forge.puppet.com/pdxcat/nrpe)
 
 It is licensed under the Apache License, Version 2.0.
diff --git a/REFERENCE.md b/REFERENCE.md
new file mode 100644
index 0000000..5cacc7f
--- /dev/null
+++ b/REFERENCE.md
@@ -0,0 +1,464 @@
+# Reference
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+**Classes**
+
+_Public Classes_
+
+* [`nrpe`](#nrpe): Installs and configures NRPE
+
+_Private Classes_
+
+* `nrpe::config`: Configures NRPE
+* `nrpe::config::ssl`: Configures SSL for NRPE
+* `nrpe::install`: Installs required NRPE packages
+* `nrpe::params`: Sets defaults based on OS
+* `nrpe::service`: Manages the NRPE service
+
+**Defined types**
+
+* [`nrpe::command`](#nrpecommand): Installs NRPE commands
+* [`nrpe::plugin`](#nrpeplugin): Installs additional plugins for NRPE
+
+**Functions**
+
+_Public Functions_
+
+
+_Private Functions_
+
+* `nrpe::ssl_logging`: A function that outputs a string suitable for the nrpe.conf `ssl_logging` parameter.  The nrpe.conf documentation has the following to say...
+
+## Classes
+
+### nrpe
+
+Installs and configures NRPE
+
+* **See also**
+https://github.com/NagiosEnterprises/nrpe
+https://github.com/NagiosEnterprises/nrpe/blob/master/README.SSL.md
+
+#### Examples
+
+##### Basic usage
+
+```puppet
+class { 'nrpe':
+  allowed_hosts => [
+    '127.0.0.1',
+    'nagios.example.org',
+  ],
+}
+```
+
+##### With SSL
+
+```puppet
+class { 'nrpe':
+  allowed_hosts               => 'nagios.example.org',
+  ssl_cert_file_content       => file('profile/ssl/nagios.example.org.crt'),
+  ssl_privatekey_file_content => file('profile/ssl/nagios.example.org.key'),
+  ssl_cacert_file_content     => file('profile/ssl/GeoTrust_RSA_CA_2018.crt'),
+  ssl_client_certs            => 'require',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `nrpe` class.
+
+##### `allowed_hosts`
+
+Data type: `Array[Stdlib::Host]`
+
+Specifies the hosts that NRPE will accept connections from.
+
+Default value: ['127.0.0.1']
+
+##### `server_address`
+
+Data type: `Stdlib::IP::Address`
+
+Specifies the IP address of the inteface that NRPE should bind to. Useful when the system has more than one interface.
+
+Default value: '0.0.0.0'
+
+##### `command_timeout`
+
+Data type: `Integer[0]`
+
+Specifies the maximum number of seconds that the NRPE daemon will allow plugins to finish executing before killing them off.
+
+Default value: 60
+
+##### `package_name`
+
+Data type: `Variant[String[1], Array[String[1]]]`
+
+The package name or array of package names that will be installed. The default is often fine, but you may wish to set this to install extra packages like `nrpe-selinux`.
+
+Default value: $nrpe::params::nrpe_packages
+
+##### `manage_package`
+
+Data type: `Boolean`
+
+By default, set to `true` and the `nrpe` class will manage the OS package(s).
+
+Default value: `true`
+
+##### `purge`
+
+Data type: `Boolean`
+
+When set to true, the module will purge any unmanaged commands from the NRPE includedir.
+
+Default value: `false`
+
+##### `dont_blame_nrpe`
+
+Data type: `Boolean`
+
+Determines whether or not the NRPE daemon will allow clients to specify arguments to commands that are executed. ENABLING THIS OPTION IS A SECURITY RISK!
+
+Default value: $nrpe::params::dont_blame_nrpe
+
+##### `log_facility`
+
+Data type: `Nrpe::Syslogfacility`
+
+The syslog facility that should be used for logging purposes.
+
+Default value: $nrpe::params::log_facility
+
+##### `server_port`
+
+Data type: `Stdlib::Port::Unprivileged`
+
+The port that NRPE should listen for connections on.
+
+Default value: $nrpe::params::server_port
+
+##### `command_prefix`
+
+Data type: `Optional[Stdlib::Absolutepath]`
+
+This option allows you to prefix all commands with a user-defined string.  Although often used to run all commands with sudo, `nrpe::command` has dedicated `sudo` parameters for this.
+
+Default value: $nrpe::params::command_prefix
+
+##### `debug`
+
+Data type: `Boolean`
+
+This option determines whether or not debugging messages are logged to the syslog facility.
+
+Default value: $nrpe::params::debug
+
+##### `connection_timeout`
+
+Data type: `Integer[0]`
+
+Specifies the maximum number of seconds that the NRPE daemon will wait for a connection to be established before exiting.
+
+Default value: $nrpe::params::connection_timeout
+
+##### `allow_bash_command_substitution`
+
+Data type: `Optional[Boolean]`
+
+Determines whether or not the NRPE daemon will allow clients to specify arguments that contain bash command substitutions of the form `$(...)`. ** ENABLING THIS OPTION IS A HIGH SECURITY RISK! **
+
+Default value: $nrpe::params::allow_bash_command_substitution
+
+##### `nrpe_user`
+
+Data type: `String[1]`
+
+Determines the effective user that the NRPE daemon should run as.
+
+Default value: $nrpe::params::nrpe_user
+
+##### `nrpe_group`
+
+Data type: `String[1]`
+
+Determines the effective group that the NRPE daemon should run as.
+
+Default value: $nrpe::params::nrpe_group
+
+##### `nrpe_pid_file`
+
+Data type: `Stdlib::Absolutepath`
+
+The name of the file in which the NRPE daemon should write it's process ID number.
+
+Default value: $nrpe::params::nrpe_pid_file
+
+##### `command_file_default_mode`
+
+Data type: `Stdlib::Filemode`
+
+The default file mode to use when creating NRPE command files in the includedir.
+
+Default value: '0644'
+
+##### `supplementary_groups`
+
+Data type: `Array[String[1]]`
+
+If set, the `nrpe_user` will be added to these supplementary groups.
+
+Default value: []
+
+##### `nrpe_ssl_dir`
+
+Data type: `Stdlib::Absolutepath`
+
+The directory that SSL certificates and keys will be created in.
+
+Default value: $nrpe::params::nrpe_ssl_dir
+
+##### `ssl_cert_file_content`
+
+Data type: `Optional[String[1]]`
+
+A string containing the SSL Certificate.
+
+Default value: `undef`
+
+##### `ssl_privatekey_file_content`
+
+Data type: `Optional[String[1]]`
+
+A string containing the SSL private **KEY**.  It is recommended to source this parameter from hiera and use EYAML or similar to encrypt the data.
+
+Default value: `undef`
+
+##### `ssl_cacert_file_content`
+
+Data type: `Optional[String[1]]`
+
+A string containing the SSL CA Cert file contents.
+
+Default value: `undef`
+
+##### `ssl_version`
+
+Data type: `Nrpe::Sslversion`
+
+The SSL Version to use.  The default of `TLSv1.2+` is the most secure option available at time of writing.  Avoid having to set it to a lower value if possible.
+
+Default value: $nrpe::params::ssl_version
+
+##### `ssl_ciphers`
+
+Data type: `Array[String[1]]`
+
+An array of ciphers that should be allowed by NRPE.  The defaults are for RSA keys and were taken from https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices.
+
+Default value: $nrpe::params::ssl_ciphers
+
+##### `ssl_client_certs`
+
+Data type: `Enum['no','ask','require']`
+
+This options determines client certificate usage.
+
+Default value: $nrpe::params::ssl_client_certs
+
+##### `ssl_log_startup_params`
+
+Data type: `Boolean`
+
+Whether to log startup SSL/TLS parameters.
+
+Default value: `false`
+
+##### `ssl_log_remote_ip`
+
+Data type: `Boolean`
+
+Whether to log remote IP address of SSL client.
+
+Default value: `false`
+
+##### `ssl_log_protocol_version`
+
+Data type: `Boolean`
+
+Whether to log SSL/TLS version of connections.
+
+Default value: `false`
+
+##### `ssl_log_cipher`
+
+Data type: `Boolean`
+
+Whether to log which encryption cipher is being used for SSL connections.
+
+Default value: `false`
+
+##### `ssl_log_client_cert`
+
+Data type: `Boolean`
+
+Whether to log if an SSL client has presented a certificate.
+
+Default value: `false`
+
+##### `ssl_log_client_cert_details`
+
+Data type: `Boolean`
+
+Whether to log details of client SSL certificates.
+
+Default value: `false`
+
+##### `config`
+
+Data type: `Stdlib::Absolutepath`
+
+**Private** You should not need to override this parameter.
+
+Default value: $nrpe::params::nrpe_config
+
+##### `include_dir`
+
+Data type: `Stdlib::Absolutepath`
+
+**Private** You should not need to override this parameter.
+
+Default value: $nrpe::params::nrpe_include_dir
+
+##### `provider`
+
+Data type: `Optional[String[1]]`
+
+**Private** You should not need to override this parameter.
+
+Default value: $nrpe::params::nrpe_provider
+
+##### `service_name`
+
+Data type: `String[1]`
+
+**Private** You should not need to override this parameter.
+
+Default value: $nrpe::params::nrpe_service
+
+## Defined types
+
+### nrpe::command
+
+Installs NRPE commands
+
+#### Examples
+
+##### Install a command called `check_users`
+
+```puppet
+nrpe::command { 'check_users':
+  ensure  => present,
+  command => 'check_users -w 5 -c 10',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `nrpe::command` defined type.
+
+##### `name`
+
+The name of the command.
+
+##### `command`
+
+Data type: `String[1]`
+
+The command plugin to run and its arguments.
+
+##### `ensure`
+
+Data type: `Enum['present', 'absent']`
+
+Whether to install or remove the command.
+
+Default value: present
+
+##### `file_mode`
+
+Data type: `Optional[Stdlib::Filemode]`
+
+The mode to use for the command file.  By default, this parameter is `undef`, and the command file will use `$nrpe::command_file_default_mode`.
+
+Default value: `undef`
+
+##### `sudo`
+
+Data type: `Boolean`
+
+Whether the command should use sudo.
+
+Default value: `false`
+
+##### `sudo_user`
+
+Data type: `String[1]`
+
+The user to run the command as when using sudo.
+
+Default value: 'root'
+
+### nrpe::plugin
+
+Installs additional plugins for NRPE
+
+#### Examples
+
+##### Install a `check_mem` plugin from a file hosted in your `site` module
+
+```puppet
+nrpe::plugin { 'check_mem':
+  ensure => present,
+  source => 'puppet:///modules/site/nrpe/check_mem',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `nrpe::plugin` defined type.
+
+##### `name`
+
+The name of the plugin.
+
+##### `ensure`
+
+Data type: `Enum['present', 'absent']`
+
+Whether to install or remove the plugin.
+
+Default value: present
+
+##### `content`
+
+Data type: `Optional[String[1]]`
+
+Defines the actual content of the plugin file.  Should not be used in conjunction with `source`.
+
+Default value: `undef`
+
+##### `source`
+
+Data type: `Optional[Stdlib::Filesource]`
+
+Defines the source of the plugin file. Should not be used in conjunction with `content`.
+
+Default value: `undef`
+
+## Functions
+
diff --git a/manifests/command.pp b/manifests/command.pp
index 6665723..c849d3d 100644
--- a/manifests/command.pp
+++ b/manifests/command.pp
@@ -13,7 +13,7 @@
 # @param ensure
 #   Whether to install or remove the command.
 # @param file_mode
-#   The mode to use for the command file.  Defaults to `$nrpe::command_file_default_mode`.
+#   The mode to use for the command file.  By default, this parameter is `undef`, and the command file will use `$nrpe::command_file_default_mode`.
 # @param sudo
 #   Whether the command should use sudo.
 # @param sudo_user
diff --git a/manifests/config.pp b/manifests/config.pp
index ba48d84..20d6240 100644
--- a/manifests/config.pp
+++ b/manifests/config.pp
@@ -1,3 +1,5 @@
+# @summary Configures NRPE
+#
 # @api private
 class nrpe::config
 {
@@ -55,6 +57,6 @@
     ensure  => directory,
     name    => $nrpe::include_dir,
     purge   => $nrpe::purge,
-    recurse => $nrpe::recurse,
+    recurse => $nrpe::purge,
   }
 }
diff --git a/manifests/config/ssl.pp b/manifests/config/ssl.pp
index 604fcb5..a2e5fdc 100644
--- a/manifests/config/ssl.pp
+++ b/manifests/config/ssl.pp
@@ -1,3 +1,5 @@
+# @summary Configures SSL for NRPE
+#
 # @api private
 class nrpe::config::ssl
 {
diff --git a/manifests/init.pp b/manifests/init.pp
index a9c3166..8e9a913 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -1,19 +1,106 @@
 # @summary Installs and configures NRPE
+#
+# @example Basic usage
+#   class { 'nrpe':
+#     allowed_hosts => [
+#       '127.0.0.1',
+#       'nagios.example.org',
+#     ],
+#   }
+#
+# @see https://github.com/NagiosEnterprises/nrpe
+#
+# @example With SSL
+#   class { 'nrpe':
+#     allowed_hosts               => 'nagios.example.org',
+#     ssl_cert_file_content       => file('profile/ssl/nagios.example.org.crt'),
+#     ssl_privatekey_file_content => file('profile/ssl/nagios.example.org.key'),
+#     ssl_cacert_file_content     => file('profile/ssl/GeoTrust_RSA_CA_2018.crt'),
+#     ssl_client_certs            => 'require',
+#   }
+#
+# @see https://github.com/NagiosEnterprises/nrpe/blob/master/README.SSL.md
+#
+# @param allowed_hosts
+#   Specifies the hosts that NRPE will accept connections from.
+# @param server_address
+#   Specifies the IP address of the inteface that NRPE should bind to. Useful when the system has more than one interface.
+# @param command_timeout
+#   Specifies the maximum number of seconds that the NRPE daemon will allow plugins to finish executing before killing them off.
+# @param package_name
+#   The package name or array of package names that will be installed. The default is often fine, but you may wish to set this to install extra packages like `nrpe-selinux`.
+# @param manage_package
+#   By default, set to `true` and the `nrpe` class will manage the OS package(s).
+# @param purge
+#   When set to true, the module will purge any unmanaged commands from the NRPE includedir.
+# @param dont_blame_nrpe
+#   Determines whether or not the NRPE daemon will allow clients to specify arguments to commands that are executed. ENABLING THIS OPTION IS A SECURITY RISK!
+# @param log_facility
+#   The syslog facility that should be used for logging purposes.
+# @param server_port
+#   The port that NRPE should listen for connections on.
+# @param command_prefix
+#   This option allows you to prefix all commands with a user-defined string.  Although often used to run all commands with sudo, `nrpe::command` has dedicated `sudo` parameters for this.
+# @param debug
+#   This option determines whether or not debugging messages are logged to the syslog facility.
+# @param connection_timeout
+#   Specifies the maximum number of seconds that the NRPE daemon will wait for a connection to be established before exiting.
+# @param allow_bash_command_substitution
+#   Determines whether or not the NRPE daemon will allow clients to specify arguments that contain bash command substitutions of the form `$(...)`. ** ENABLING THIS OPTION IS A HIGH SECURITY RISK! **
+# @param nrpe_user
+#   Determines the effective user that the NRPE daemon should run as.
+# @param nrpe_group
+#   Determines the effective group that the NRPE daemon should run as.
+# @param nrpe_pid_file
+#   The name of the file in which the NRPE daemon should write it's process ID number.
+# @param command_file_default_mode
+#   The default file mode to use when creating NRPE command files in the includedir.
+# @param supplementary_groups
+#   If set, the `nrpe_user` will be added to these supplementary groups.
+# @param nrpe_ssl_dir
+#   The directory that SSL certificates and keys will be created in.
+# @param ssl_cert_file_content
+#   A string containing the SSL Certificate.
+# @param ssl_privatekey_file_content
+#   A string containing the SSL private **KEY**.  It is recommended to source this parameter from hiera and use EYAML or similar to encrypt the data.
+# @param ssl_cacert_file_content
+#   A string containing the SSL CA Cert file contents.
+# @param ssl_version
+#   The SSL Version to use.  The default of `TLSv1.2+` is the most secure option available at time of writing.  Avoid having to set it to a lower value if possible.
+# @param ssl_ciphers
+#   An array of ciphers that should be allowed by NRPE.  The defaults are for RSA keys and were taken from https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices.
+# @param ssl_client_certs
+#   This options determines client certificate usage.
+# @param ssl_log_startup_params
+#   Whether to log startup SSL/TLS parameters.
+# @param ssl_log_remote_ip
+#   Whether to log remote IP address of SSL client.
+# @param ssl_log_protocol_version
+#   Whether to log SSL/TLS version of connections.
+# @param ssl_log_cipher
+#   Whether to log which encryption cipher is being used for SSL connections.
+# @param ssl_log_client_cert
+#   Whether to log if an SSL client has presented a certificate.
+# @param ssl_log_client_cert_details
+#   Whether to log details of client SSL certificates.
+# @param config
+#   **Private** You should not need to override this parameter.
+# @param include_dir
+#   **Private** You should not need to override this parameter.
+# @param provider
+#   **Private** You should not need to override this parameter.
+# @param service_name
+#   **Private** You should not need to override this parameter.
 class nrpe (
   Array[Stdlib::Host]                  $allowed_hosts                   = ['127.0.0.1'],
   Stdlib::IP::Address                  $server_address                  = '0.0.0.0',
   Integer[0]                           $command_timeout                 = 60,
-  Stdlib::Absolutepath                 $config                          = $nrpe::params::nrpe_config,
-  Stdlib::Absolutepath                 $include_dir                     = $nrpe::params::nrpe_include_dir,
   Variant[String[1], Array[String[1]]] $package_name                    = $nrpe::params::nrpe_packages,
-  Optional[String[1]]                  $provider                        = $nrpe::params::nrpe_provider,
   Boolean                              $manage_package                  = true,
-  Optional[Boolean]                    $purge                           = undef,
-  Optional[Boolean]                    $recurse                         = undef,
-  String[1]                            $service_name                    = $nrpe::params::nrpe_service,
+  Boolean                              $purge                           = false,
   Boolean                              $dont_blame_nrpe                 = $nrpe::params::dont_blame_nrpe,
   Nrpe::Syslogfacility                 $log_facility                    = $nrpe::params::log_facility,
-  Stdlib::Port                         $server_port                     = $nrpe::params::server_port,
+  Stdlib::Port::Unprivileged           $server_port                     = $nrpe::params::server_port,
   Optional[Stdlib::Absolutepath]       $command_prefix                  = $nrpe::params::command_prefix,
   Boolean                              $debug                           = $nrpe::params::debug,
   Integer[0]                           $connection_timeout              = $nrpe::params::connection_timeout,
@@ -36,6 +123,12 @@
   Boolean                              $ssl_log_client_cert_details     = false,
   Stdlib::Filemode                     $command_file_default_mode       = '0644',
   Array[String[1]]                     $supplementary_groups            = [],
+
+  # Private parameters.  You shouldn't need to override these.
+  Stdlib::Absolutepath                 $config                          = $nrpe::params::nrpe_config,
+  Stdlib::Absolutepath                 $include_dir                     = $nrpe::params::nrpe_include_dir,
+  Optional[String[1]]                  $provider                        = $nrpe::params::nrpe_provider,
+  String[1]                            $service_name                    = $nrpe::params::nrpe_service,
 ) inherits nrpe::params {
 
   # Extra validation
diff --git a/manifests/install.pp b/manifests/install.pp
index e4fd47b..55e01ad 100644
--- a/manifests/install.pp
+++ b/manifests/install.pp
@@ -1,3 +1,5 @@
+# @summary Installs required NRPE packages
+#
 # @api private
 class nrpe::install
 {
diff --git a/manifests/params.pp b/manifests/params.pp
index 3bf9d02..30833aa 100644
--- a/manifests/params.pp
+++ b/manifests/params.pp
@@ -1,4 +1,6 @@
+# @summary Sets defaults based on OS
 #
+# @api private
 class nrpe::params {
 
   $nrpe_provider = $::osfamily ? {
diff --git a/manifests/service.pp b/manifests/service.pp
index 442bc2f..ce0577a 100644
--- a/manifests/service.pp
+++ b/manifests/service.pp
@@ -1,3 +1,5 @@
+# @summary Manages the NRPE service
+#
 # @api private
 class nrpe::service
 {