Using the module

This page describes how to use the Sectigo SaltStack module.

Configuring the SaltStack work directory structure

The salt and pillar directories that are included in this integration’s package include all the files that are required by the Sectigo SaltStack module. These directories are generally placed inside the /srv/ directory on Linux systems. In order to use the Sectigo SaltStack module, the contents of the salt and pillar directories must be placed in the /srv/salt/ and /srv/pillar/ directories (or equivalent) on your master node, respectively.

Configuring the SaltStack master

Once you have a salt-master installed on your Linux system, you must configure the paths for the salt and pillar directories in the master configuration file. This configuration file is generally located by default at /etc/salt/master. You must set the following fields in the salt-master configuration file if they are not already set (you may uncomment the fields if they already exist but are commented).

file_roots:
  base:
    -/srv/salt (where "/srv/salt" is the path to the salt folder provided by Sectigo)

pillar_roots:
  base:
    -/srv/pillar (where "/srv/pillar" is the path to the pillar folder provided by Sectigo)

runner_dirs:
  -/srv/salt/_runners (where "/srv/_runners" is the path to the _runners folder provided by Sectigo)

Setting up environmental variables

There are three environmental variables that must be specified as part of this package. The variables for Linux are the following.

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.

Interacting with the module

This section describes how to interact with the SaltStack module.

This integration was designed and tested to work with a root user as the SaltStack default setup runs the master and minion as the root user. In order to use the integration with as a non-root user, you must configure the ownership and permissions of your work directories accordingly. For more information, see the SaltStack documentation.

Files synchronization between master and target minion nodes

You must ensure that the master and (target) minion nodes are synchronized by running the following command.

salt 'target' saltutil.sync_all

This command syncs all the files on the target minions. If there is more than one minion with a similar prefix you can also make use of wildcard. For example, if there are 3 target minions with the names dev1, dev2, and dev3, and all 3 machines need to have the same certificate, then you pass the following command.

salt 'dev*' saltutil.sync_all

To sync runners specifically, run the following command.

salt-run saltutil.sync_runners

Certificates issuance and collection

There are two techniques that can be used to generate certificates using the Sectigo SaltStack module:

Generating certificates on a master node using runners
Generating certificates on minion nodes using execution modules

If you have already issued a certificate, and would like to generate another one, either set the sectigo_force parameter to True, or select a new filename.

Generating certificates on a master node by using runners

In order to run the entire configuration and deploy the certificates and their necessary packages on the minions, run the following command on a master node.

salt-run sectigo_saltstack_module.main <cert_type> <cert_config_file>

If you added any new pillar config files, see Filename requirements.

This command will call the Python modules and make respective API calls to SCM based on the current state.

Example SSL

salt-run sectigo_saltstack_module.main ssl sectigo_ssl_certificate

Example client

salt-run sectigo_saltstack_module.main client sectigo_client_certificate

You can only run the command above on a master node. All the certificate-related files that get generated are stored on the master from where they get transferred to the minions using a push or a pull mechanism.

Push Model (Run on Master): In the push mechanism, the master pushes the configuration and the certificate-related files to the minions. Since you are running the command on a master node, you must specify the target.
```
salt 'target' state.apply "pillar={'cert_type': '<cert_type>', 'cert_config_file': '<pillar_file_name>'}"
```
This command will set the necessary state of the minions according to the OS and the state file that is defined for that OS.
Pull Model (Run on Minions): In the pull mechanism, the minions can pull the state from the master and adjust their own configurations accordingly. Since you are directly running the command on a minion node, you do not have to specify the target.
```
salt-call state.apply "pillar={'cert_type': '<cert_type>', 'cert_config_file': '<pillar_file_name>'}"
```

All _state sample files provided in this package are for SSL certificates. If you need to use the push or pull mechanisms for client certificates you will need to create your own _client.sls files and modify the sectigo_configuration file for client certificates. More information on creating state files can be found here.

Generating certificates on minion nodes by using execution modules

It is possible to execute the Python files directly on minions instead of running them on the master node. For this, you need to use execution modules instead of runners and copy the contents from the salt/_runners/ folder into the salt/_modules/ folder. You must make sure all the Python related prerequisites are configured on the minions. Additionally, if you have made any configuration changes on the master, you must re-synchronize the files by re-running the salt 'target' saltutil.sync_all command.

For execution modules, it is not necessary to set the environment variables on minions. However, you need to update the env_vars.sls file in the salt/pillar folder with your Sectigo account related credentials.

This file is only necessary in the case of execution modules, and not runner modules.

The following command can then be executed.

salt 'target' sectigo_saltstack_module.main <cert_type> <cert_config_file>

Example SSL

salt 'target' sectigo_saltstack_module.main ssl sectigo_ssl_certificate

Example client

