Custom hook scripts

The pki-realm script supports usage of a custom hook scripts located in the /etc/pki/hooks/ directory. These scripts will be executed in alphabetical order (see run-parts(8) for more details) within a special environment. You can use that to perform operations after certain actions like creation of a new PKI realm, or activation of a new certificate.

Execution environment

The hook scripts will be executed by the root account inside the PKI hook directory (/etc/pki/hooks/), with a set of $PKI_SCRIPT_* environment variables:

$PKI_SCRIPT_REALM

Contains the name of the current PKI realm.

$PKI_SCRIPT_FQDN

Contains Fully Qualified Domain Name used as the default domain if the realm does not specify one in it's name.

$PKI_SCRIPT_SUBJECT

Contains the Distinguished Name, or subject of the certificate, each element separated by the / character, similar to the format of the openssl req -subj option.

$PKI_SCRIPT_DOMAINS

List of apex (root) domains configured for the realm, separated by the / character.

$PKI_SCRIPT_SUBDOMAINS

List of subdomains which should be added to each apex domain, each one separated by the / character. The special _wildcard_ name means a wildcard subdomain (*.example.com).

$PKI_SCRIPT_PRIVATE_KEY

Absolute path to the private key of the current PKI realm.

$PKI_SCRIPT_DEFAULT_CRT

Absolute path to the current PKI realm certificate chain, expected to be used in the application configuration files.

$PKI_SCRIPT_DEFAULT_KEY

Absolute path to the current PKI realm private key, expected to be used in the application configuration files.

$PKI_SCRIPT_DEFAULT_PEM

Absolute path to the current PKI realm combined private key and certificate chain, expected to be used in the application configuration files.

$PKI_SCRIPT_STATE

A list of PKI realm states separated by the , character. You can inspect this variable to determine the current state of the realm (initialization, activation of new certificates, changed files) and react to it in the script.

Known script states

You can use the $PKI_SCRIPT_STATE variable to check current state of the PKI realm. This variable should always be non-empty, otherwise hook scripts are not executed. Each state can repeat multiple times on the list, but you should avoid multiple execution due to a particular state.

List of known states:

new-realm

A new PKI realm has been initialized, there are no private keys or certificates present.

new-private-key

A private key has been generated.

new-internal-request

A new internal CA certificate signing request has been generated.

new-acme-request

A new ACME certificate signing request has been generated.

changed-certificate

A new certificate has been activated, or there has been change of the active Certificate Authority (internal, external, acme).

changed-dhparam

Diffie-Hellman parameters in the certificate chain have been added/updated.

file-change

A generic file change notification.

file-deletion

A file has been deleted.

changed-public-file

Some of the files in public/ directory have been changed/replaced.

changed-private-file

Some of the files in private/ directory have been changed/replaced.

Example nginx hook

This is an example hook script which detects if a given PKI realm is currently used by the nginx server and if so, when a certificate change is detected it reloads the nginx daemon so that new certificate can be activated.

#!/bin/bash

# Reload or restart nginx on a certificate state change

set -o nounset -o pipefail -o errexit

nginx_config="/etc/nginx/nginx.conf"
nginx_sites="/etc/nginx/sites-enabled"
nginx_action="reload"

# Check if current PKI realm is used by the 'nginx' webserver
certificate=$(grep -r "${PKI_SCRIPT_DEFAULT_CRT:-}" ${nginx_sites}/* || true)

# Get list of current realm states
states=( $(echo "${PKI_SCRIPT_STATE:-}" | tr "," " ") )

if [ -n "${certificate}" -a "${#states[@]}" -gt 0 ] ; then

    for state in "${states[@]}" ; do

        if [ "${state}" = "changed-certificate" -o "${state}" = "changed-dhparam" ] ; then

            # Check if current init is systemd
            if $(pidof systemd > /dev/null 2>&1) ; then

                nginx_state="$(systemctl is-active nginx.service)"
                if [ ${nginx_state} = "active" ] ; then
                    if $(/usr/sbin/nginx -c ${nginx_config} -t > /dev/null 2>&1) ; then
                        systemctl ${nginx_action} nginx.service
                    fi
                fi

            else

                nginx_pidfile="$(grep -E '^pid\s+' ${nginx_config} | awk '{print $2}' | cut -d\; -f1)"
                if $(kill -0 $(<${nginx_pidfile}) > /dev/null 2>&1) ; then
                    if $(/usr/sbin/nginx -c ${nginx_config} -t > /dev/null 2>&1) ; then
                        service nginx ${nginx_action}
                    fi
                fi

            fi

            break
        fi

    done

fi