debops.pki default variables

Sections

Global PKI configuration
Automatic Certificate Management Environment
Certbot configuration
Required software packages
Directory, file and user/group configuration
Certificate sign times
Configuration of PKI Realms
Internal Certificate Authorities
Custom file management
System-wide CA Certificates

Global PKI configuration 

pki_enabled

Enable or disable PKI support.

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

pki_download_extra

Enable or disable extra file copying.

pki_download_extra: True

pki_internal

Enable or disable support for internal certificates. If the support is disabled, the PKI realm will generate its own set of self-signed certificates on remote hosts.

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

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 inside the secret/pki/realms/by-group/ directory on the Ansible Controller, and files put there will be copied to remote hosts.

pki_inventory_groups: [ 'debops_service_pki' ]

pki_vcs_ignore_patterns_role

This list of ignore patterns for files below /etc/pki that version control systems should ignore. /etc is not tracked by default by a version control system. This definition exists preliminary in case you decide to use etckeeper for example to track changes in /etc. In case you want to track sensitive files by a version control system specify:

 pki_vcs_ignore_patterns_role: []

in your inventory and be sure that you know what you are doing!

Note that currently, only git as version control system is supported. If you use another version control system, be sure to add support for it to this role. Ignore patterns are specified using the .gitignore file format documented in gitignore(5). By default, any file path below /etc/pki contained in a subdirectory called private will not be tracked.

Note

When you started using this role before version 0.2.11 and sensitive files are already tracked by version control you will need to manually deleted them from version control history!

pki_vcs_ignore_patterns_role: [ '**/private/**' ]

pki_vcs_ignore_patterns

Refer to pki_vcs_ignore_patterns_role for details. This variable is intended to be used in Ansible’s global inventory and allows you to define additional file patterns without having to overwrite the recommended ignore list maintained by this role.

pki_vcs_ignore_patterns: []

pki_vcs_ignore_patterns_group

Refer to pki_vcs_ignore_patterns_role for details. This variable is intended to be used in a host inventory group of Ansible (only one host group is supported) and allows you to define additional file patterns without having to overwrite the recommended ignore list maintained by this role.

pki_vcs_ignore_patterns_group: []

pki_vcs_ignore_patterns_host

Refer to pki_vcs_ignore_patterns_role for details. This variable is intended to be used in a host inventory group of Ansible (only one host group is supported) and allows you to define additional file patterns without having to overwrite the recommended ignore list maintained by this role.

pki_vcs_ignore_patterns_host: []

Automatic Certificate Management Environment 

pki_acme

Enable or disable support for ACME certificates.

pki_acme: '{{ (True
               if (((ansible_all_ipv4_addresses | d([]) +
                     ansible_all_ipv6_addresses | d([])) | ansible.utils.ipaddr("public")
                    and pki_default_domain)
                   or pki_acme_type != "acme-tiny")
               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 the 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: []

pki_acme_type

ACME client to use to interact with the ACME Certificate Authority. Supported values: 'acme-tiny', 'dns-cloudflare', 'dns-digitalocean', 'dns-dnsimple', 'dns-gehirn', 'dns-google', 'dns-linode', 'dns-ovh', 'dns-rfc2136', 'dns-route53', 'dns-sakuracloud', 'dns-gandi'

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 or version of the acme-tiny source which should be used.

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.fhs.src | d("/usr/local/src"))
                       + "/" + pki_acme_user }}'

pki_acme_tiny_bin

Path where the acme-tiny script will be installed.

pki_acme_tiny_bin: '/usr/local/bin/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-v2'

pki_acme_ca_api_map

Dictionary map of the ACME API endpoints, mapped to custom names, used by the ACME client. Refer to the Let's Encrypt Staging Environment documentation for details about le-staging-v2.

