diff --git a/REFERENCE.md b/REFERENCE.md index 68be811..5904cba 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -1,245 +1,283 @@ # Reference ## Table of Contents ### Classes #### Public Classes * [`hitch`](#hitch): Manage the hitch TLS proxy #### Private Classes * `hitch::config`: Manage the hitch configuration, systemd configuration and default DH parameters. * `hitch::install`: Manage the hitch package and optionally a repository * `hitch::service`: Manage the hitch service ### Defined types * [`hitch::domain`](#hitchdomain): Add a TLS certificate and key for a domain ## Classes ### `hitch` Manage the hitch TLS proxy +#### Examples + +##### defaults + +```puppet +include hitch + +hitch::domain { 'example.com': + cacert_source => '/etc/pki/tls/certs/ca.pem', + cert_source => '/etc/pki/tls/certs/example.com.pem', + key_source => '/etc/pki/tls/private_keys/example.com.pem', +} +``` + #### Parameters The following parameters are available in the `hitch` class. ##### `package_name` Data type: `String` Package name for installing hitch. ##### `service_name` Data type: `String` Service name for the hitch service. ##### `user` Data type: `String` User running the service. ##### `group` Data type: `String` Group running the service. ##### `backend` Data type: `String` Where to proxy requests. ##### `config_file` Data type: `Stdlib::Absolutepath` Path to the hitch configuration file. ##### `file_owner` Data type: `String` User owning the configuration files. Defaults to "root". ##### `dhparams_file` Data type: `Stdlib::Absolutepath` Path to file for Diffie-Hellman parameters, which are shared by all domains. ##### `dhparams_content` Data type: `Optional[String]` Content for the DH parameter file. If unset, DH parameters will be generated on the node, which may take a long time. ##### `config_root` Data type: `Stdlib::Absolutepath` Configuration root directory. The hitch::domain defined type will place certificates here. ##### `purge_config_root` Data type: `Boolean` If true, will delete all unmanaged files from the config_root. Defaults to false. ##### `frontend` Data type: `Variant[String, Array]` The listening frontend(s) for hitch. ##### `manage_repo` Data type: `Boolean` If true, install the EPEL repository on RedHat OS family. ##### `write_proxy_v2` Data type: `Enum['on', 'off']` ##### `ciphers` Data type: `String` ##### `domains` Data type: `Optional[Hash]` ##### `workers` Data type: `Variant[Integer, Enum['auto']]` ##### `prefer_server_ciphers` Data type: `Enum['on','off']` ##### `alpn_protos` Data type: `Optional[String]` ##### `tls_protos` Data type: `Optional[String]` ## Defined types ### `hitch::domain` This define installs pem files to the config root, and configures them in the hitch config file. The CA certificate (if present), server certificate, key and DH parameters are concatenated, and placed in the hitch configuration. You can specify cacert, cert and key with either _content or _source suffix. -Parameters: +#### Examples + +##### website with TLS files from managed node + +```puppet +hitch::domain { 'example.com': + cacert_source => '/etc/pki/tls/certs/ca.pem', + cert_source => '/etc/pki/tls/certs/example.com.pem', + key_source => '/etc/pki/tls/private_keys/example.com.pem', +} +``` + +##### website with TLS content from hiera + +```puppet +class profile::hitch ( + Hash $domains = {}, +) { + $domains.each |$domain_title, $domain_params| { + hitch::domain { $domain_title: + * => $domain_params, + } + } +} +``` #### Parameters The following parameters are available in the `hitch::domain` defined type. ##### `ensure` Data type: `Enum['present', 'absent']` The desired state of the hitch domain. Default is 'present'. Default value: `present` ##### `default` Data type: `Boolean` If there are multiple domains, set this to true to make this the default domain used by hitch. If there is only one domain, it will be the default domain no matter what you set here. Defaults to false. Default value: ``false`` ##### `cacert_content` Data type: `Optional[String]` A PEM encoded CA certificate. Default value: ``undef`` ##### `cacert_source` Data type: `Optional[Stdlib::Filesource]` Path to a PEM encoded CA certificate. Default value: ``undef`` ##### `cert_content` Data type: `Optional[String]` A PEM encoded certificate. This must be a certificate matching the key. Default value: ``undef`` ##### `cert_source` Data type: `Optional[Stdlib::Filesource]` Path to a PEM encoded certificate. This must be a certificate matching the key. Default value: ``undef`` ##### `key_content` Data type: `Optional[String]` A PEM encoded key. This must be a key matching the certificate. Default value: ``undef`` ##### `key_source` Data type: `Optional[Stdlib::Filesource]` Path to a PEM encoded key. This must be a key matching the certificate. Default value: ``undef`` diff --git a/manifests/domain.pp b/manifests/domain.pp index 0b38322..cc6ab8b 100644 --- a/manifests/domain.pp +++ b/manifests/domain.pp @@ -1,117 +1,133 @@ # @summary # Add a TLS certificate and key for a domain # # This define installs pem files to the config root, and configures # them in the hitch config file. # # The CA certificate (if present), server certificate, key and DH # parameters are concatenated, and placed in the hitch configuration. # # You can specify cacert, cert and key with either _content or _source # suffix. # -# Parameters: +# @example website with TLS files from managed node +# hitch::domain { 'example.com': +# cacert_source => '/etc/pki/tls/certs/ca.pem', +# cert_source => '/etc/pki/tls/certs/example.com.pem', +# key_source => '/etc/pki/tls/private_keys/example.com.pem', +# } +# +# @example website with TLS content from hiera +# class profile::hitch ( +# Hash $domains = {}, +# ) { +# $domains.each |$domain_title, $domain_params| { +# hitch::domain { $domain_title: +# * => $domain_params, +# } +# } +# } # # @param ensure # The desired state of the hitch domain. Default is 'present'. # # @param default # If there are multiple domains, set this to true to make this the # default domain used by hitch. If there is only one domain, it # will be the default domain no matter what you set here. Defaults # to false. # # @param cacert_content # A PEM encoded CA certificate. # # @param cacert_source # Path to a PEM encoded CA certificate. # # @param cert_content # A PEM encoded certificate. This must be a certificate matching the # key. # # @param cert_source # Path to a PEM encoded certificate. This must be a certificate # matching the key. # # @param key_content # A PEM encoded key. This must be a key matching the certificate. # # @param key_source # Path to a PEM encoded key. This must be a key matching the # certificate. # define hitch::domain ( Enum['present', 'absent'] $ensure = present, Boolean $default = false, Optional[String] $cert_content = undef, Optional[String] $key_content = undef, Optional[String] $cacert_content = undef, Optional[Stdlib::Filesource] $cert_source = undef, Optional[Stdlib::Filesource] $key_source = undef, Optional[Stdlib::Filesource] $cacert_source = undef, ) { if ($key_content and $cert_content) { validate_x509_rsa_key_pair($cert_content, $key_content) } include ::hitch $config_root = $hitch::config_root $config_file = $hitch::config_file $dhparams_file = $hitch::dhparams_file $pem_file="${config_root}/${title}.pem" Concat::Fragment { notify => Class['hitch::service'], } # Add a line to the hitch config file concat::fragment { "hitch::domain ${title}": target => $config_file, content => "pem-file = \"${pem_file}\"\n", } # Create the pem file, with (optional) ca certificate chain, a # certificate, a key, and finally the dh parameters concat { $pem_file: ensure => $ensure, mode => '0640', owner => $::hitch::file_owner, group => $::hitch::group, notify => Class['hitch::service'], } concat::fragment {"${title} key": target => $pem_file, order => '01', content => $key_content, source => $key_source, } concat::fragment {"${title} cert": target => $pem_file, order => '02', content => $cert_content, source => $cert_source, } if ($cacert_content or $cacert_source) { concat::fragment {"${title} cacert": target => $pem_file, order => '03', content => $cacert_content, source => $cacert_source, } } concat::fragment {"${title} dhparams": target => $pem_file, source => $dhparams_file, order => '04', } } diff --git a/manifests/init.pp b/manifests/init.pp index bb9243c..42f277d 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,103 +1,112 @@ # @summary # Manage the hitch TLS proxy # +# @example defaults +# include hitch +# +# hitch::domain { 'example.com': +# cacert_source => '/etc/pki/tls/certs/ca.pem', +# cert_source => '/etc/pki/tls/certs/example.com.pem', +# key_source => '/etc/pki/tls/private_keys/example.com.pem', +# } +# # @param package_name # Package name for installing hitch. # # @param service_name # Service name for the hitch service. # # @param user # User running the service. # # @param group # Group running the service. # # @param backend # Where to proxy requests. # # @param config_file # Path to the hitch configuration file. # # @param file_owner # User owning the configuration files. Defaults to "root". # # @param dhparams_file # Path to file for Diffie-Hellman parameters, which are shared # by all domains. # # @param dhparams_content # Content for the DH parameter file. If unset, DH parameters will # be generated on the node, which may take a long time. # # @param config_root # Configuration root directory. The hitch::domain defined type # will place certificates here. # # # @param purge_config_root # If true, will delete all unmanaged files from the config_root. # Defaults to false. # # @param frontend # The listening frontend(s) for hitch. # # @param manage_repo # If true, install the EPEL repository on RedHat OS family. # class hitch ( String $package_name, String $service_name, String $user, String $group, String $file_owner, Stdlib::Absolutepath $config_file, Stdlib::Absolutepath $dhparams_file, Stdlib::Absolutepath $config_root, Boolean $purge_config_root, Variant[String, Array] $frontend, String $backend, Enum['on', 'off'] $write_proxy_v2, String $ciphers, Optional[Hash] $domains, Optional[String] $dhparams_content, Boolean $manage_repo, Variant[Integer, Enum['auto']] $workers, Enum['on','off'] $prefer_server_ciphers, Optional[String] $alpn_protos, Optional[String] $tls_protos, ) { class { '::hitch::install': package => $package_name, manage_repo => $manage_repo, } -> class { '::hitch::config': config_root => $config_root, config_file => $config_file, dhparams_file => $dhparams_file, dhparams_content => $dhparams_content, purge_config_root => $purge_config_root, file_owner => $file_owner, user => $user, group => $group, frontend => $frontend, backend => $backend, write_proxy_v2 => $write_proxy_v2, ciphers => $ciphers, workers => $workers, prefer_server_ciphers => $prefer_server_ciphers, alpn_protos => $alpn_protos, tls_protos => $tls_protos, } ~> class { '::hitch::service': service_name => $service_name, } -> Class['::hitch'] $domains.each |$domain_title, $domain_params| { hitch::domain { $domain_title: * => $domain_params, } } }