diff --git a/CHANGES.rst b/CHANGES.rst index e55c4ef..92ddd9c 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,15 @@ Changelog ========= +v0.2.10 +------- + +*Unreleased* + +- Documentation fixes and improvements. Made variables hyperlinks using the + `any` role in Sphinx which also ensures that variables which the + documentation refers to actually exist. [ypid] + v0.2.9 ------ @@ -22,7 +31,7 @@ v0.2.8 - Add support for setting filesystem ACL entries for private directories and files. [drybjed] -- Include realms defined in ``pki_default_realms`` in tasks that copy files +- Include realms defined in :any:`pki_default_realms` in tasks that copy files from Ansible Controller depending on an Ansible inventory group. [drybjed] v0.2.7 @@ -64,7 +73,7 @@ v0.2.5 *Released: 2016-03-02* - Don't run :program:`pki-authority` script on Ansible Controller if list of - ``pki_authorities`` is not defined. [drybjed] + :any:`pki_authorities` is not defined. [drybjed] v0.2.4 ------ @@ -201,6 +210,6 @@ v0.1.0 a separate ``debops.dhparam`` Ansible role. Existing hosts won't be affected. [drybjed] -- Expose ``ansible_fqdn`` variable as ``pki_fqdn`` so that it can be overridden +- Expose ``ansible_fqdn`` variable as :any:`pki_fqdn` so that it can be overridden if necessary. [drybjed] diff --git a/defaults/main.yml b/defaults/main.yml index fb2a6e2..ed9462d 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -143,7 +143,7 @@ pki_acme_tiny_bin: '/usr/local/lib/pki/acme-tiny' # .. envvar:: 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. +# is done in :any:`pki_acme_ca_api_map` dictionary variable. pki_acme_ca: 'le-live' @@ -249,7 +249,7 @@ pki_private_mode: '0640' # 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 -# :ref:`pki_private_groups_present` for more details. +# :ref:`pki__ref_private_groups_present` for more details. pki_private_groups_present: [] @@ -364,6 +364,8 @@ pki_authority_preference: [ 'external', 'acme', 'internal', 'selfsigned' ] # .. envvar:: pki_realms # # List of PKI realms configured on all hosts. +# Refer to the :ref:`documentation of all options ` for +# more details. pki_realms: [] diff --git a/docs/acme-integration.rst b/docs/acme-integration.rst index f2875ee..fd2fe85 100644 --- a/docs/acme-integration.rst +++ b/docs/acme-integration.rst @@ -159,27 +159,27 @@ ACME configuration variables The ``debops.pki`` role has several default variables which can be used to control ACME support. The most important are: -``pki_acme`` +:any:`pki_acme` Boolean. When ``True``, support for ACME Certificate Authority will be configured for all PKI realms unless disabled on the realm level. By default the role checks if a public IP address is available and a default domain is configured, otherwise the support is disabled automatically. -``pki_acme_install`` +:any:`pki_acme_install` Boolean. Enable or disable installation of :program:`acme-tiny` and configuration of ACME support without enabling it for all realms. When this variable is set to - ``True`` and ``pki_acme`` is set to ``False``, ACME support can be enabled + ``True`` and :any:`pki_acme` is set to ``False``, ACME support can be enabled independently in each PKI realm. By default, it is set to the same value as - ``pki_acme``. + :any:`pki_acme`. -``pki_acme_ca`` +:any:`pki_acme_ca` Name of the ACME Certificate Authority API endpoint to use. Dictionary with - endpoints is defined in the ``pki_acme_ca_api_map`` variable. By default, + endpoints is defined in the :any:`pki_acme_ca_api_map` variable. By default, ``le-live`` is used which points to the Let's Encrypt Live CA. For testing you can switch the default CA to ``le-staging`` which points to Let's Encrypt Staging CA. -``pki_acme_default_subdomains`` +:any:`pki_acme_default_subdomains` List of subdomains which will be added to the default ACME domain and all other domains configured for ACME certificate by default, can be overridden by ``item.acme_subdomains`` parameter. By default, the ``www.`` subdomain will be @@ -187,7 +187,7 @@ control ACME support. The most important are: need to be correctly configured in the DNS for the Certificate Authority to sign the request. -Each PKI realm configured in the ``pki_realms`` or ``pki_*_realms`` variables +Each PKI realm configured in the :any:`pki_realms` or ``pki_*_realms`` variables can have several parameters related to the ACME certificates: ``item.name`` @@ -205,7 +205,7 @@ can have several parameters related to the ACME certificates: List of subdomains that should be added to all of the ACME apex/root domains. If you want to create an ACME certificate only with the apex domain, you need to use this parameter with ``[]`` value to override - ``pki_acme_default_subdomains``. + :any:`pki_acme_default_subdomains`. ``item.acme_subdomains`` List of subdomains added to each apex (root) domain configured in the ACME diff --git a/docs/custom-files.rst b/docs/custom-files.rst index 3547d2b..1808431 100644 --- a/docs/custom-files.rst +++ b/docs/custom-files.rst @@ -26,7 +26,7 @@ Each element of the file list is a dict with specific parameters: ``group`` File group, depending on the file type it will be ``root`` (for public files) - or a group specified by the ``pki_private_group`` variable, usually + or a group specified by the :any:`pki_private_group` variable, usually ``ssl-cert`` (for private files). ``mode`` @@ -41,14 +41,14 @@ There are multiple list variables which can be used on multiple inventory levels: - all hosts in the inventory: - - ``pki_private_files`` - - ``pki_public_files`` + - :any:`pki_private_files` + - :any:`pki_public_files` - hosts in specific inventory group: - - ``pki_group_private_files`` - - ``pki_group_public_files`` + - :any:`pki_group_private_files` + - :any:`pki_group_public_files` - specific hosts: - - ``pki_host_private_files`` - - ``pki_host_public_files`` + - :any:`pki_host_private_files` + - :any:`pki_host_public_files` The private files will be copied before PKI realms are created, so that you can provide private keys if you want to. Public files will be copied after PKI diff --git a/docs/defaults-configuration.rst b/docs/defaults-detailed.rst similarity index 89% rename from docs/defaults-configuration.rst rename to docs/defaults-detailed.rst index fedfffe..ae46a40 100644 --- a/docs/defaults-configuration.rst +++ b/docs/defaults-detailed.rst @@ -1,5 +1,5 @@ -Default variables: configuration -================================ +Default variable details +======================== Some of ``debops.pki`` default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them. @@ -8,7 +8,7 @@ simple strings or lists, here you can find documentation and examples for them. :local: :depth: 1 -.. _pki_private_groups_present: +.. _pki__ref_private_groups_present: pki_private_groups_present -------------------------- @@ -49,12 +49,12 @@ Ensure two system groups exist, one with a condition: - name: 'group2' when: '{{ inventory_hostname in specific_inventory_group }}' -.. _pki_realms: +.. _pki__ref_realms: pki_realms ---------- -The set of ``pki_realms`` lists can be used to define the configuration of PKI +The set of :any:`pki_realms` lists can be used to define the configuration of PKI realms located on remote hosts. Each realm keeps a set of private keys and certificates which are signed by the various Certificate Authorities. @@ -88,14 +88,14 @@ List of parameters related to the entire PKI realm: ``authority`` Specify name of the internal Certificate Authority to send the internal certificate requests to instead of the default one configured in - ``pki_default_authority`` variable. This should be the "normal" name of the + :any:`pki_default_authority` variable. This should be the "normal" name of the authority, not it's subdomain name. ``acme`` Optional, boolean. Enable or disable support for ACME Certificate Authority. - Can be used to invert the global ``pki_acme`` setting per PKI realm if + Can be used to invert the global :any:`pki_acme` setting per PKI realm if needed, but support for ACME needs to be present on the remote host for it to - work (see ``pki_acme_install`` variable). + work (see :any:`pki_acme_install` variable). ``internal`` Optional, boolean. Enable or disable support for internal CA certificates in @@ -106,7 +106,7 @@ List of parameters related to the entire PKI realm: Optional. List of directory names (``external``, ``acme``, ``internal``, ``selfsigned``) which determines the order in which the PKI realm looks for valid certificates. The first found valid certificate is enabled. If not - specified, the order configured in ``pki_authority_preference`` will be used. + specified, the order configured in :any:`pki_authority_preference` will be used. ``library`` Optional. Specify name of the crypto library used to generate private key and @@ -121,24 +121,24 @@ List of parameters related to the entire PKI realm: ``private_dir_group`` Optional. System group which will be set as the group of the :file:`private/` directory of a given PKI realm. By default, ``ssl-cert``. It needs to exist, - and can be created using ``pki_private_groups_resent`` list. + and can be created using :any:`pki_private_groups_present` list. ``private_file_group`` Optional. System group which will be set as the group of the private keys inside of the :file:`private/` directory. It needs to exist, and can be created - using ``pki_private_groups_present`` list. + using :any:`pki_private_groups_present` list. ``private_dir_acl_groups`` Optional. List of groups which should be allowed execute (``X``) permission to the ``private/`` realm directory. The access will be granted using filesystem ACL table. If not specified, the list defined in - ``pki_private_dir_acl_groups`` will be applied. + :any:`pki_private_dir_acl_groups` will be applied. ``private_file_acl_groups`` Optional. List of groups which should be allowed read (``r``) permission to the files in the ``private/`` realm directory. The access will be granted using filesystem ACL table. If not specified, the list defined in - ``pki_private_file_acl_groups`` will be applied. + :any:`pki_private_file_acl_groups` will be applied. ``dhparam`` Optional, boolean. Enable or disable support for adding the Diffie-Hellman @@ -161,7 +161,7 @@ respectively: ``default_domain`` Optional. Change the default domain used by a given PKI realm. If not specified, default domain is based on the ``name`` parameter if it has at - least 1 dot, or it will be taken from ``pki_default_domain`` variable which + least 1 dot, or it will be taken from :any:`pki_default_domain` variable which is populated by the ``ansible_domain`` variable. ``default_subdomains``, ``acme_default_subdomains`` @@ -169,8 +169,8 @@ respectively: realm. A special value ``_wildcard_`` can be used to indicate that a wildcard domain should be present in the certificate. - If not specified, ``pki_default_subdomains`` (for internal CA) and - ``pki_acme_default_subdomains`` (for ACME CA) will be used. The PKI + If not specified, :any:`pki_default_subdomains` (for internal CA) and + :any:`pki_acme_default_subdomains` (for ACME CA) will be used. The PKI parameters can be set to empty to override the default variables. ``subject``, ``acme_subject`` diff --git a/docs/external-certificates.rst b/docs/external-certificates.rst index dda701c..7189385 100644 --- a/docs/external-certificates.rst +++ b/docs/external-certificates.rst @@ -105,7 +105,7 @@ Because files copied from :file:`by-group/all/` and :file:`by-group/inventory_gr directories are not overwritten automatically, you will need to remove the corresponding files on remote hosts yourself if you want to update them. -The ``pki_inventory_groups`` default variable is a list of Ansible inventory +The :any:`pki_inventory_groups` default variable is a list of Ansible inventory groups that will have their corresponding directories. You need to specify your custom inventory groups in order to have them "active". diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 5e424d1..01a29d2 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -47,7 +47,7 @@ remote hosts. Most of these variables are related to Certificate Authority operation, the ones you will likely want to change are: -``pki_ca_domain`` +:any:`pki_ca_domain` This is the DNS domain used as a base for the internal Certificate Authority Distinguished Names. If you use more than one domain in your environment, you should set this variable to your preferred domain on all hosts, through @@ -57,11 +57,11 @@ ones you will likely want to change are: configured with no default domain, or the provider domain might be set up by default. Make sure that you check what domain is used by your remote hosts. -``pki_ca_organization`` +:any:`pki_ca_organization` This is the organizations name used as a base for the internal Certificate Authority Distinguished Names. -``pki_ca_root_dn``, ``pki_ca_domain_dn``, ``pki_ca_service_dn`` +:any:`pki_ca_root_dn`, :any:`pki_ca_domain_dn`, :any:`pki_ca_service_dn` These variables define the Distinguished Name or Subject of the Root Certificate Authority and Domain Certificate Authority. The value is a list of DN entries which define the subject. diff --git a/docs/index.rst b/docs/index.rst index 853e519..7b2e60a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ Ansible role: debops.pki acme-integration external-certificates defaults - defaults-configuration + defaults-detailed system-ca-certificates custom-files custom-hooks diff --git a/docs/system-ca-certificates.rst b/docs/system-ca-certificates.rst index 42585d7..83d888e 100644 --- a/docs/system-ca-certificates.rst +++ b/docs/system-ca-certificates.rst @@ -25,12 +25,12 @@ from the system CA store. By default, Debian hosts automatically trust new Root Certificate Authorities added in the ``ca-certificates`` package. To control this, you can use -``pki_system_ca_certificates_trust_new`` boolean variable. Setting this +:any:`pki_system_ca_certificates_trust_new` boolean variable. Setting this variable to ``True`` will ensure that new Root CA certificates are trusted. Setting it to ``False`` will not enable new CA certificates automatically. -You can use ``pki_system_ca_certificates_blacklist`` and -``pki_system_ca_certificates_whitelist`` list variables to define which +You can use :any:`pki_system_ca_certificates_blacklist` and +:any:`pki_system_ca_certificates_whitelist` list variables to define which certificates will be excluded/included in the CA store. Each list element is a regexp of the certificate file name. If a given file is found in both lists, it will be excluded from the certificate store.