Sectigo Puppet integration

Overview

The Sectigo Puppet integration provides a solution for the enrollment, collection, renewal, replacement, and revocation of SSL/TLS and client (S/MIME) certificates issued by the Sectigo Certificate Manager (SCM).

The integration is distributed as a Puppet module featuring the following:

  • RSA 2048, 3072, and 4096-bit private key generation

  • Certificate signing request (CSR)

  • Enrollment, collection, renewal, replacement, and revocation of certificates issued by SCM

The integration supports the generation of new SSL and client certificates and detection of existing certificates stored in a location accessible to the module at runtime. The integration also checks the validity of existing certificates and allows the issuance of replacement certificates as required. You can request different types of SSL and client certificates by supplying appropriate configuration options.

The types of SSL and client certificates available to you are based on your account configuration.
Puppet Sectigo integration diagram

Prerequisites

The Puppet integration has the following prerequisites:

  • Puppet Server and Agent version 6

  • Ruby version 2.6

  • SCM organization with the Web API access enabled

  • A list of SSL and client certificate types with associated validity periods for the organization

The Puppet module is supported for Linux master and Linux agent and has been tested on the following operating systems:

  • CentOS 7.3/8.0 master and agent

  • Ubuntu 18.04 and 20.04 master and agent

Puppet integration package

The Sectigo Puppet integration package contains the following:

  • modules:

    • sectigo_puppet_module:

      • files: Contains static files

        • index.html: Sample dashboard

        • server_httpd.conf: Sample HTTPD server configuration

        • server_nginx.conf: Sample NGINX server configuration

        • ssl_redirect.conf: Sample server redirect HTTP to HTTPS

      • lib/puppet/functions/sectigo_puppet_module:

        • constants.rb: Constants file for the SCM API library

        • rbcert.rb: Ruby library for connecting with the SCM API

        • helper.rb: Common function file

        • sectigo_puppet_module.rb: Main Ruby file designed for Puppet

      • manifest

        • httpd.pp: Sample HTTPD configuration

        • init.pp: Manifest files that calls Ruby

        • nginx.pp: Sample NGINX configuration

  • manifests:

    • site.pp: The catalog for the Puppet server. This file contains a configuration that can be used to generate certificate on servers and that can be used to move existing certificates from master to agent nodes.

  • Sample:

    • config_sample_account.json: Sample Facter configuration with SCM account-related parameters

    • config_sample_issue_ssl.json or config_sample_issue_client.json: Sample Facter configuration with parameters that are used for SSL or client certificate issuance.

    • config_sample_node_ssl.json: Sample Facter configuration with parameters that are used for moving SSL certificates onto a Puppet node.

    • fileserver.conf: Sample configuration file for the Puppet file server

    • run.sh: A shell script that can be used in a cronjob to automate the execution of the module.

Sectigo Puppet integration package

The integration structure

The integration hides the complexity of the SCM REST API by acting as an adapter between Puppet and the Sectigo API. It enables you to issue, collect, replace, renew, and revoke certificates on your master and agent nodes.

Components

The integration is based on the following components:

  • Ruby library for the Sectigo API handles the communication with the Sectigo REST API. This library is delivered as a component of the Puppet module. It is not designed nor delivered as a general-purpose library.

    The Puppet module is the only software component that can interact with the library.
  • Sectigo Puppet module mediates the interaction between you, the Puppet master and agent nodes, and the Sectigo REST API. The module mainly consists of a standard Puppet execution routine with minimum dependencies. It supports the issuance, collection, replacement, renewal, and revocation of SSL and client certificates.

  • Facter contains all the required parameters for SSL and client executions in JSON format. In addition, it contains the account JSON file which consists of the account’s Facter files and certificate generation-specific option.

Tasks

The integration generates certificates on a master server and, in the case of SSL certificates, distributes them onto agent nodes. The integration uses Puppet modules that are typically located in the /etc/puppetlabs/code/environment/<environment_name>/modules/sectigo_puppet_module/ directory.

Additionally, the integration allows you to generate certificates directly on agent nodes by using the deferred functions concept of Puppet. All of the inclusions are made in the main manifest file site.pp located in the /etc/puppetlabs/code/environment/<environment_name>/manifest/site.pp directory which serves as a catalog to the servers addressed within it.

