Default variables

Global PKI configuration

pki_enabled

Enable or disable PKI support.

pki_enabled: '{{ (True
                  if pki_default_domain
                  else False) | bool }}'
pki_internal

Enable or disable support for internal certificates.

pki_internal: '{{ (True
                   if pki_default_domain
                   else False) | bool }}'
pki_fqdn

Fully Qualified Domain Name of the remote host that is managed by the debops.pki role. This variable is important in Ansible tasks that maintain files in the secret/ directory, as well as correct identification of hosts which should have certificates signed by the internal Certificate Authority.

pki_fqdn: '{{ ansible_fqdn }}'
pki_inventory_groups

List of Ansible inventory group names which are taken into account while managing the PKI realms. These inventory groups will have their own directories in secret/pki/realms/by-group/ directory on Ansible Controller, and files put there will be copied to remote hosts.

pki_inventory_groups: [ 'debops_service_pki' ]

Automatic Certificate Management Environment

pki_acme

Enable or disable support for ACME certificates.

pki_acme: '{{ (True
               if ((ansible_all_ipv4_addresses +
                    ansible_all_ipv6_addresses) | ipaddr("public") and
                    pki_default_domain)
               else False) | bool }}'
pki_acme_install

Install ACME support but don’t enable it by default for each realm.

pki_acme_install: '{{ pki_acme | bool }}'
pki_acme_library

The crypto library used to generate Certificate Signing Requests for ACME certificates, either openssl or gnutls. Currently OpenSSL is recommended due to issues with GnuTLS generation.

pki_acme_library: 'openssl'
pki_acme_user

Name of the system user account which will be used to interact with the ACME Certificate Authority.

pki_acme_user: 'pki-acme'
pki_acme_group

Name of the system group which will be used to interact with the ACME Certificate Authority.

pki_acme_group: 'pki-acme'
pki_acme_home

Home of the user account that interacts with ACME Certificate Authority.

pki_acme_home: '/run/pki-acme'
pki_acme_default_subdomains

List of DNS subdomains that will be added by default to each apex (root) domain configured in ACME Certificate Signing Requests.

pki_acme_default_subdomains: [ 'www' ]
pki_acme_type

ACME client to use to interact with the ACME Certificate Authority. At the moment only acme-tiny is supported.

pki_acme_type: 'acme-tiny'
pki_acme_tiny_repo

URL of the acme-tiny git repository.

pki_acme_tiny_repo: 'https://github.com/diafygi/acme-tiny'
pki_acme_tiny_version

Branch of the acme-tiny source which should be checked out for deployment.

pki_acme_tiny_version: 'master'
pki_acme_tiny_src

Directory where acme-tiny source code will be cloned into for deployment.

pki_acme_tiny_src: '{{ (ansible_local.root.src
                        if (ansible_local|d() and ansible_local.root|d() and
                            ansible_local.root.src|d())
                        else "/usr/local/src") + "/" + pki_acme_user }}'
pki_acme_tiny_bin

Path where acme-tiny script will be installed.

pki_acme_tiny_bin: '/usr/local/lib/pki/acme-tiny'
pki_acme_ca

Name of the ACME API endpoint used by the ACME client. The name-URL mapping is done in pki_acme_ca_api_map dictionary variable.

pki_acme_ca: 'le-live'
pki_acme_ca_api_map

Dictionary map of the ACME API endpoints, mapped to custom names, used by the ACME client.

pki_acme_ca_api_map:
  'le-live':    'https://acme-v01.api.letsencrypt.org'
  'le-staging': 'https://acme-staging.api.letsencrypt.org'
pki_acme_challenge

Directory where ACME client should store responses to ACME CA challenges. By default it’s defined by the debops.nginx Ansible role using Ansible facts.

pki_acme_challenge_dir: '{{ (ansible_local.nginx.acme_root
                             if (ansible_local|d() and ansible_local.nginx|d() and
                                 ansible_local.nginx.acme_root|d())
                             else "/srv/www/sites/acme/public") +
                             "/.well-known/acme-challenge" }}'

APT package lists

pki_base_packages

List of APT packages to install by default on the remote host for cryptographic support.

pki_base_packages: [ 'ssl-cert', 'make', 'ca-certificates',
                     'gnutls-bin', 'openssl' ]
pki_acme_packages

List of APT packages required by ACME support.

pki_acme_packages: [ 'curl', 'git' ]
pki_packages

List of additional APT packages to install.

pki_packages: []

Directory, file and user/group configuration

pki_root

Root directory of the PKI configuration on remote hosts.

