Using the integration

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 a certificate

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

Issue a certificate 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.

Issue a certificate 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.

Transfer a certificate 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.

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

Collect a certificate

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-renew a certificate and check its 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.

Replace a certificate

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

Revoke a certificate

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

Interpreting 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.

Configuring 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

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`.

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.

Using the 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 Interpreting the results.

Automating 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. 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:

Execute the following command on master.
```
crontab -e
```

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).