The following tasks are available through Puppet:

  • issue: Obtains a new certificate using parameters that correspond to SSL or client certificates, along with certificate-related files. The certificate’s name is defined by the sectigo_ssl_cert_file_name or sectigo_client_cert_file_name parameter in the sectigo_ssl_cert_file_path or sectigo_client_cert_file_path directory, respectively.

    This task also collects certificates that are issued and supports the auto-renewal of certificates.

  • collect: Collects the certificates. You must ensure that the value of the sectigo_ssl_cert_ssl_id or sectigo_client_cert_order_number parameter is defined in the Facter files.

  • replace: Replaces the certificates. You must ensure that the sectigo_ssl.ids or sectigo_client.ids file exists on the required file path.

  • revoke: Revokes the certificates. You must ensure that the sectigo_ssl.ids or sectigo_client.ids file exists on the required file path.

The integration parameters

The integration provides various parameters that you can use in different scenarios.

Customer-specific parameters

The following table lists parameters that are required for establishing a connection with SCM.

Parameter Type Description

sectigo_cm_user

Mandatory

Your Sectigo username

sectigo_cm_password

Mandatory

Password to access your URI

sectigo_cm_uri

Mandatory

Your Sectigo specific URI

sectigo_cm_base_url

Mandatory

The base URL of the Sectigo CA

CSR parameters

The following table lists parameters that are required for the generation of the CSR.

Parameter Type Description

sectigo_csr_domain

Conditional

A single value for a domain included in the certificate Common Name (CN) field.

Required if sectigo_csr is not defined.

sectigo_csr_country

Conditional

The country name included in the certificate Country (C) field.

Required if sectigo_csr is not defined.

sectigo_csr_state

Conditional

The state or province name included in the certificate State (ST) field.

Required if sectigo_csr is not defined.

sectigo_csr_location

Conditional

The location name included in the certificate Location (L) field.

Required if sectigo_csr is not defined.

sectigo_csr_organization

Conditional

The organization name included in the certificate Organization (O) field.

Required if sectigo_csr is not defined.

sectigo_csr_organization_unit

Conditional

The organization unit included in the certificate Organization Unit (OU) field.

Required if sectigo_csr is not defined.

sectigo_csr_email_address

Conditional

The email address included in the certificate emailAddress field.

Required if sectigo_csr is not defined.

sectigo_csr

Conditional

The full path to the CSR file. If provided, then the subject parameters are ignored.

sectigo_csr_key_algo

Optional

The private key algorithm to use to generate the private key. The default value is RSA.

sectigo_csr_key_size

Optional

The size of the TLS/SSL key to generate. The possible values are:

  • 2048: for 2048-bit (default)

  • 3072: for 3072-bit

  • 4096: for 4096-bit

Certificate issuance parameters

The following table lists parameters that are used for certificate issuance.

Parameter Type Description

SSL certificates

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_ssl_cert_file_path

Mandatory (with default)

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed.

sectigo_ssl_cert_file_name

Mandatory (with default)

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs. The default file name is sectigo_ssl.

sectigo_ssl_cert_external_requester

Optional

A comma-separated list of emails

sectigo_ssl_cert_comments

Optional

Comments for certificate enrollment

sectigo_ssl_cert_num_servers

Conditional

The number of server licenses (numeric)

sectigo_ssl_cert_server_type

Optional

The server type ID (numeric)

sectigo_ssl_cert_subject_alt_names

Optional

A comma-separated list of subject alternative names (SAN)

sectigo_ssl_cert_custom_fields

Optional

The custom fields to be applied to the requested certificate. The expected format for custom fields is the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using \.

sectigo_ssl_cert_format_type

Optional

The format type for the SSL certificate. The supported values are:

  • x509: X509, Base64 encoded

  • x509CO: X509 Certificate only, Base64 encoded (default)

  • x509IO: X509 Intermediates/Root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

  • x509IOR: X509 Intermediates/Root only, reverse, Base64 encoded

sectigo_ssl_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

sectigo_ssl_cert_type

Mandatory

The type of SSL certificate (numeric). This is the ID of the SSL certificate type.

Client certificates

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_client_cert_file_path

Mandatory (with default)

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed.

sectigo_client_cert_file_name

Mandatory (with default)

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs. The default filename is sectigo_client.

sectigo_client_cert_type

Mandatory

The type of client certificate (numeric). This is the ID of the client certificate type.

sectigo_client_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

sectigo_client_cert_email

Mandatory

A valid user email that is less than 256 characters

sectigo_client_cert_first_name

Mandatory

The user’s first name

sectigo_client_cert_middle_name

Conditional

The user’s middle name

sectigo_client_cert_last_name

Mandatory

