From b0dd95e7ce099f2bf9c1d4b0cd2041459ca162c0 Mon Sep 17 00:00:00 2001 From: Hugo Haakseth Date: Fri, 24 May 2024 23:54:40 +0200 Subject: [PATCH] Convert inline docs to Puppet Strings --- REFERENCE.md | 273 ++++++++++++++++++++++++++++++++++++++++++++ manifests/ca.pp | 38 +++--- manifests/init.pp | 60 +++++----- manifests/params.pp | 6 +- 4 files changed, 324 insertions(+), 53 deletions(-) create mode 100644 REFERENCE.md diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..14a9484 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,273 @@ +# Reference + + + +## Table of Contents + +### Classes + +#### Public Classes + +* [`ca_cert`](#ca_cert): This module manages the user installed certificate authority (CA) +certificates installed on the server. It does not manage operating +system defaults CA certificates. + +#### Private Classes + +* `ca_cert::params`: OS dependant parameter defaults + +### Defined types + +* [`ca_cert::ca`](#ca_cert--ca): Manage a CA Certificate on a system. This cannot manage pre-installed +operating system CAs. + +## Classes + +### `ca_cert` + +This module manages the user installed certificate authority (CA) +certificates installed on the server. It does not manage operating +system defaults CA certificates. + +#### Examples + +##### Basic usage + +```puppet +class { 'ca_cert': } + +class { 'ca_cert': + manage_all_user_CAs => true, +} +``` + +#### Parameters + +The following parameters are available in the `ca_cert` class: + +* [`package_name`](#-ca_cert--package_name) +* [`update_cmd`](#-ca_cert--update_cmd) +* [`trusted_cert_dir`](#-ca_cert--trusted_cert_dir) +* [`distrusted_cert_dir`](#-ca_cert--distrusted_cert_dir) +* [`cert_dir_group`](#-ca_cert--cert_dir_group) +* [`cert_dir_mode`](#-ca_cert--cert_dir_mode) +* [`ca_file_group`](#-ca_cert--ca_file_group) +* [`ca_file_mode`](#-ca_cert--ca_file_mode) +* [`ca_file_extension`](#-ca_cert--ca_file_extension) +* [`package_ensure`](#-ca_cert--package_ensure) +* [`always_update_certs`](#-ca_cert--always_update_certs) +* [`purge_unmanaged_CAs`](#-ca_cert--purge_unmanaged_CAs) +* [`install_package`](#-ca_cert--install_package) +* [`ca_certs`](#-ca_cert--ca_certs) + +##### `package_name` + +Data type: `String[1]` + +The name of the package(s) to be installed. + +Default value: `$ca_cert::params::package_name` + +##### `update_cmd` + +Data type: `String[1]` + +Command to be used to update CA certificates. + +Default value: `$ca_cert::params::update_cmd` + +##### `trusted_cert_dir` + +Data type: `String[1]` + +Absolute directory path to the folder containing trusted certificates. + +Default value: `$ca_cert::params::trusted_cert_dir` + +##### `distrusted_cert_dir` + +Data type: `Optional[String[1]]` + +Absolute directory path to the folder containing distrusted certificates (OS dependent). + +Default value: `$ca_cert::params::distrusted_cert_dir` + +##### `cert_dir_group` + +Data type: `String[1]` + +The installed trusted certificate's POSIX group permissions. This uses +the same syntax as Puppet's native file resource's "group" parameter. +It defaults to 'system' on AIX, to 'sys' on Solaris, to 'staff' on +Ubuntu/Debian, and to 'root' in other cases. + +Default value: `$ca_cert::params::cert_dir_group` + +##### `cert_dir_mode` + +Data type: `String[1]` + +The installed trusted certificate's POSIX filesystem permissions. This uses +the same syntax as Puppet's native file resource's "mode" parameter. +It defaults to '2665' on Debian, and to '0755' on other cases. + +Default value: `$ca_cert::params::cert_dir_mode` + +##### `ca_file_group` + +Data type: `String[1]` + +The installed CA certificate's POSIX group permissions. This uses +the same syntax as Puppet's native file resource's "group" parameter. +(defaults to 'root' with the exeption of AIX which defaults to 'system') + +Default value: `$ca_cert::params::ca_file_group` + +##### `ca_file_mode` + +Data type: `String[1]` + +The installed CA certificate's POSIX filesystem permissions. This uses +the same syntax as Puppet's native file resource's "mode" parameter. +(defaults to '0444', i.e. world-readable) + +Default value: `$ca_cert::params::ca_file_mode` + +##### `ca_file_extension` + +Data type: `String[1]` + +File extenstion for the certificate. + +Default value: `$ca_cert::params::ca_file_extension` + +##### `package_ensure` + +Data type: `String[1]` + +The ensure parameter to pass to the package resource. + +Default value: `'installed'` + +##### `always_update_certs` + +Data type: `Boolean` + +Run the appropriate update CA certificates command for your operating +system on every Puppet run whether it is needed or not. + +Default value: `false` + +##### `purge_unmanaged_CAs` + +Data type: `Boolean` + +When set to true (default: false), user installed CA +certificates (in the appropriate directories) not managed by this +module will be purged. + +Default value: `false` + +##### `install_package` + +Data type: `Boolean` + +Whether or not this module should install the ca_certificates package. +The package contains the system default (typically Mozilla) CA +certificates, as well as the tools required for managing other installed +CA certificates. + +Default value: `true` + +##### `ca_certs` + +Data type: `Hash` + +A hash of CA certificates that should be installed as part of the class +declaration. + +Default value: `{}` + +## Defined types + +### `ca_cert::ca` + +Manage a CA Certificate on a system. This cannot manage pre-installed +operating system CAs. + +#### Examples + +##### + +```puppet +ca_cert::ca { 'globalsign_org_intermediate': + source => 'http://secure.globalsign.com/cacert/gsorganizationvalsha2g2r1.crt', +} +``` + +#### Parameters + +The following parameters are available in the `ca_cert::ca` defined type: + +* [`ca_text`](#-ca_cert--ca--ca_text) +* [`source`](#-ca_cert--ca--source) +* [`ensure`](#-ca_cert--ca--ensure) +* [`verify_https_cert`](#-ca_cert--ca--verify_https_cert) +* [`checksum`](#-ca_cert--ca--checksum) +* [`checksum_type`](#-ca_cert--ca--checksum_type) + +##### `ca_text` + +Data type: `Optional[String]` + +The text of the CA certificate to install. Required if text is the source +(default). If a different source is specified this parameter is ignored. + +Default value: `undef` + +##### `source` + +Data type: `String` + +Where the CA certificate should be retrieved from. text, http, https, ftp, +file, and puppet protocols/sources are supported. If text, then the ca_text parameter +is also required. Defaults to text. + +Default value: `'text'` + +##### `ensure` + +Data type: `String` + +Whether or not the CA certificate should be on a system or not. Valid +values are trusted, present, distrusted, and absent. Note: untrusted is +not supported on Debian based systems - using it will log a warning +and treat it the same as absent. (defaults to trusted) + +Default value: `'trusted'` + +##### `verify_https_cert` + +Data type: `Boolean` + +When retrieving a certificate whether or not to validate the CA of the +source. (defaults to true) + +Default value: `true` + +##### `checksum` + +Data type: `Optional[String]` + +The checksum of the file. (defaults to undef) + +Default value: `undef` + +##### `checksum_type` + +Data type: `Optional[String[1]]` + +The type of file checksum. (defauts to undef) + +Default value: `undef` + diff --git a/manifests/ca.pp b/manifests/ca.pp index f5bcde4..4387cca 100644 --- a/manifests/ca.pp +++ b/manifests/ca.pp @@ -1,40 +1,42 @@ -# ca.pp +# @summary +# Manage a CA Certificate on a system. This cannot manage pre-installed +# operating system CAs. # -# Manage a CA Certificate on a system. This cannot manage pre-installed -# operating system CAs. +# @example +# ca_cert::ca { 'globalsign_org_intermediate': +# source => 'http://secure.globalsign.com/cacert/gsorganizationvalsha2g2r1.crt', +# } # -# === Parameters -# -# [*ca_text*] +# @param ca_text # The text of the CA certificate to install. Required if text is the source # (default). If a different source is specified this parameter is ignored. -# [*source*] +# +# @param source # Where the CA certificate should be retrieved from. text, http, https, ftp, # file, and puppet protocols/sources are supported. If text, then the ca_text parameter # is also required. Defaults to text. -# [*ensure*] +# +# @param ensure # Whether or not the CA certificate should be on a system or not. Valid # values are trusted, present, distrusted, and absent. Note: untrusted is # not supported on Debian based systems - using it will log a warning # and treat it the same as absent. (defaults to trusted) -# [*verify_https_cert*] +# +# @param verify_https_cert # When retrieving a certificate whether or not to validate the CA of the # source. (defaults to true) -# [*checksum*] +# +# @param checksum # The checksum of the file. (defaults to undef) -# [*checksum_type*] -# The type of file checksum. (defauts to undef) # -# === Examples +# @param checksum_type +# The type of file checksum. (defauts to undef) # -# ca_cert::ca { 'globalsign_org_intermediate': -# source => 'http://secure.globalsign.com/cacert/gsorganizationvalsha2g2r1.crt', -# } define ca_cert::ca ( - Optional[String] $ca_text = undef, - String $source = 'text', String $ensure = 'trusted', + String $source = 'text', Boolean $verify_https_cert = true, + Optional[String] $ca_text = undef, Optional[String] $checksum = undef, Optional[String[1]] $checksum_type = undef, ) { diff --git a/manifests/init.pp b/manifests/init.pp index 72a01ad..78ca931 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,80 +1,72 @@ -# == Class: ca_cert +# @summary +# This module manages the user installed certificate authority (CA) +# certificates installed on the server. It does not manage operating +# system defaults CA certificates. # -# This module manages the user installed certificate authority (CA) -# certificates installed on the server. It does not manage operating -# system defaults CA certificates. +# @example Basic usage +# class { 'ca_cert': } # -# === Parameters +# class { 'ca_cert': +# manage_all_user_CAs => true, +# } # -# [*package_name*] -# The name of the package(s) to be installed +# @param package_name +# The name of the package(s) to be installed. # -# [*update_cmd*] +# @param update_cmd # Command to be used to update CA certificates. # -# [*trusted_cert_dir*] +# @param trusted_cert_dir # Absolute directory path to the folder containing trusted certificates. # -# [*distrusted_cert_dir*] +# @param distrusted_cert_dir # Absolute directory path to the folder containing distrusted certificates (OS dependent). # -# [*cert_dir_group*] +# @param cert_dir_group # The installed trusted certificate's POSIX group permissions. This uses # the same syntax as Puppet's native file resource's "group" parameter. # It defaults to 'system' on AIX, to 'sys' on Solaris, to 'staff' on # Ubuntu/Debian, and to 'root' in other cases. # -# [*cert_dir_mode*] +# @param cert_dir_mode # The installed trusted certificate's POSIX filesystem permissions. This uses # the same syntax as Puppet's native file resource's "mode" parameter. # It defaults to '2665' on Debian, and to '0755' on other cases. # -# [*ca_file_group*] +# @param ca_file_group # The installed CA certificate's POSIX group permissions. This uses # the same syntax as Puppet's native file resource's "group" parameter. # (defaults to 'root' with the exeption of AIX which defaults to 'system') # -# [*ca_file_mode*] +# @param ca_file_mode # The installed CA certificate's POSIX filesystem permissions. This uses # the same syntax as Puppet's native file resource's "mode" parameter. # (defaults to '0444', i.e. world-readable) # -# [*ca_file_extension*] +# @param ca_file_extension # File extenstion for the certificate. # -# [*package_ensure*] -# The ensure parameter to pass to the package resource +# @param package_ensure +# The ensure parameter to pass to the package resource. # -# [*always_update_certs*] +# @param always_update_certs # Run the appropriate update CA certificates command for your operating # system on every Puppet run whether it is needed or not. # -# [*purge_unmanaged_CAs*] +# @param purge_unmanaged_CAs # When set to true (default: false), user installed CA # certificates (in the appropriate directories) not managed by this # module will be purged. # -# [*install_package*] +# @param install_package # Whether or not this module should install the ca_certificates package. # The package contains the system default (typically Mozilla) CA # certificates, as well as the tools required for managing other installed # CA certificates. # -# [*ca_certs*] +# @param ca_certs # A hash of CA certificates that should be installed as part of the class -# declaration -# -# === Examples -# -# class { 'ca_cert': } -# -# class { 'ca_cert': -# manage_all_user_CAs => true, -# } -# -# === Authors -# -# Phil Fenstermacher +# declaration. # class ca_cert ( String[1] $package_name = $ca_cert::params::package_name, diff --git a/manifests/params.pp b/manifests/params.pp index 73aa926..b1e325d 100644 --- a/manifests/params.pp +++ b/manifests/params.pp @@ -1,4 +1,8 @@ -# Private class +# @summary +# OS dependant parameter defaults +# +# @api private +# class ca_cert::params { case $facts['os']['family'] { 'Debian': {