pki_acme_ca_api_map:
  'le-live':    'https://acme-v01.api.letsencrypt.org'
  'le-staging': 'https://acme-staging.api.letsencrypt.org'
  'le-live-v2': 'https://acme-v02.api.letsencrypt.org/directory'
  'le-staging-v2': 'https://acme-staging-v02.api.letsencrypt.org/directory'

pki_acme_contacts

List of (mailto:) URLs that the ACME server can use to contact you for issues related to your account. For example, the server may wish to notify you about server-initiated revocation or certificate expiration.

pki_acme_contacts: [ 'mailto:{{ ansible_local.core.admin_public_email[0] | d("root@" + ansible_domain) }}' ]

pki_acme_challenge_dir

Directory where the 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 | d("/srv/www/sites/acme/public")
                            + "/.well-known/acme-challenge" }}'

pki_create_acme_challenge_dir

Whether the directory where the ACME client should store responses should be created.

pki_create_acme_challenge_dir: '{{ True if (ansible_local.nginx.acme | d() and
                                            ansible_local.nginx.acme | bool) else False }}'

Certbot configuration 

The lists below define the contents of the /etc/letsencrypt/cli.ini configuration file. See pki_certbot_configuration for more details.

pki_certbot_default_configuration

The default contents of the Certbot configuration file defined by the role.

pki_certbot_default_configuration:

  - name: 'max-log-backups'
    comment: |
      Because we are using logrotate for greater flexibility, disable the
      internal certbot logrotation.
    value: 0

  - name: 'post-hook'
    comment: |
      The certbot script does not execute post-hooks on initial certificate
      issuance, only renewals. This should ensure that the permissions are
      fixed when certificates are created.
    value: '/etc/letsencrypt/renewal-hooks/post/000-fix-permissions'

pki_certbot_configuration

The contents of the Certbot configuration file defined by the user.

pki_certbot_configuration: []

pki_certbot_combined_configuration

The variable which combines the Certbot configuration variables and is used in role tasks and templates.

pki_certbot_combined_configuration: '{{ pki_certbot_default_configuration
                                        + pki_certbot_configuration }}'

Required software packages 

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', 'acl' ]

pki_acme_packages

List of APT packages required by ACME support.

pki_acme_packages:
  - '{{ "curl" if (pki_acme_type == "acme-tiny" and pki_acme_install | bool) else [] }}'
  - '{{ "git" if (pki_acme_type == "acme-tiny" and pki_acme_install | bool) else [] }}'
  - '{{ [] if (pki_acme_install | bool == false or ansible_distribution_release in
               ["stretch", "trusty", "xenial", "bionic"])
           else "acme-tiny" if (pki_acme_type == "acme-tiny") else [] }}'
  - '{{ "python3-certbot-dns-cloudflare" if (pki_acme_type == "dns-cloudflare" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-digitalocean" if (pki_acme_type == "dns-digitalocean" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-dnsimple" if (pki_acme_type == "dns-dnsimple" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-gehirn" if (pki_acme_type == "dns-gehirn" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-google" if (pki_acme_type == "dns-google" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-linode" if (pki_acme_type == "dns-linode" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-ovh" if (pki_acme_type == "dns-ovh" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-rfc2136" if (pki_acme_type == "dns-rfc2136" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-route53" if (pki_acme_type == "dns-route53" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-sakuracloud" if (pki_acme_type == "dns-sakuracloud" and pki_acme_install | bool) else [] }}'
  - '{{ "python3-certbot-dns-gandi" if (pki_acme_type == "dns-gandi" and pki_acme_install | bool) else [] }}'
  - '{{ "certbot" if (pki_acme_type in
                ["dns-cloudflare", "dns-digitalocean",
                 "dns-dnsimple", "dns-gehirn", "dns-google",
                 "dns-linode", "dns-ovh", "dns-rfc2136",
                 "dns-route53", "dns-sakuracloud", "dns-gandi", "manual"]
           and pki_acme_install | bool) else [] }}'

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: []

pki_private_dir_acl_groups