The user’s last name. The combined length of the first, middle, and last name fields cannot exceed 64 characters.

sectigo_client_cert_custom_fields

Optional

The custom fields to be applied to the requested certificate. The expected format for custom fields is the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using \.

sectigo_client_cert_subject_alt_names

Optional

A comma-separated list of subject alternative names (SAN)

sectigo_client_cert_revoke_on_replace

Optional

If True, previous certificates will be revoked when replaced. The default value is False.

Certificate auto-renewal

sectigo_expiry_window

Optional

The period of days prior to expiration that a new certificate enrollment process will be initiated (numeric) if a task is started. The default expiry window is 7 days.

sectigo_auto_renew

Optional

If set to true, the auto-renewal option is enabled. The default value is true.

Collect certificate

sectigo_loop_period

Optional

The interval (in seconds) between repeated attempts to collect a certificate (numeric). The default value is 30.

sectigo_max_timeout

Optional

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made (numeric). The default value is 600.

In addition to the parameters listed in the preceding table, you are required to pass CSR parameters.

Certificate collection parameters

The following table lists parameters that are used for collecting a certificate. The collection operation may fail if the certificate is still being processed. In such cases, the operation attempts to collect the certificate several times before returning a failure. The parameters allow you to configure the frequency and maximum time for additional attempts during certificate collection.

Parameter Type Description

SSL certificates

sectigo_ssl_cert_format_type

Mandatory (with default)

The format type for the SSL certificate. The supported values are:

  • x509: X509, Base64 encoded (default)

  • x509CO: X509 certificate only, Base64 encoded

  • x509IO: X509 intermediates and root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

  • x509IOR: X509 intermediates and root only, reverse, Base64 encoded

sectigo_loop_period

Optional

The interval (in seconds) between repeated attempts to collect a certificate (numeric). The default value is 30.

sectigo_max_timeout

Optional

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made (numeric). The default value is 600.

sectigo_ssl_cert_ssl_id

Conditional

The SSL ID of the certificate to be collected. Mandatory if the selected Facter task is collect.

sectigo_ssl_cert_file_path

Optional

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed.

sectigo_ssl_cert_file_name

Optional

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs. The default file name is sectigo_ssl.

Client certificates

sectigo_loop_period

Optional

The interval (in seconds) between repeated attempts to collect a certificate (numeric). The default value is 30.

sectigo_max_timeout

Optional

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made (numeric). The default value is 600.

sectigo_client_cert_file_name

Optional

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs. The default file name is sectigo_client.

sectigo_client_cert_file_path

Optional

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs. The default file path is the one where the command is executed.

sectigo_client_cert_order_number

Conditional

The order number of the certificate to be collected. Mandatory if the selected Facter task is collect.

Certificate replacement parameters

The following table lists parameters that are used for replacing a certificate.

Parameter Type Description

SSL certificates

sectigo_replace_reason

Mandatory

Reason for replacing the certificate

sectigo_ssl_cert_common_name

Mandatory

A single value for a domain included in the certificate Common Name (CN) field

sectigo_generate_key_if_missing

Mandatory (with default)

If true, generates the private key if it is missing. The default value is true.

Client certificates

sectigo_replace_reason

Mandatory

Reason for replacing the certificate

sectigo_client_cert_revoke_on_replace

Mandatory (with default)

If true, previous certificates will be revoked when replaced. The default value is true.

sectigo_generate_key_if_missing

Mandatory (with default)

If true, generates the private key if it is missing. The default value is true.

In addition to the parameters listed in the preceding table, you are required to pass CSR parameters, as per your replacement requirement. For more information, see Replacing certificates.

Certificate revocation parameters

The following table lists parameters that are used for manually revoking a certificate.

Parameter Type Description

SSL certificates

sectigo_revoke_reason

Mandatory

The reason why a certificate is to be revoked

sectigo_ssl_cert_file_name

Mandatory

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs.

sectigo_ssl_cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs.

Client certificates

sectigo_revoke_reason

Mandatory

The reason why a certificate is to be revoked

sectigo_client_cert_file_name

Mandatory

The name of the certificate file. The same name is used for the CSR, private key, and enrollment IDs.

sectigo_client_cert_file_path

Mandatory

The location where the certificate is to be stored. The same location is used to store CSR, private key, and enrollment IDs.

Miscellaneous parameters

The following table lists parameters that are used for renewing a certificate.

Parameter Type Description

sectigo_force

Optional

