diff --git a/REFERENCE.md b/REFERENCE.md index b5ca980..68be811 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -1,252 +1,245 @@ # Reference ## Table of Contents ### Classes #### Public Classes -* [`hitch`](#hitch): Class: hitch =========================== Full description of class hitch here. Parameters ---------- +* [`hitch`](#hitch): Manage the hitch TLS proxy #### Private Classes -* `hitch::config`: == Class hitch::config This class is called from hitch for service config. -* `hitch::install`: == Class hitch::install This class is called from hitch for install. -* `hitch::service`: == Class hitch::service This class is meant to be called from hitch. It ensure the service is running. +* `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): == Define hitch::domain This define installs pem files to the config root, and configures them in the hitch config file. The CA certificate +* [`hitch::domain`](#hitchdomain): Add a TLS certificate and key for a domain ## Classes ### `hitch` -Class: hitch -=========================== - -Full description of class hitch here. - -Parameters ----------- +Manage the hitch TLS proxy #### 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. Default: /etc/hitch/ +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. -##### `config_file` - -Data type: `Stdlib::Absolutepath` - - - -##### `backend` - -Data type: `String` - - - ##### `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` -== Define 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: #### 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/config.pp b/manifests/config.pp index 0ff4c31..97919b3 100644 --- a/manifests/config.pp +++ b/manifests/config.pp @@ -1,78 +1,77 @@ -# == Class hitch::config -# -# This class is called from hitch for service config. +# @summary +# Manage the hitch configuration, systemd configuration and default DH parameters. # # @api private class hitch::config ( Stdlib::Absolutepath $config_root, Stdlib::Absolutepath $config_file, Stdlib::Absolutepath $dhparams_file, Boolean $purge_config_root, String $file_owner, String $user, String $group, Enum['on','off'] $write_proxy_v2, Variant[String, Array] $frontend, String $backend, String $ciphers, Variant[Integer, Enum['auto']] $workers, Enum['on','off'] $prefer_server_ciphers, Optional[String] $dhparams_content = undef, Optional[String] $alpn_protos = undef, Optional[String] $tls_protos = undef, ) { case $frontend { Array: { $frontend_array = $frontend } String: { $frontend_string = $frontend } default: { fail('invalid frontend') } } file { $config_root: ensure => directory, recurse => true, purge => $purge_config_root, owner => $file_owner, group => $group, mode => '0750', } concat { $config_file: ensure => present, } if $dhparams_content { file { $dhparams_file: ensure => present, owner => $file_owner, group => $group, mode => '0640', content => $dhparams_content, } } else { exec { "${title} generate dhparams": path => '/usr/local/bin:/usr/bin:/bin', command => "openssl dhparam -out ${dhparams_file} 2048", creates => $dhparams_file, } -> file { $dhparams_file: ensure => present, owner => $file_owner, group => $group, mode => '0640', } } concat::fragment { "${title} config": content => template('hitch/hitch.conf.erb'), target => $config_file, } } diff --git a/manifests/domain.pp b/manifests/domain.pp index 1c8da28..0b38322 100644 --- a/manifests/domain.pp +++ b/manifests/domain.pp @@ -1,116 +1,117 @@ -# == Define hitch::domain +# @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: # -# @param ensure [Enum['present','absent']] +# @param ensure # The desired state of the hitch domain. Default is 'present'. # -# @param default [Boolean] +# @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 [Optional[String]] cacert_content +# @param cacert_content # A PEM encoded CA certificate. # -# @param [Optional[Stdlib::Filesource]] cacert_source +# @param cacert_source # Path to a PEM encoded CA certificate. # -# @param [Optional[String]] cert_content +# @param cert_content # A PEM encoded certificate. This must be a certificate matching the # key. # -# @param [Optional[Stdlib::Filesource]] cert_source +# @param cert_source # Path to a PEM encoded certificate. This must be a certificate # matching the key. # -# @param [Optional[String]] key_content +# @param key_content # A PEM encoded key. This must be a key matching the certificate. # -# @param [Optional[Stdlib::Filesource]] key_source +# @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 c4b167b..bb9243c 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,100 +1,103 @@ -# Class: hitch -# =========================== +# @summary +# Manage the hitch TLS proxy # -# Full description of class hitch here. -# -# Parameters -# ---------- -# -# @param package_name [String] +# @param package_name # Package name for installing hitch. # -# @param service_name [String] +# @param service_name # Service name for the hitch service. # -# @param user [String] +# @param user # User running the service. # -# @param group [String] +# @param group # Group running the service. # -# @param file_owner [String] +# @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 [Stdlib::Absolutepath] +# @param dhparams_file # Path to file for Diffie-Hellman parameters, which are shared # by all domains. # -# @param dhparams_content [Optional[String]] +# @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 [Stdlib::Absolutepath] -# Configuration root directory. Default: /etc/hitch/ +# @param config_root +# Configuration root directory. The hitch::domain defined type +# will place certificates here. +# # -# @param purge_config_root [Boolean] +# @param purge_config_root # If true, will delete all unmanaged files from the config_root. # Defaults to false. # -# @param frontend[Variant[String, Array]] +# @param frontend # The listening frontend(s) for hitch. # -# @param manage_repo [Boolean] +# @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, } } } diff --git a/manifests/install.pp b/manifests/install.pp index 45cfd65..01d0827 100644 --- a/manifests/install.pp +++ b/manifests/install.pp @@ -1,21 +1,20 @@ -# == Class hitch::install -# -# This class is called from hitch for install. +# @summary +# Manage the hitch package and optionally a repository # # @api private class hitch::install ( String $package, Boolean $manage_repo, ) { if $manage_repo { if $facts['os']['family'] == 'RedHat' { ensure_resource('package', 'epel-release', { 'ensure' => 'present' }) Package['epel-release'] -> Package[$package] } } package { $package: ensure => present, } } diff --git a/manifests/service.pp b/manifests/service.pp index 34f1fa4..05fb52e 100644 --- a/manifests/service.pp +++ b/manifests/service.pp @@ -1,23 +1,21 @@ -# == Class hitch::service -# -# This class is meant to be called from hitch. -# It ensure the service is running. +# @summary +# Manage the hitch service # # @api private class hitch::service ( String $service_name, ) { service { $service_name: ensure => running, enable => true, hasstatus => true, hasrestart => true, } # configure hitch.service systemd::dropin_file { 'limits.conf': unit => 'hitch.service', content => template('hitch/limits.conf.erb'), } }