pki_root: '/etc/pki'
pki_public_group

Default system group which owns the public files and directories.

pki_public_group: 'root'
pki_private_group

Default system group which owns the private files and directories.

pki_private_group: 'ssl-cert'
pki_public_dir_mode

Octal permissions of the public directories.

pki_public_dir_mode: '0755'
pki_private_dir_mode

Octal permissions of private directories.

pki_private_dir_mode: '0750'
pki_public_mode

Octal permissions of public files.

pki_public_mode: '0644'
pki_private_mode

Octal permissions of private files.

pki_private_mode: '0640'
pki_private_groups_present

Create system group specified here if they don’t exist. This can be used to ensure that private directories and files are owned by correct group before the role that creates the group is run by Ansible. See pki_private_groups_present for more details.

pki_private_groups_present: []

Certificate sign times

pki_default_sign_base

The base amount of time in days which is used for signing various certificates. By default, 1 year.

pki_default_sign_base: '365'
pki_default_root_sign_multiplier

Amount of time which Root Certificate Authority will be valid, multiplied by the base time amount.

pki_default_root_sign_multiplier: '12'
pki_default_ca_sign_multiplier

Amount of time which intermediate CA certificates will be valid, multiplied by the base time amount.

pki_default_ca_sign_multiplier: '10'
pki_default_cert_sign_multiplier

Amount of time which client/server certificates will be valid, multiplied by the base time amount.

pki_default_cert_sign_multiplier: '3'

Configuration of PKI Realms

pki_library

The crypto library used to manage PKI realms on remote hosts, either gnutls or openssl. GnuTLS is preferred on Debian hosts.

pki_library: 'gnutls'
pki_system_realm

System-wide PKI realm which is used by services by default for server certificates. It will be set in Ansible local facts for use by other Ansible roles.

pki_system_realm: '{{ ansible_local.pki.realm
                      if (ansible_local|d() and ansible_local.pki|d() and
                          ansible_local.pki.realm|d())
                      else "domain" }}'
pki_system_ca_realm

System-wide PKI realm which is used by services by default for CA certificate (client authentication). It will be set in Ansible local facts for use by other Ansible roles.

pki_system_ca_realm: '{{ pki_system_realm }}'
pki_default_domain

Default DNS domain used to create Certificate Signing Requests. It will be specified in the certificate Subject if it’s not redefined, as well as in the certificate SubjectAltName field.

pki_default_domain: '{{ ansible_domain }}'
pki_default_subdomains

List of additional subdomains added by default to all domain specified in the Certificate Signing Request. The _wildcard_ is a replacement for the * character and means that each domain will have an alternative wildcard SubjectAltName.

pki_default_subdomains: [ '_wildcard_' ]
pki_realms

List of PKI realms configured on all hosts.

pki_realms: []
pki_default_realms

List of the default PKI realms configured on all hosts.

pki_default_realms:

  - name: 'domain'
    acme: False
pki_group_realms

List of PKI realms configured in specific inventory groups.

pki_group_realms: []
pki_host_realms

List of PKI realms configured on specific hosts.

pki_host_realms: []
pki_dependent_realms

List of PKI realms configured in a role dependency.

pki_dependent_realms: []
pki_scheduler

Enable periodic runs of pki-realm script for all PKI realms. The script will check realm structure and renew certificates that are near their expiration date.

pki_scheduler: True
pki_scheduler_interval

Specify the interval of periodical tasks: hourly, daily, weekly or monthly.

pki_scheduler_interval: 'weekly'
pki_dhparam

Specify if Diffie-Hellman parameters should be appended to the certificate chain, required by specific applications like HAproxy, ZNC or others that don’t support DHE parameters in a separate file.

pki_dhparam: '{{ (True
                  if (ansible_local|d() and ansible_local.dhparam|d() and
                      ansible_local.dhparam.default|d())
                  else False) | bool }}'
pki_dhparam_file

Path to the Diffie-Hellman parameters file which will be appended to the certificate chain, if specified.

pki_dhparam_file: '{{ ansible_local.dhparam.default
                      if (ansible_local|d() and ansible_local.dhparam|d() and
                          ansible_local.dhparam.default)
                      else "" }}'

Configuration of PKI Certificate Authorities

pki_ca_library

The crypto library used by the Certificate Authorities on the Ansible Controller, either openssl or gnutls. Currently OpenSSL library is preferred due to rich functionality.

pki_ca_library: 'openssl'
pki_default_authority

Name of the default Certificate Authority to which host certificates are directed if a PKI realm does not specify a default Authority.

