Sectigo.com
Shop Enterprise Partners Resources

Using the integration

To use the integration, you need to configure your directory structure and then you can start interacting with the software.

Configure the work directory structure

You start configuration by unzipping the files and directories that are included in the packaged integration into the cookbooks folder of Chef, with the default typically located under /var/chef.

Every time you execute the knife command, you need to configure the file in the default location (current_location/.chef/config.rb). Alternatively, you can pass the configuration file while executing the knife command using the -config option. For example, -config config.rb.

Set up environment variables

There are three environment variables that must be specified as part of this package. These variables are located in the root user on the workstation and in the logged-in user on the Chef node. If you are interacting with the Bash directly on the Chef workstation or on your Chef node, you can set the following in your ~/.bashrc file.

export SECTIGO_CM_USER='<your_sectigo_username>'
export SECTIGO_CM_PASSWORD='<your_sectigo_password>'
export SECTIGO_CM_URI='<your_sectigo_uri>'

The Linux command to set these environment variables after adding them in ~/.bashrc is $ source ~/.bashrc.

If you are interacting with your Chef node remotely—​for example, through knife ssh—you need to add the following lines to your /etc/environment file.

SECTIGO_CM_USER='<your_sectigo_username>'
SECTIGO_CM_PASSWORD='<your_sectigo_password>'
SECTIGO_CM_URI='<your_sectigo_uri>'

Executing the Chef cookbooks

You can use the integration to issue, collect, replace, and revoke certificates.

Issue a certificate

To issue a certificate, you use the issue_certificate recipe described in [Sectigo Chef recipes]. Ensure you set the sectigo_cert_type parameter to ssl or client, depending on the certificate type with which you are working.

Use the Chef workstation to issue certificates

To issue certificates via the Chef workstation:

  1. Get the latest certificate by executing the existing recipes.

     chef-solo -j samples/ssl_params.json --log_level info

    Where samples/ssl_params.json is the parameter in the JSON file given in the package.

    {
    "run_list": [
        "recipe[sectigo_chef_cookbook::issue_certificate]"
    ],
    # customer specific
    "sectigo_cm_base_url":"https://<REPLACE_SECTIGO_CM_PORTAL>",
    "sectigo_cm_org_id":12345,
    "sectigo_cert_type":"ssl",
        .
        .
}

  2. Once the certificate is issued and collected, upload the cookbook to the Chef server.

    knife cookbook upload sectigo_chef_cookbook -cookbook-path /var/chef

  3. Configure the parameters for your Chef node.

    knife node edit name_of_chef_node

  4. Once the cookbook is uploaded to the Chef server, you can obtain the certificate on a Chef node.

    knife ssh 'name: name_of_chef_node' 'sudo chef-client'

    Where name_of_chef_node is the name of your Chef node. The <name_of_chef_node>.json file that is associated with your Chef node should be similar to the following.

    {
    "run_list": [
        "recipe[sectigo_chef_cookbook::copy_certificate]"
    ],
    # parameters
    "normal": {
        "sectigo_cert_type":"ssl", "sectigo_ssl_cert_file_path":"/etc/ssl/",
        "sectigo_ssl_cert_file_name":"sectigo_ssl",
         .
    }
     .
     .
}

    The same command may be used to trigger other recipes.

The following diagram illustrates the certificate issuance flow.

Sectigo Chef certificate issuance diagram

Execute the local cookbook on Chef nodes to issue certificates

You may issue different certificates on each individual Chef node by running the following command, where samples/ssl_params.json is the parameter in the JSON file given in the package.

sudo chef-client -j sample/ssl_params.json --log_level debug

Execute the remote cookbook on Chef nodes to issue certificates

To execute recipes remotely on Chef nodes:

  1. Modify your Chef node to specify the recipe to use along with its applicable parameters.

    knife node edit name_of_chef_node

  2. Trigger the recipe.

    knife ssh 'name:name_of_chef_node' 'sudo chef-client'

    Where name_of_chef_node is the name of your Chef node. The <name_of_chef_node>.json file that is associated with your Chef node should be similar to the following.

    {
    "run_list": [
        "recipe[sectigo_chef_cookbook::recipe_you_want_to_execute]"
    ],
    # parameters
    "normal": {
        "sectigo_cm_base_url":"https://<REPLACE_SECTIGO_CM_PORTAL>",
        "sectigo_cm_org_id":12345,
        "sectigo_cert_type":"ssl",
         .
    }
     .
     .
}

Replace a certificate

A certificate can be replaced if one of the following conditions is met:

  • A CSR value is provided via the sectigo_csr parameter, and a value has been modified for any of the sectigo_csr, domain, or SANs parameters.

  • A value has been modified for any individual CSR, domain, or SANs parameters.

To replace a certificate, follow the Replace a certificate recipe.

The following diagram illustrates the certificate replacement flow.

Sectigo Chef certificate replacement diagram

Revoke a certificate

To revoke a certificate, follow the Revoke a certificate recipe.

Collect a certificate

To collect a certificate, follow the Collect a certificate recipe.

Configure logging

The integration includes a logger that you can configure using parameters described in the following table.

In the integration:

  • Logs are always stored in a log file whose path can be configured

  • 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 can be configured

Parameter Type Description

sectigo_logger_file_path

Optional

The path where the logs are stored. The default value is ./sectigo_chef_cookbook.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 existing CSRs

You can provide an existing CSR by enabling the sectigo_csr parameter in the param.json file and supplying the file path. The cookbook will use this CSR instead of creating new one. The certificate enrollment, renewal, replacement, and collection uses the content from the provided sectigo_csr parameter.

Automating the execution of the cookbook on the Chef workstation

The sectigo-chef-workstation.sh script included in the integration’s package can be used as a cronjob (see Crontab.guru). It is executed at the defined time interval and runs all the commands defined in the script. The following example shows how to use crontab to run a cronjob, with the configuration on the workstation user root user.

PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/local/go/bin
* */2 * * * . ~/.bashrc; /home/centos/samples/sectigo-chef-workstation.sh >>
/home/centos/ /home/centos/samples/daily-backup.log 2>&1

The issue_certificate, replace_certificate, collect_certificate, or revoke_certificate recipe is used in the run_list to run on the workstation. The copy_certificate recipe in the run_list is only used for the Chef node. The preceding example executes the script for SSL every 2 hours.

Each location must be an absolute path.

Automating the execution of the cookbook on Chef nodes

The sectigo-chef-node.sh script included in the integration’s package can be used as a cronjob (see Crontab.guru). It is executed at the defined time interval and runs all the commands defined in the script. The following example shows how to use crontab to run a cronjob, with the configuration on the client node.

PATH=/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/local/go/bin
* */2 * * * . ~/.bashrc; /home/centos/samples/sectigo-chef-node.sh >>
/home/centos/ /home/centos/samples/daily-backup.log 2>&1

The use issue_certificate, replace_certificate, collect_certificate, or revoke_certificate recipe is used in the run_list to run to the node. The preceding example executes the sectigo-chef-node.sh script for SSL every 2 hours.