Issues a new certificate even if there is already a certificate on the target server. The default value is false. If set to true, the existing certificate is backed up and any related information (key, CSR, ID) is deleted. This option is required if the certificate information (such as domain) has changed and a new certificate is required.

sectigo_cert_type

Mandatory

Indicates the type of the certificate. Should be set to ssl for SSL certificates and to client for client certificates.

generate_cert_on

Mandatory

Determines where the certificates are to be generated. Accepts either master or node as a value.

Puppet command-line interface parameters

The following table lists parameters that are used directly in the command-line interface commands.

Parameter Description Case-sensitive

FACTER_task

A task that is to be executed. Can be issue/collect/replace/revoke.

Yes. FACTER in upper case. The rest in lower case.

FACTER_type

Can be either ssl or client, as in supported certificate types

Yes. FACTER in upper case. The rest in lower case.

site.pp

Configuration file from the applied manifest folder

Yes. Everything is typically in lower case.

Using the integration package

To use the integration package, you need to configure your directory structure and a number of other artifacts, and then you can start interacting with the software:

  1. Switch to the root user using the sudo su command.

    sudo su
  2. Unzip the Puppet integration package and navigate to the Sectigo-Puppet-Integration directory.

  3. Copy the files from the Sectigo-Puppet-Integration/Sample/ directory to the /opt/puppetlabs/facter/facts.d directory.

    cp Sectigo-Puppet-Integration/Sample/* /opt/puppetlabs/facter/facts.d/
  4. Copy the child directories of the /Sectigo-Puppet-Integration/modules/sectigo_puppet_module directory to the /etc/puppetlabs/code/environments/production/modules/ directory.

    cp -r /Sectigo-Puppet-Integration/modules/sectigo_puppet_module /etc/puppetlabs/code/environments/production/modules/
  5. Copy the Sectigo-Puppet-Integration/manifests/site.pp file to the /etc/puppetlabs/code/environments/production/manifests/ directory.

    cp Sectigo-Puppet-Integration/manifests/site.pp /etc/puppetlabs/code/environments/production/manifests/

How to configure the work directory structure

The manifest, Sample, and module directories that are included in the integration package contain all the files that are required by the Sectigo Puppet module. These directories must be placed in the /etc/puppetlabs/code/environment/<environment_name>/ directory on the master server.

How to configure the Puppet master

Once you have the Puppet Server installed on your Linux system, you must configure the Facter path and Facter files. The Facter path should be /opt/puppetlabs/facter/facts.d/. By default, this path does not exist so you must create its directories and subdirectories manually. The Facter values are typically stored in a JSON file. The following is a sample Facter JSON configuration that is a part of the integration package.

{
    "sectigo_ssl_config": {
        "sectigo_cert_type":"ssl",
        "sectigo_ssl_cert_file_path":"/etc/ssl/",
        "sectigo_ssl_cert_file_name":"Sectigo_ssl",
        …
        }
}

When working on the master node, you must include the config_sample_account.json file and the config_sample_issue_ssl.json or config_sample_issue_client.json Facter files in your Facter directory (samples of these files are provided with the integration package).

If you are generating certificates on the Puppet master, you must set the generate_cert_on Facter value in the config_sample_account.json file to master.

If you intend to transfer SSL certificates from a Puppet master to a Puppet agent, then you must also include the config_sample_node_ssl.json file in your Facter directory and the fileserver.conf file in your Puppet environment directory typically located in the /etc/puppetlabs/puppet directory (samples of these files are provided with the integration package).

The path in the fileserver.conf file should match the path that you have specified in the sectigo_ssl_cert_file_path or sectigo_client_cert_file_path Facter value.

How to configure the Puppet agent

Once you have the Puppet agent installed on your Linux system, you must also configure the Facter path and Facter files. The Facter path should be /opt/puppetlabs/facter/facts.d/. If the path does not exist, you must create its directories and subdirectories manually. The configuration of the Puppet agent depends on your use case. If you are planning to generate certificates on the Puppet master and then move them to the Puppet agent, you only need to configure the Facter values that are set in the config_sample_node_ssl.json (for SSL) sample file provided with the integration.

If you want to generate certificates and interact with SCM directly on the Puppet agent instead of using the Puppet master, then you must set the certificate issuance and account-related Facter values on your Puppet agent. These values are provided in the config_sample_account.json and config_sample_issue_ssl.json or config_sample_issue_client.json sample files, respectively.

If you are generating certificates on the Puppet agent, you must set the generate_cert_on Facter value in the config_sample_account.json file to node.

How to define the account-based Facter values

The following shows how to define the account-based values in a different Facter file in JSON format as key:value pairs.

{
    "sectigo_account_config": {
        "sectigo_cm_user":"<YOUR_USER_NAME>",
        "sectigo_cm_password":"<YOUR_PASSWORD>",
        "sectigo_cm_uri":"<YOUR_CUSTOMER_URI>",
        "generate_cert_on":"<master/node>"
        }
}

How to interact with the module

The integration provides options to generate the certificates individually in the Puppet master node and in the Puppet agent nodes. In addition, the integration provides the option to populate the certificates generated on the master into the agent nodes. To perform any certificate operation on the master, use the following command.

FACTER_task=<issue/collect/replace/revoke> FACTER_type=<ssl/client> puppet apply site.pp

To generate a certificate operation on agent nodes, use the following command.

FACTER_task=<issue/collect/replace/revoke> FACTER_type=<ssl/client> puppet agent -t

The following defines the commands:

  • FACTER_task generates certificates and applies one of the following operations: issue, collect, replace, revoke.

    If the FACTER_task command is not used, the issue operation is performed by default.

  • FACTER_type can be defined as either ssl or client.

    If the FACTER_type command is not used, then the already set fact is applied by default.

  • site.pp is the name of the Puppet manifest file that lists custom functions called from the Ruby library. This file ensures seamless generation of certificates on master and their propagation in agents, and generation of certificates on every agent.

Issuing certificates

Certificates are issued by executing the FACTER_task=issue command, with FACTER_type=ssl or FACTER_task=client depending on the certificate type.

Certificate issue on Puppet master

To run the entire configuration and deploy the certificates and their necessary packages on the agents, you need to execute the following command on a master server (the current working directory must be /etc/puppetlabs/code/environment/<environment_name>/manifest/).

FACTER_task=issue FACTER_type=<ssl/client> puppet apply site.pp

Once the command is executed, the following typically occurs:

  • If the Facter value of the sectigo_force parameter is true, backups of the existing files are created and a fresh certificate enrollment is done.

  • If the Facter value of the sectigo_force parameter is true and the IDS file is present, the certificate with that particular ID is collected.

  • If the Facter value of the sectigo_force parameter is false and no files are present, a fresh enroll takes place.

  • If the Facter value of the sectigo_force parameter is false and any artifact other than the IDS file is present, you are prompted to either empty the directory or set the value of the sectigo_force parameter to true.

The Puppet apply command only works in master; a configuration is programmed in the httpd.pp manifest file to the sectigo_puppet_module and it transfers the generated certificates to the agents.
Certificate generation on agent nodes using modules

Using deferred functions instead of regular Ruby functions, you can run the Ruby functions directly on agents instead of running them on the master server.

To generate certificates on agent nodes using modules, execute the following command.

FACTER_task=issue FACTER_type=<ssl/client> puppet agent -t

This command generates certificate files only on the agent on which it is executed.

Certificate transfer from the Puppet master to a Puppet agent

When a certificate generated on the Puppet master needs to be moved to a Puppet agent, you must change the generate_cert_on parameter in your config_sample_account.json file to node. Additionally, depending on the type of server deployment that you are using on your Puppet agent (for example, Apache, NGINX), you must update the last include statement in the site.pp file to reference the corresponding manifest in sectigo_puppet_module. For example, if you are using httpd on your Puppet agent, the site.pp file should be similar to the following.

Puppet Sectigo site.pp file
The config_sample_node_ssl.json file must be placed in your Facter directory on the Puppet agent.

You can then execute the following command on the Puppet agent directly.

puppet agent -t

The following diagram illustrates the certificate issuance flow.

Puppet Sectigo certificate issuance diagram

Collecting certificates

To collect a certificate, you start by adding values of the sectigo_ssl_cert_ssl_id or sectigo_client_cert_order_number parameter to the Facter file, therefore instructing Puppet to collect the certificate with a specific order number or certificate ID.

Execute the following command on the master.

FACTER_task=collect FACTER_type=<ssl/client> puppet apply site.pp

Execute the following command on the agent.

FACTER_task=collect FACTER_type=<ssl/client> puppet agent -t

Auto-renewing certificates and checking their validity

If the existing certificate has expired or is about to expire (within the period specified via the sectigo_expiry_window parameter), and the issue Facter task is called, the integration tries to renew the existing certificate.

The existing certificate-related files are not deleted and only renamed with a timestamp.

If auto-renewal is triggered for an SCM account configured such that certificates require manual approval, the following error message is displayed: {"code":-23,"description":"The certificate hasn’t been approved yet!"}

If this occurs, you need to approve the certificate request via SCM, and then use the collect Facter task instead of the issue Facter task to collect the certificate and to avoid generating additional unwanted certificates.

Replacing certificates

To replace a certificate, one of the following two conditions must be met:

  • Either you provide a CSR value by setting the sectigo_csr parameter and a value modification for any of the CSR, domain, or SANs parameters has taken place.

  • Or a value modification for any individual CSR, domain, or SANs parameters has taken place.

If either of the preceding two conditions are satisfied, run the following command on master or agent to replace your certificate.

  • master

  • agent

FACTER_task=replace FACTER_type=<ssl/client> puppet apply site.pp
FACTER_task=replace FACTER_type=<ssl/client> puppet agent -t

The following diagram illustrates the certificate replacement flow.

Puppet Sectigo certificate replacement diagram

Revoking certificates

To revoke a certificate, you must specify the reason via the sectigo_revoke_reason parameter in the Facter file. Replace the default comment in the file.

To proceed with revocation, execute the following command on master or agent.

  • master

  • agent

FACTER_task=revoke FACTER_type=<ssl/client> puppet apply site.pp
FACTER_task=revoke FACTER_type=<ssl/client> puppet agent -t

How to interpret the results

After you execute the FACTER_task=<task_name> FACTER_type=<ssl/client> puppet apply site.pp command in master, all the files, such as CSR, CRT, IDS, KEY, are stored in the sectigo_<ssl/client>_cert_file_path defined in the Facter file. For example, if the Facter value for the path is sectigo_ssl_cert_file_path="/etc/ssl/", then the files are generated and saved in the /etc/ssl/ directory.

When you execute the commands in agents, you must have the values set in the agent Facter file, and then when you execute the FACTER_task=<task_name> FACTER_type=<ssl/client> puppet agent -t command, it is generated and set at the location of the file path.

How to configure logging

By default, when working on the Puppet master, the commands to generate certificates are executed in the production/<production_name>/manifest/ directory, and the log output is stored in the same directory in a file named sectigo_puppet_module.log.

When working on the Puppet agent, you can execute the commands to generate certificates from any directory and therefore, by default, the log output is stored in your work directory in a file named sectigo_puppet_module.log.

The integration includes a logger that you can configure in the config_sample_issue_ssl.json or config_sample_issue_client.json file using parameters described in the following table. In the integration:

  • Logs are always stored in a log file whose path is configurable.

  • Logs can be sent to STDOUT.

  • Logs are rotated based on a maximum file size (for example, 10240000 bytes). The maximum file size and the maximum number of backed up log files are configurable.

Parameter Type Description

sectigo_logger_file_path

Optional

The path where the logs are stored. The default value is "./sectigo_puppet_module.log".

sectigo_logger_stdout_flag

Optional

A flag that determines if logs are sent to STDOUT. The default value is true.

sectigo_logger_max_file_size

Optional

The maximum file size for the rotated logs in bytes. The default value is 10240000.

sectigo_logger_max_num_backups

Optional

The maximum number of backup files for the rotated logs. The default value is 10.

How to use existing CSRs

You can provide an existing CSR by enabling the sectigo_csr parameter in the Facter file and providing the full path to the existing CSR file. If the .csr file is provided, the module uses it instead of creating a new file. The certificate issuance, collection, replacement, and revocation occurs using the content from the provided .csr files. For more information, see How to interpret the results.

How to automate execution

The run.sh script included in the integration’s package can be used as a cronjob (see Crontab.guru). It is executed at the specified time interval and runs all the commands defined in the script (see How to interact with the module). The script requires the following three arguments to be passed:

  • FACTER_type

  • FACTER_task

  • Your environment name in /environments/<environment_name>

Run the script as follows:

  1. Execute the following command on master.

    crontab -e
  2. Enter the following text and save.

    SHELL=/bin/bash
    */1 * * * * sudo /bin/bash
    /etc/puppetlabs/code/environments/dev/Sample/run.sh

When completed, files are created in the master file path.

The runinterval option available in Puppet allows you to enable automatic pulling of the generated certificates from Puppet master to agent nodes at defined time intervals. You can configure this option on each Puppet agent individually. When enabled, the agent checks whether or not it has all the files from the specified catalog (for example, a manifest file within the module), and then pulls these files at the interval specified in runinterval (for example, the files are pulled every hour if runinterval=1h).