pki_default_authority: 'domain'
pki_ca_domain

The DNS domain used by default for an Certificate Authority configuration if no specific item.domain is configured.

pki_ca_domain: '{{ ansible_domain if ansible_domain else ansible_hostname }}'
pki_authorities

List of internal Certificate Authorities managed on an Ansible Controller. Each CA is defined as a dictionary variable.

pki_authorities:
  - '{{ pki_authorities_ca_root }}'
  - '{{ pki_authorities_ca_domain }}'
  - '{{ pki_authorities_ca_service }}'
pki_ca_organization

The organizations name to be used in Distinguished Names (subject).

pki_ca_organization: '{{ pki_ca_domain.split(".") | first | capitalize }}'
pki_ca_root_dn

The Distinguished Name (subject) of the Root Certificate Authority.

pki_ca_root_dn: [ 'o={{ pki_ca_organization }} Certificate Authority' ]
pki_ca_domain_dn

The Distinguished Name (subject) of the Domain Certificate Authority.

pki_ca_domain_dn: [ 'o={{ pki_ca_organization }}', 'ou=Domain CA' ]
pki_ca_service_enabled

Enable or disable special Service Certificate Authority, which is a Root CA without intermediate CA and sign server certificates directly. This might be needed by specific applications like MySQL which do not support an intermediate CA.

pki_ca_service_enabled: False
pki_ca_service_dn

The Distinguished Name (subject) of the Service Certificate Authority.

pki_ca_service_dn: [ 'o={{ pki_ca_organization }}', 'ou=Internal Services CA' ]
pki_authorities_ca_root

Configuration of the Root Certificate Authority.

pki_authorities_ca_root:
  name: 'root'
  subdomain: 'root-ca'
  subject: '{{ pki_ca_root_dn }}'
pki_authorities_ca_domain

Configuration of the Domain Certificate Authority.

pki_authorities_ca_domain:
  name: 'domain'
  subdomain: 'domain-ca'
  subject: '{{ pki_ca_domain_dn }}'
  issuer_name: 'root'
pki_authorities_ca_service

Configuration of the Service Certificate Authority.

pki_authorities_ca_service:
  name: 'service'
  subdomain: 'service-ca'
  subject: '{{ pki_ca_service_dn }}'
  type: 'service'
  enabled: '{{ pki_ca_service_enabled | bool }}'
pki_dependent_authorities

List of Certificate Authorities defined as a role dependency.

pki_dependent_authorities: []
pki_ca_certificates_path

The path inside secret/ca-certificates/ directory located on Ansible Controller where Root CA certificates will be symlinked by default. Can be one of:

  • by-group/all - certificates copied to all hosts;
  • by-group/{{ group_name }} - certificates copied to hosts in a specified inventory group;
  • by-host/{{ pki_fqdn }} - certificates copied to a specific host;
pki_ca_certificates_path: 'by-group/all'

Custom file management

You can use custom file lists to copy files to remote hosts or install contents of Jinja variables. See Custom file management for more details.

pki_private_files

Copy private files to all hosts in inventory.

pki_private_files: []
pki_group_private_files

Copy private files to hosts in specific inventory groups.

pki_group_private_files: []
pki_host_private_files

Copy private files to specific hosts in inventory.

pki_host_private_files: []
pki_public_files

Copy public files to all hosts in inventory.

pki_public_files: []
pki_group_public_files

Copy public files to hosts in specific inventory group.

pki_group_public_files: []
pki_host_public_files

Copy public files to specific hosts in inventory.

pki_host_public_files: []

System-wide Root CA Certificates

See System CA certificates for more details about management of system-wide CA certificates.

pki_system_ca_certificates_trust_new

Set default trust policy for new certificates added to ca-certificates system package.

pki_system_ca_certificates_trust_new: True
pki_system_ca_certificates_blacklist

List of blacklisted CA certificates. You can specify either exact names of certificate files or use regular expressions. If a certificate is found in both lists, it will be blacklisted.

pki_system_ca_certificates_blacklist:

  # Blacklist CNNIC Root Certificates
  # http://googleonlinesecurity.blogspot.com/2015/03/maintaining-digital-certificate-security.html
  - 'mozilla/CNNIC_ROOT.crt'
  - 'mozilla/China_Internet_Network_Information_Center_EV_Certificates_Root.crt'
pki_system_ca_certificates_whitelist

List of whitelisted CA certificates. You can specify either exact names of certificate files or use regular expressions.

pki_system_ca_certificates_whitelist: []