debops.pki default variables¶
Sections
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:
1 | 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_' ]
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'
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'
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 }}'
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 }}'
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 }}'
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 }}'
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