certs

Configures and manages SSL certificate deployments, restarting services as configured.

Project URL RSS Feed Report issues

Module Author

Broad Institute

broadinstitute

Module Stats

16,161 downloads

3,178 latest version

5.0 quality score

Version information

released Jan 27th 2020

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

Bolt

r10k or Code Manager

Manual installation

Download

Documentation

broadinstitute/certs — version 2.5.1 Jan 27th 2020

certs

Overview
Module Description
Setup
- Setup requirements
Usage
- Installation
- Examples
Reference
Limitations - OS compatibility, etc.
Contributors

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
Debian & Suse
- certificates directory: /etc/ssl/certs
- keys directory: /etc/ssl/private
- service: apache2
FreeBSD
- certificates directory: /usr/local/etc/apache24
- keys directory: /usr/local/etc/apache24
- service: apache24
Gentoo
- certificates directory: /etc/ssl/apache2
- keys directory: /etc/ssl/apache2
- service: apache2

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
Private classes
- Class: certs::params
Public defined types
- Defined type: certs::site
- Parameters within certs::site

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)

More contributors.

Modules

Discover

Contribute

Topics

How-to Guides

Collections

Resources

About Forge

Getting Started

certs

Broad Institute

Version information

This version is compatible with:

Start using this module

Documentation

certs

Table of Contents

Overview

Module Description

Setup

Setup Requirements

Usage

Installation

Examples

Reference

Public Classes

Class: certs

Private Classes

Class: certs::params

Public Defined Types

Defined type: certs::site

Parameters within certs::site

ca_cert

ca_content

ca_ext

ca_name

ca_path

ca_source_path

cert_chain

cert_content

cert_dir_mode

cert_ext

cert_mode

cert_path

chain_content

chain_ext

chain_name

chain_path

chain_source_path

dhparam

dhparam_content

dhparam_dir

dhparam_file

ensure

group

key_content

key_dir_mode

key_ext

key_mode

key_path

merge_chain

merge_dhparam

merge_key

name

owner

service

source_path

validate_x509

Limitations

Contributors

Change log

2.5.1 (2020-01-24)

Added

Fixed

2.5.0 (2018-07-27)

Added

2.4.0 (2018-07-26)

Added

2.3.2 (2018-07-24)

Fixed

Class: `certs`

Class: `certs::params`

Defined type: `certs::site`

Parameters within `certs::site`

`ca_cert`

`ca_content`

`ca_ext`

`ca_name`

`ca_path`

`ca_source_path`

`cert_chain`

`cert_content`

`cert_dir_mode`

`cert_ext`

`cert_mode`

`cert_path`

`chain_content`

`chain_ext`

`chain_name`

`chain_path`

`chain_source_path`

`dhparam`

`dhparam_content`

`dhparam_dir`

`dhparam_file`

`ensure`

`group`

`key_content`

`key_dir_mode`

`key_ext`

`key_mode`

`key_path`

`merge_chain`

`merge_dhparam`

`merge_key`

`name`

`owner`

`service`

`source_path`

`validate_x509`