certs
Version information
This version is compatible with:
- Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x
- Puppet >=5.0.0 < 7.0.0
- RedHat,CentOS,OracleLinux,Scientific,Debian,Ubuntu,SuSE
Start using this module
Documentation
certs
Table of Contents
Overview
Configures SSL certificates and keys.
Module Description
This module provides SSL certificate files required by Apache or other services via the certs::site define. It can be used in conjunction with puppetlabs/apache's apache::vhost definitions to provide the ssl_cert and ssl_key files or any other service requiring SSL certificates.
It can also be used independent of any Puppet-defined service that requires the files to exist on a managed node.
Setup
Setup Requirements
The certificate files must come from an external store. Recommended stores are a site-specific (and private) module containing SSL files or a network-accessible filesystem, such as NFS, that the managed node can access.
Once a file store is determined, include at least one certs::site define and specify the file store location as the source_path
.
By default, this module will place certificates and keys in their relative locations and restart the specified service, provided it is defined in the catalog.
-
RedHat
- certificates directory:
/etc/pki/tls/certs
- keys directory:
/etc/pki/tls/private
- service:
httpd
- certificates directory:
-
Debian & Suse
- certificates directory:
/etc/ssl/certs
- keys directory:
/etc/ssl/private
- service:
apache2
- certificates directory:
-
FreeBSD
- certificates directory:
/usr/local/etc/apache24
- keys directory:
/usr/local/etc/apache24
- service:
apache24
- certificates directory:
-
Gentoo
- certificates directory:
/etc/ssl/apache2
- keys directory:
/etc/ssl/apache2
- service:
apache2
- certificates directory:
Usage
No trailing slashes should be provided for any paths.
Installation
Puppet Forge:
puppet module install broadinstitute-certs
Puppetfile:
mod 'broadinstitute/certs'
Examples
Puppet Manifest:
manifest.pp
include certs
$domain = 'www.example.com'
certs::site { $domain:
source_path => 'puppet:///site_certificates',
ca_cert => true,
ca_name => 'caname',
ca_source_path => 'puppet:///ca_certs',
}
With Hiera:
node.yaml
classes:
- certs
certs::sites:
'www.example.com':
source_path: 'puppet:///site_certificates'
ca_cert: true
ca_name: 'caname'
ca_source_path: 'puppet:///ca_certs'
Resource Chaining with Apache Module:
manifest.pp
Certs::Site<| |> -> Apache::Vhost<| |>
Global Defaults:
You can also reset some of the settings in params.pp globally via the certs base class which will be inherited by all certs::site defines used that are later defined. In this example, we can reset the default certificate and key paths for all instantiated sites so that we don't have to manually set the custom path in each site:
$domain1 = 'www.example.com'
$domain2 = 'foo.example.com'
class { 'certs':
cert_path => '/path/to/certs',
key_path => '/path/to/keys',
}
certs::site { $domain1:
source_path => 'puppet:///site_certificates',
ca_cert => true,
ca_name => 'caname',
ca_source_path => 'puppet:///ca_certs',
}
certs::site { $domain2:
source_path => 'puppet:///site_certificates',
ca_cert => true,
ca_name => 'caname',
ca_source_path => 'puppet:///ca_certs',
}
Reference
Public Classes
Class: certs
Instantiates the availability of the certs::site defined type.
You can simply declare the default certs
class:
class { 'certs': }
Private Classes
Class: certs::params
Manages parameters for configuring certificate sites.
Public Defined Types
Defined type: certs::site
The Certs module allows a lot of flexibility in the configuration of sites. This flexibility is due, in part, to site
being a defined resource type, which allows it to be evaluated multiple times with different parameters.
The certs::site
defined type allows you to define certificates to deploy to managed nodes and restart dependent services automatically.
Parameters within certs::site
ca_cert
Boolean for whether to look for a CA certificate file.
Optional value. Default: false.
ca_content
A string representing the contents of the CA file.
Optional value. Default: undef.
ca_ext
The extension of the CA certificate file.
Optional value. Default: crt.
ca_name
The name of the CA certificate file.
Optional value. Default: undef.
ca_path
Location where the CA certificate file will be stored on the managed node.
Optional value. Default: cert_path
.
ca_source_path
The location of the CA certificate file. Typically references a module's files.
e.g. 'puppet:///ca_certs' will search for the mount point defined in fileserver.conf
on the Puppet Server for the specified files.
Optional value. Default: source_path
.
cert_chain
Boolean for whether to look for a certificate chain file.
Optional value. Default: false.
cert_content
A string representing the contents of the certificate file. This can only be provided if $source_path
is undefined or an error will occur.
Optional value. Default: undef.
cert_dir_mode
Permissions of the certificate directory.
Optional value. Default: '0755'.
cert_ext
The extension of the certificate file.
Optional value. Default: '.crt'.
cert_mode
Permissions of the certificate files.
Optional value. Default: '0644'.
cert_path
Location where the certificate files will be stored on the managed node.
Optional value. Defaults:
- RedHat:
/etc/pki/tls/certs
- Debian and SuSE:
/etc/ssl/certs
- FreeBSD:
/usr/local/etc/apache24
- Gentoo:
/etc/ssl/apache2
chain_content
A string representing the contents of the chain file.
Optional value. Default: undef.
chain_ext
The extension of the certificate chain file.
Optional value. Default: crt.
chain_name
The name of the certificate chain file.
Optional value. Default: undef.
chain_path
Location where the certificate chain file will be stored on the managed node.
Optional value. Default: cert_path
.
chain_source_path
The location of the certificate chain file. Typically references a module's files.
e.g. 'puppet:///chain_certs' will search for the mount point defined in fileserver.conf
on the Puppet Server for the specified files.
Optional value. Default: source_path
.
dhparam
A boolean value to determine whether a dhparam file should be placed on the system along with the other certificate files. The dhparam file will need to exist on the source side just as with the other certificate files in order for the file to be delivered.
Optional value. Default: false.
dhparam_content
A string representing the contents of the dhparam file. This option will take precedence over dhparam_file if it exists on the source side.
Optional value. Default: undef.
dhparam_dir
A string representing the directory in which the dhparam file should be placed.
Optional value. Default: cert_path
.
dhparam_file
The name of the dhparam file.
Optional value. Default: 'dh2048.pem'.
ensure
Ensure for the site resources. If present
, files will be put in place. If absent
, certificate, key and dhparam files will be removed.
Optional value. Default: 'present'.
group
Name of the group owner of the certificates.
Optional value. Defaults:
- RedHat, Debian, and SuSE:
root
- FreeBSD and Gentoo:
wheel
key_content
A string representing the contents of the key file. This can only be provided if $source_path
is undefined or an error will occur.
Optional value. Default: undef.
key_dir_mode
Permissions of the private keys directory.
Optional value. Default: '0755'.
key_ext
The extension of the private key file.
Optional value. Default: '.key'.
key_mode
Permissions of the private keys.
Optional value. Default: '0600'.
key_path
Location where the private keys will be stored on the managed node.
Optional value. Defaults:
- RedHat:
/etc/pki/tls/private
- Debian and SuSE:
/etc/ssl/private
- FreeBSD:
/usr/local/etc/apache24
- Gentoo:
/etc/ssl/apache2
merge_chain
Option to merge the CA and intermediate chain files into the actual certificate file, which is required by some software.
Optional value. Default: false.
merge_dhparam
Option to merge the DH paramaters file into the actual certificate file, which is required by some software.
Optional value. Default: false.
merge_key
Option to merge the private key into the actual certificate file, which is required by some software.
Optional value. Default: false.
name
The title of the resource matches the certificate's name
e.g. www.example.com matches the certificate for the hostname www.example.com.
owner
Name of the owner of the certificates.
Optional value. Default: 'root'.
service
Name of the server service(s) to notify when certificates are updated.
Setting to false (or any Boolean) will disable service notifications.
Optional value. Defaults:
- RedHat:
httpd
- Debian, SuSE, and Gentoo:
apache2
- FreeBSD:
apache24
source_path
The location of the certificate files. Typically references a module's files.
e.g. 'puppet:///site_certs' will search for the mount point defined in fileserver.conf
on the Puppet Server for the specified files.
validate_x509
A boolean value to determine whether or not to validate the certificate and key pairs. Failure will cause the catalog to fail compilation.
Optional value. Default: false.
Limitations
This module is CI tested against open source Puppet on:
- CentOS 6 and 7
- RHEL 6 and 7
This module also provides functions for other distributions and operating systems, such as FreeBSD and Gentoo, but is not formally tested on them and are subject to regressions.
Contributors
Riccardo Calixte (@rcalixte)
Andrew Teixeira (@coreone)
Change log
All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
2.5.1 (2020-01-24)
Added
Fixed
- Make dhparam directory customizable (Fixes #38) #45 (coreone)
- Fix ensure_resource on multiple directories not working correctly #43 (coreone)
2.5.0 (2018-07-27)
Added
2.4.0 (2018-07-26)
Added
2.3.2 (2018-07-24)
Fixed
2.3.1 (2018-06-18)
2.3.0 (2018-06-18)
Added
2.2.1 (2018-06-07)
Added
2.2.0 (2018-05-18)
Added
2.1.1 (2018-05-16)
2.1.0 (2018-05-16)
Added
- Add validation parameter #25 (rcalixte)
- Handle trusted certificate updates on EL6/7 #22 (jorhett)
- Refactor for modern Puppet #21 (jorhett)
Fixed
1.2.1 (2017-08-02)
Added
Fixed
1.2.0 (2017-07-28)
Added
1.1.0 (2017-01-17)
Added
1.0.0 (2016-09-06)
Added
- Add tests, content instead of source logic, and ensure support #6 (coreone)
- Update README #5 (rcalixte)
- Testing fixes and global default settings #4 (coreone)
- Various fixes and cert/chain merge ability #3 (coreone)
0.4.0 (2016-08-25)
* This Changelog was automatically generated by github_changelog_generator
Dependencies
- puppetlabs-stdlib (>= 4.12.0 < 7.0.0)
- puppetlabs/concat (>= 1.1.1 < 7.0.0)