From 4808b457342b68d424679d9d2244b20e67b480df Mon Sep 17 00:00:00 2001 From: Hugo Haakseth Date: Thu, 23 May 2024 10:52:52 +0200 Subject: [PATCH 1/2] Move and use params only in ca_certs class --- manifests/ca.pp | 41 ++++++------------------ manifests/init.pp | 76 ++++++++++++++++++++++++++++++++++----------- manifests/params.pp | 12 ++++--- 3 files changed, 75 insertions(+), 54 deletions(-) diff --git a/manifests/ca.pp b/manifests/ca.pp index 649a1c4..f5bcde4 100644 --- a/manifests/ca.pp +++ b/manifests/ca.pp @@ -24,14 +24,6 @@ # The checksum of the file. (defaults to undef) # [*checksum_type*] # The type of file checksum. (defauts to undef) -# [*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*] -# 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) # # === Examples # @@ -45,23 +37,8 @@ Boolean $verify_https_cert = true, Optional[String] $checksum = undef, Optional[String[1]] $checksum_type = undef, - Optional[String] $ca_file_group = undef, - Optional[String] $ca_file_mode = undef, ) { include ca_cert - include ca_cert::params - - if $ca_file_group == undef { - $file_group = $ca_cert::params::ca_file_group - } else { - $file_group = $ca_file_group - } - - if $ca_file_mode == undef { - $file_mode = $ca_cert::params::ca_file_mode - } else { - $file_mode = $ca_file_mode - } if ($ensure == 'trusted' or $ensure == 'distrusted') and $source == 'text' and !$ca_text { fail('ca_text is required if source is set to text') @@ -93,11 +70,11 @@ } # Determine Full Resource Name - $resource_name = "${name}.${ca_cert::params::ca_file_extension}" + $resource_name = "${name}.${ca_cert::ca_file_extension}" $ca_cert = $adjusted_ensure ? { - 'distrusted' => "${ca_cert::params::distrusted_cert_dir}/${resource_name}", - default => "${ca_cert::params::trusted_cert_dir}/${resource_name}", + 'distrusted' => "${ca_cert::distrusted_cert_dir}/${resource_name}", + default => "${ca_cert::trusted_cert_dir}/${resource_name}", } case $adjusted_ensure { @@ -111,8 +88,8 @@ source => $source, path => $ca_cert, owner => 'root', - group => $file_group, - mode => $file_mode, + group => $ca_cert::ca_file_group, + mode => $ca_cert::ca_file_mode, notify => Exec['ca_cert_update'], } } @@ -133,8 +110,8 @@ source => $source_path, path => $ca_cert, owner => 'root', - group => $file_group, - mode => $file_mode, + group => $ca_cert::ca_file_group, + mode => $ca_cert::ca_file_mode, notify => Exec['ca_cert_update'], } } @@ -144,8 +121,8 @@ content => $ca_text, path => $ca_cert, owner => 'root', - group => $file_group, - mode => $file_mode, + group => $ca_cert::ca_file_group, + mode => $ca_cert::ca_file_mode, notify => Exec['ca_cert_update'], } } diff --git a/manifests/init.pp b/manifests/init.pp index c9fb9eb..72a01ad 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -6,25 +6,63 @@ # # === Parameters # +# [*package_name*] +# The name of the package(s) to be installed +# +# [*update_cmd*] +# Command to be used to update CA certificates. +# +# [*trusted_cert_dir*] +# Absolute directory path to the folder containing trusted certificates. +# +# [*distrusted_cert_dir*] +# Absolute directory path to the folder containing distrusted certificates (OS dependent). +# +# [*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*] +# 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*] +# 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*] +# 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*] +# File extenstion for the certificate. +# +# [*package_ensure*] +# The ensure parameter to pass to the package resource +# # [*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*] # When set to true (default: false), user installed CA # certificates (in the appropriate directories) not managed by this # module will be purged. +# # [*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*] # A hash of CA certificates that should be installed as part of the class # declaration -# [*package_ensure*] -# The ensure parameter to pass to the package resource -# [*package_name*] -# The name of the package(s) to be installed # # === Examples # @@ -38,27 +76,30 @@ # # Phil Fenstermacher # -# lint:ignore:variable_is_lowercase class ca_cert ( + String[1] $package_name = $ca_cert::params::package_name, + String[1] $update_cmd = $ca_cert::params::update_cmd, + String[1] $trusted_cert_dir = $ca_cert::params::trusted_cert_dir, + Optional[String[1]] $distrusted_cert_dir = $ca_cert::params::distrusted_cert_dir, + String[1] $cert_dir_group = $ca_cert::params::cert_dir_group, + String[1] $ca_file_group = $ca_cert::params::ca_file_group, + String[1] $cert_dir_mode = $ca_cert::params::cert_dir_mode, + String[1] $ca_file_mode = $ca_cert::params::ca_file_mode, + String[1] $ca_file_extension = $ca_cert::params::ca_file_extension, + String[1] $package_ensure = 'installed', Boolean $always_update_certs = false, - Boolean $purge_unmanaged_CAs = false, # lint:ignore:variable_contains_upcase - Boolean $install_package = true, - Hash $ca_certs = {}, - String $package_ensure = 'installed', - String $package_name = $ca_cert::params::package_name, + Boolean $purge_unmanaged_CAs = false, # lint:ignore:variable_contains_upcase lint:ignore:variable_is_lowercase + Boolean $install_package = true, + Hash $ca_certs = {}, ) inherits ca_cert::params { - $trusted_cert_dir = $ca_cert::params::trusted_cert_dir - $cert_dir_group = $ca_cert::params::cert_dir_group - $cert_dir_mode = $ca_cert::params::cert_dir_mode - file { 'trusted_certs': ensure => directory, path => $trusted_cert_dir, owner => 'root', group => $cert_dir_group, mode => $cert_dir_mode, - purge => $purge_unmanaged_CAs, # lint:ignore:variable_contains_upcase - recurse => $purge_unmanaged_CAs, # lint:ignore:variable_contains_upcase + purge => $purge_unmanaged_CAs, # lint:ignore:variable_contains_upcase lint:ignore:variable_is_lowercase + recurse => $purge_unmanaged_CAs, # lint:ignore:variable_contains_upcase lint:ignore:variable_is_lowercase notify => Exec['ca_cert_update'], } @@ -75,10 +116,9 @@ } exec { 'ca_cert_update': - command => $ca_cert::params::update_cmd, + command => $update_cmd, logoutput => 'on_failure', refreshonly => !$always_update_certs, path => ['/usr/sbin', '/usr/bin', '/bin'], } } -# lint:endignore:variable_is_lowercase diff --git a/manifests/params.pp b/manifests/params.pp index ea483ad..73aa926 100644 --- a/manifests/params.pp +++ b/manifests/params.pp @@ -3,6 +3,7 @@ case $facts['os']['family'] { 'Debian': { $trusted_cert_dir = '/usr/local/share/ca-certificates' + $distrusted_cert_dir = undef $update_cmd = 'update-ca-certificates' $cert_dir_group = 'staff' $ca_file_group = 'root' @@ -45,10 +46,11 @@ } 'Suse': { if $facts['os']['release']['major'] =~ /(10|11)/ { - $trusted_cert_dir = '/etc/ssl/certs' - $update_cmd = 'c_rehash' - $ca_file_extension = 'pem' - $package_name = 'openssl-certs' + $trusted_cert_dir = '/etc/ssl/certs' + $distrusted_cert_dir = undef + $update_cmd = 'c_rehash' + $ca_file_extension = 'pem' + $package_name = 'openssl-certs' } elsif versioncmp($facts['os']['release']['major'], '12') >= 0 { $trusted_cert_dir = '/etc/pki/trust/anchors' @@ -64,6 +66,7 @@ } 'AIX': { $trusted_cert_dir = '/var/ssl/certs' + $distrusted_cert_dir = undef $update_cmd = '/usr/bin/c_rehash' $cert_dir_group = 'system' $cert_dir_mode = '0755' @@ -75,6 +78,7 @@ 'Solaris': { if versioncmp($facts['os']['release']['major'], '11') >= 0 { $trusted_cert_dir = '/etc/certs/CA/' + $distrusted_cert_dir = undef $update_cmd = '/usr/sbin/svcadm restart /system/ca-certificates' $cert_dir_group = 'sys' $cert_dir_mode = '0755' From 9297cd8468bebb8221eaba6a721067b395169e6c Mon Sep 17 00:00:00 2001 From: Hugo Haakseth Date: Fri, 24 May 2024 23:54:40 +0200 Subject: [PATCH 2/2] Convert inline docs to Puppet Strings --- REFERENCE.md | 273 ++++++++++++++++++++++++++++++++++++++++++++ manifests/ca.pp | 38 +++--- manifests/init.pp | 62 +++++----- manifests/params.pp | 6 +- 4 files changed, 325 insertions(+), 54 deletions(-) create mode 100644 REFERENCE.md diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..8dbf81a --- /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 defined certificate authority (CA) +certificates on the server. On OSes that support a distrusted +folder the module also manages distrusting system default CA certificates. + +#### Private Classes + +* `ca_cert::params`: OS dependent parameter defaults + +### Defined types + +* [`ca_cert::ca`](#ca_cert--ca): Manage a user defined CA Certificate on a system. +On OSes that support distrusting pre-installed CAs this can be managed as well. + +## Classes + +### `ca_cert` + +This module manages the user defined certificate authority (CA) +certificates on the server. On OSes that support a distrusted +folder the module also manages distrusting system default 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. + +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 user defined CA Certificate on a system. +On OSes that support distrusting pre-installed CAs this can be managed as well. + +#### 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..ddfbdfa 100644 --- a/manifests/ca.pp +++ b/manifests/ca.pp @@ -1,40 +1,42 @@ -# ca.pp +# @summary +# Manage a user defined CA Certificate on a system. +# On OSes that support distrusting pre-installed CAs this can be managed as well. # -# 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..c746df1 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,80 +1,72 @@ -# == Class: ca_cert +# @summary +# This module manages the user defined certificate authority (CA) +# certificates on the server. On OSes that support a distrusted +# folder the module also manages distrusting system default 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*] -# Absolute directory path to the folder containing distrusted certificates (OS dependent). +# @param distrusted_cert_dir +# Absolute directory path to the folder containing distrusted certificates. # -# [*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..d925df8 100644 --- a/manifests/params.pp +++ b/manifests/params.pp @@ -1,4 +1,8 @@ -# Private class +# @summary +# OS dependent parameter defaults +# +# @api private +# class ca_cert::params { case $facts['os']['family'] { 'Debian': {