salt 'target' sectigo_saltstack_module.main client sectigo_client_certificate

This will execute the script on all the target minions and might cause the operations like Enroll and Renew to be executed separately on each minion.

Certificate auto renewal and validity check

If the existing certificate is expired or is about to expire (within the specified sectigo_expiry_window), the Sectigo SaltStack module will try and enroll a new certificate.

The module makes use of the existing .key and .csr files if they are available.

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

Certificate replacement

In order to replace a certificate, one of the following conditions must be met:

A CSR value is provided using sectigo_csr, and a value of any sectigo_csr, domain, or SANs parameters has been modified.
A value of any individual CSR, domain, or SANs parameters has been modified.

If either of the two conditions are satisfied, you can replace your certificate by running the following command.

salt-run sectigo_saltstack_module.main <cert_type> <cert_config_file>

The certificate replacement behavior is shown in the following diagram.

Sectigo SaltStack certificate replacement

Certificate revocation

In order to revoke an existing certificate, you must change the value of the revoke parameter (sectigo_ssl_cert_revoke for SSL certs or sectigo_client_cert_revoke for client certs) to True in your pillar configuration file, and run the following command.

salt-run sectigo_saltstack_module.main <cert_type> <cert_config_file>

Output

There are different forms of output that you may get when attempting to issue a certificate using the Sectigo SaltStack module. The output depends on how you interact with the plugin.

Output from generating certificates on a master node using runners

When working directly on the master node, the Sectigo SaltStack module initially stores the issued certificate, key, and CSR files on the master node’s file system. The file path that’s used for this storage is set dynamically, and it follows the following pattern.

salt/files/certs/<minion_name>/<sectigo_ssl_cert_file_path>

The salt/files path already exists on the master node; the certs directory and its content get dynamically generated when you execute the following command.

salt-run sectigo_saltstack_module.main <cert_type> <cert_config_file>

In the case of a single minion, <minion_name> consists of the minion’s hostname (for example, Minion1). In the case of a wildcard, the <minion_name> consists of the common prefix element in the wildcard, along with _allMinions as a suffix. For example, suppose that you have three minions, APP1-Minion1, APP1-Minion2, and APP1-Minion3, if you use APP1* as your target wildcard, the <minion_name> will be APP1_allMinions.

It is also possible to issue different certificates for different wildcards, for more information see Issuing certificates using runners for multiple minion wildcards.

Output from generating certificates on minion nodes using execution modules

When using the execution modules to issue certificates directly on minion nodes, the certificates are stored directly under the path specified in the sectigo_ssl_cert_file_path parameter.

In other words, if you set sectigo_ssl_cert_file_path to be /etc/ssl/, then when you run the following command, the resulting certificate, key, and CSR files will be stored directly inside /etc/ssl/.

salt 'target' sectigo_saltstack_module.main <cert_type> <cert_config_file>

Logs

If you are running the commands manually, the entire trace is shown on the screen and is also stored in the sectigo_saltstack.log file present in the location from where the command is executed.

You can also enable SaltStack logging as per your needs by referring to the SaltStack documentation.

If you are working with the runner module, and you execute commands manually on the master, the log files will be generated in your current work directory. If you use the run.sh file provided with the package, the logs will be generated by default on minions in the /<filename>.log directory. If you are running the execution module using the salt-call command on a minion, since it’s a manual step, the logs will be generated in your current work directory.

Salt master logs and Salt minion logs are typically located at /var/log/salt/master and /var/log/salt/minion, respectively.

Using existing CSRs

If you want to provide the existing CSR, you can do that by enabling the sectigo_csr parameter in the pillar file and giving the exact full path of the .csr file, also making sure the file exists. If the .csr file is provided, the module will use it instead of creating a new one. The certificate enrollment, renewal, replacement, or collection uses the content from the provided .csr files.

The system assumes that you already have the KEY file and will NOT generate a KEY. You can provide the existing CSR by passing the full file path in the sectigo_csr parameter (for example, /etc/ssl/sectigo_ssl.csr). All the other files will be present in the sectigo_ssl_cert_file_path (for SSL) and sectigo_client_cert_file_path (for client) folders.

For more details on how the files are stored, see the Output section.

Automating the execution

The run.sh script included in the integration’s package can be used as a cronjob. It will be executed at the defined time interval, and run all the commands defined in the Interacting with the module section. For information about setting the cronjobs, see Crontab.guru. The script requires 3 arguments to be passed: <cert_type>, <cert_config_file>, <target>. Make sure to add executable permissions to the run.sh file with the chmod +x /srv/run.sh command. The script considers the default salt root path as /srv/.

The following sample cronjob command will execute the script for SSL every two hours.

0 */2 * * * /srv/run.sh ssl sectigo_ssl_certificate minion*