Class: Ansible::Ruby::Modules::Acme_certificate

Inherits:
Base show all
Defined in:
lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb,
lib/ansible/ruby/modules/generated/crypto/acme/acme_certificate.rb

Overview

Create and renew SSL/TLS certificates with a CA supporting the L(ACME protocol,tools.ietf.org/html/draft-ietf-acme-acme-14), such as L(Let’s Encrypt,letsencrypt.org/). The current implementation supports the C(http-01), C(dns-01) and C(tls-alpn-01) challenges. To use this module, it has to be executed twice. Either as two different tasks in the same run or during two runs. Note that the output of the first run needs to be recorded and passed to the second run as the module argument C(data). Between these two tasks you have to fulfill the required steps for the chosen challenge by whatever means necessary. For C(http-01) that means creating the necessary challenge file on the destination webserver. For C(dns-01) the necessary dns record has to be created. For C(tls-alpn-01) the necessary certificate has to be created and served. It is I(not) the responsibility of this module to perform these steps. For details on how to fulfill these challenges, you might have to read through L(the main ACME specification,tools.ietf.org/html/draft-ietf-acme-acme-14#section-8) and the L(TLS-ALPN-01 specification,tools.ietf.org/html/draft-ietf-acme-tls-alpn-05#section-3). Also, consider the examples provided for this module.

Instance Method Summary collapse

Methods inherited from Base

#ansible_name, #to_h

Methods inherited from Ansible::Ruby::Models::Base

attr_option, attr_options, attribute, fix_inclusion, #initialize, remove_existing_validations, #to_h, validates

Constructor Details

This class inherits a constructor from Ansible::Ruby::Models::Base

Instance Method Details

#account_email ⇒ String?

Returns The email address associated with this account.,It will be used for certificate expiration warnings.,Note that when C(modify_account) is not set to C(no) and you also used the M(acme_account) module to specify more than one contact for your account, this module will update your account and restrict it to the (at most one) contact email address specified here.

Returns:

  • (String, nil) —

    The email address associated with this account.,It will be used for certificate expiration warnings.,Note that when C(modify_account) is not set to C(no) and you also used the M(acme_account) module to specify more than one contact for your account, this module will update your account and restrict it to the (at most one) contact email address specified here.



15
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 15

attribute :account_email

#agreement ⇒ Object?

Returns URI to a terms of service document you agree to when using the ACME v1 service at C(acme_directory).,Default is latest gathered from C(acme_directory) URL.,This option will only be used when C(acme_version) is 1.

Returns:

  • (Object, nil) —

    URI to a terms of service document you agree to when using the ACME v1 service at C(acme_directory).,Default is latest gathered from C(acme_directory) URL.,This option will only be used when C(acme_version) is 1.



19
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 19

attribute :agreement

#chain_dest ⇒ String?

Returns If specified, the intermediate certificate will be written to this file.

Returns:

  • (String, nil) —

    If specified, the intermediate certificate will be written to this file.



50
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 50

attribute :chain_dest

#challenge ⇒ :"http-01", ...

Returns The challenge to be performed.

Returns:

  • (:"http-01", :"dns-01", :"tls-alpn-01", nil) —

    The challenge to be performed.



30
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 30

attribute :challenge

#csr ⇒ String

Returns File containing the CSR for the new certificate.,Can be created with C(openssl req …).,The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must be fulfilled for the CSR to be signed.,I(Note): the private key used to create the CSR I(must not) be the account key. This is a bad idea from a security point of view, and the CA should not accept the CSR. The ACME server should return an error in this case.

Returns:

  • (String) —

    File containing the CSR for the new certificate.,Can be created with C(openssl req …).,The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must be fulfilled for the CSR to be signed.,I(Note): the private key used to create the CSR I(must not) be the account key. This is a bad idea from a security point of view, and the CA should not accept the CSR. The ACME server should return an error in this case.



34
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 34

attribute :csr

#data ⇒ String?

Returns The data to validate ongoing challenges. This must be specified for the second run of the module only.,The value that must be used here will be provided by a previous use of this module. See the examples for more details.,Note that for ACME v2, only the C(order_uri) entry of C(data) will be used. For ACME v1, C(data) must be non-empty to indicate the second stage is active; all needed data will be taken from the CSR.,I(Note): the C(data) option was marked as C(no_log) up to Ansible 2.5. From Ansible 2.6 on, it is no longer marked this way as it causes error messages to be come unusable, and C(data) does not contain any information which can be used without having access to the account key or which are not public anyway.

Returns:

  • (String, nil) —

    The data to validate ongoing challenges. This must be specified for the second run of the module only.,The value that must be used here will be provided by a previous use of this module. See the examples for more details.,Note that for ACME v2, only the C(order_uri) entry of C(data) will be used. For ACME v1, C(data) must be non-empty to indicate the second stage is active; all needed data will be taken from the CSR.,I(Note): the C(data) option was marked as C(no_log) up to Ansible 2.5. From Ansible 2.6 on, it is no longer marked this way as it causes error messages to be come unusable, and C(data) does not contain any information which can be used without having access to the account key or which are not public anyway.



38
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 38

attribute :data

#deactivate_authzs ⇒ :yes, ...

Returns Deactivate authentication objects (authz) after issuing a certificate, or when issuing the certificate failed.,Authentication objects are bound to an account key and remain valid for a certain amount of time, and can be used to issue certificates without having to re-authenticate the domain. This can be a security concern.

Returns:

  • (:yes, :no, nil) —

    Deactivate authentication objects (authz) after issuing a certificate, or when issuing the certificate failed.,Authentication objects are bound to an account key and remain valid for a certain amount of time, and can be used to issue certificates without having to re-authenticate the domain. This can be a security concern.



58
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 58

attribute :deactivate_authzs

#dest ⇒ String?

Returns The destination file for the certificate.,Required if C(fullchain_dest) is not specified.

Returns:

  • (String, nil) —

    The destination file for the certificate.,Required if C(fullchain_dest) is not specified.



42
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 42

attribute :dest

#force ⇒ :yes, ...

Returns Enforces the execution of the challenge and validation, even if an existing certificate is still valid for more than C(remaining_days).,This is especially helpful when having an updated CSR e.g. with additional domains for which a new certificate is desired.

Returns:

  • (:yes, :no, nil) —

    Enforces the execution of the challenge and validation, even if an existing certificate is still valid for more than C(remaining_days).,This is especially helpful when having an updated CSR e.g. with additional domains for which a new certificate is desired.



62
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 62

attribute :force

#fullchain_dest ⇒ String?

Returns The destination file for the full chain (i.e. certificate followed by chain of intermediate certificates).,Required if C(dest) is not specified.

Returns:

  • (String, nil) —

    The destination file for the full chain (i.e. certificate followed by chain of intermediate certificates).,Required if C(dest) is not specified.



46
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 46

attribute :fullchain_dest

#modify_account ⇒ :yes, ...

Returns Boolean indicating whether the module should create the account if necessary, and update its contact data.,Set to C(no) if you want to use the M(acme_account) module to manage your account instead, and to avoid accidental creation of a new account using an old key if you changed the account key with M(acme_account).,If set to C(no), C(terms_agreed) and C(account_email) are ignored.

Returns:

  • (:yes, :no, nil) —

    Boolean indicating whether the module should create the account if necessary, and update its contact data.,Set to C(no) if you want to use the M(acme_account) module to manage your account instead, and to avoid accidental creation of a new account using an old key if you changed the account key with M(acme_account).,If set to C(no), C(terms_agreed) and C(account_email) are ignored.



26
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 26

attribute :modify_account

#remaining_days ⇒ Integer?

Returns The number of days the certificate must have left being valid. If C(cert_days < remaining_days), then it will be renewed. If the certificate is not renewed, module return values will not include C(challenge_data).,To make sure that the certificate is renewed in any case, you can use the C(force) option.

Returns:

  • (Integer, nil) —

    The number of days the certificate must have left being valid. If C(cert_days < remaining_days), then it will be renewed. If the certificate is not renewed, module return values will not include C(challenge_data).,To make sure that the certificate is renewed in any case, you can use the C(force) option.



54
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 54

attribute :remaining_days

#terms_agreed ⇒ :yes, ...

Returns Boolean indicating whether you agree to the terms of service document.,ACME servers can require this to be true.,This option will only be used when C(acme_version) is not 1.

Returns:

  • (:yes, :no, nil) —

    Boolean indicating whether you agree to the terms of service document.,ACME servers can require this to be true.,This option will only be used when C(acme_version) is not 1.



22
 
# File 'lib/ansible/ruby/modules/generated/crypto/acme/letsencrypt.rb', line 22

attribute :terms_agreed