List of system groups which should have access to the private directory of each realm, unless specified otherwise. The execute access will be granted using the filesystem ACL table.

pki_private_dir_acl_groups: []

pki_private_file_acl_groups

List of system groups which should have read access to key files in private/ directory of each realm, unless specified otherwise. The read access will be granted using the filesystem ACL table.

pki_private_file_acl_groups: []

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_realm_key_size

The key size in bits to use when generating realm RSA keys.

pki_realm_key_size: '2048'

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 | d("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_authority_preference

Order in which different certificate types are used. First certificate type found wins.

pki_authority_preference: [ 'external', 'acme', 'internal', 'selfsigned' ]

pki_realms

List of PKI realms configured on all hosts. Refer to the documentation of all options for more details.

pki_realms: []

pki_default_realms

List of the default PKI realms configured on all hosts.

pki_default_realms:

  - name: 'domain'
    acme: False
    default_subdomains:
      - '{{ ansible_hostname }}'
      - '*.{{ ansible_hostname }}'
      - '_wildcard_'

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. This is required by applications that don't support DHE parameters in a separate file like HAproxy, ZNC.

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

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 | d("") }}'

Internal 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_name_constraints

Specify if the nameConstraints CA certificate extension should be included in the generated CA certificates by default.

pki_ca_name_constraints: True

pki_ca_name_constraints_critical

Specify if the nameConstraints CA certificate extension should be marked critical by default. Enabling this when using nameConstraints is recommended by the CA/Browser Forum. Ref: https://cabforum.org/wp-content/uploads/CA-Browser-Forum-BR-1.6.4.pdf

pki_ca_name_constraints_critical: True

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 }}'

pki_ca_organization

A string with the organization's 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_root_key_size

The key size in bits to use when generating the RSA Root CA key.

pki_ca_root_key_size: '4096'

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_domain_key_size

The key size in bits to use when generating the RSA Domain CA key.

pki_ca_domain_key_size: '4096'

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_ca_service_key_size

The key size in bits to use when generating the RSA Service CA key.

pki_ca_service_key_size: '4096'

pki_authorities_ca_root

Configuration of the Root Certificate Authority.

pki_authorities_ca_root:
  name: 'root'
  enabled: '{{ True if pki_ca_domain | d() else False }}'
  subdomain: 'root-ca'
  subject: '{{ pki_ca_root_dn }}'
  key_size: '{{ pki_ca_root_key_size }}'

pki_authorities_ca_domain

Configuration of the Domain Certificate Authority.

pki_authorities_ca_domain:
  name: 'domain'
  enabled: '{{ True if pki_ca_domain | d() else False }}'
  subdomain: 'domain-ca'
  subject: '{{ pki_ca_domain_dn }}'
  issuer_name: 'root'
  key_size: '{{ pki_ca_domain_key_size }}'

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: '{{ True if (pki_ca_domain | d() and pki_ca_service_enabled | bool) else False }}'
  key_size: '{{ pki_ca_service_key_size }}'

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_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/{{ inventory_hostname }} - 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 the content 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 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
  # https://security.googleblog.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: []

pki_system_ca_certificates_download_by_host

If True, by hosts CA certificates are downloaded on remote hosts.

pki_system_ca_certificates_download_by_host: '{{ pki_enabled | bool }}'

pki_system_ca_certificates_download_by_group

If True, by group CA certificates are downloaded on remote hosts.

pki_system_ca_certificates_download_by_group: '{{ pki_enabled | bool }}'

pki_system_ca_certificates_download_all_hosts

If True, CA certificates intended for all hosts are downloaded on remote hosts.

pki_system_ca_certificates_download_all_hosts: '{{ pki_enabled | bool }}'

pki_system_ca_certificates_download_all_hosts_force

If True, force the download of CA certificates intended for all hosts. Note that this will overwrite by-host and by-group CA certificates. This option can be used to push new root certificates from a internal CA to hosts.

pki_system_ca_certificates_download_all_hosts_force: False