Note
This plugin is part of the community.crypto collection (version 1.9.6).
You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
To use it in a playbook, specify: community.crypto.ecs_domain.
New in version 1.0.0: of community.crypto
domain_status=EXPIRED, in which case a re-validation will be performed.verification_method=dns, details about the required DNS entry will be specified in the return parameters dns_contents, dns_location, and dns_resource_type.verification_method=web_server, details about the required file details will be specified in the return parameters file_contents and file_location.verification_method=email, the email address(es) that the validation email(s) were sent to will be in the return parameter emails. This is purely informational. For domains requested using this module, this will always be a list of size 1.The below requirements are needed on the host that executes this module.
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| client_id integer | Default: 1 | The client ID to request the domain be associated with. If no client ID is specified, the domain will be added under the primary client with ID of 1. |
| domain_name string / required | The domain name to be verified or reverified. | |
| entrust_api_client_cert_key_path path / required | The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. | |
| entrust_api_client_cert_path path / required | The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. | |
| entrust_api_key string / required | The key (password) for authentication to the Entrust Certificate Services (ECS) API. | |
| entrust_api_specification_path path | Default: "https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml" | The path to the specification file defining the Entrust Certificate Services (ECS) API configuration. You can use this to keep a local copy of the specification to avoid downloading it every time the module is used. |
| entrust_api_user string / required | The username for authentication to the Entrust Certificate Services (ECS) API. | |
| verification_email string | Email address to be used to verify domain ownership. Email address must be either an email address present in the WHOIS data for domain_name, or one of the following constructed emails: admin@domain_name, administrator@domain_name, webmaster@domain_name, hostmaster@domain_name, postmaster@domain_name
Note that if domain_name includes subdomains, the top level domain should be used. For example, if requesting validation of example1.ansible.com, or test.example2.ansible.com, and you want to use the "admin" preconstructed name, the email address should be [email protected]. If using the email values from the WHOIS data for the domain or it's top level namespace, they must be exact matches. If verification_method=email but verification_email is not provided, the first email address found in WHOIS data for the domain will be used.To verify domain ownership, domain owner must follow the instructions in the email they receive. Only allowed if verification_method=email
| |
| verification_method string / required |
| The verification method to be used to prove control of the domain. If verification_method=email and the value verification_email is specified, that value is used for the email validation. If verification_email is not provided, the first value present in WHOIS data will be used. An email will be sent to the address in verification_email with instructions on how to verify control of the domain.If verification_method=dns, the value dns_contents must be stored in location dns_location, with a DNS record type of verification_dns_record_type. To prove domain ownership, update your DNS records so the text string returned by dns_contents is available at dns_location.If verification_method=web_server, the contents of return value file_contents must be made available on a web server accessible at location file_location.If verification_method=manual, the domain will be validated with a manual process. This is not recommended. |
Note
verification_method=dns or verification_method=web_server. Be aware of that if doing many domain validation requests.See also
Can be used to request certificates from ECS, with provider=entrust.
Can be used to request a Certificate from ECS using a verified domain.
- name: Request domain validation using email validation for client ID of 2.
community.crypto.ecs_domain:
domain_name: ansible.com
client_id: 2
verification_method: email
verification_email: [email protected]
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request domain validation using DNS. If domain is already valid,
request revalidation if expires within 90 days
community.crypto.ecs_domain:
domain_name: ansible.com
verification_method: dns
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request domain validation using web server validation, and revalidate
if fewer than 60 days remaining of EV eligibility.
community.crypto.ecs_domain:
domain_name: ansible.com
verification_method: web_server
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request domain validation using manual validation.
community.crypto.ecs_domain:
domain_name: ansible.com
verification_method: manual
entrust_api_user: apiusername
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description |
|---|---|---|
| client_id integer | changed or success | Client ID that the domain belongs to. If the input value client_id is specified, this will always be the same as client_id
Sample: 1 |
| dns_contents string | changed and if verification_method is dns
| The value that ECS will be expecting to find in the DNS record located at dns_location. Sample: AB23CD41432522FF2526920393982FAB |
| dns_location string | changed and if verification_method is dns
| The location that ECS will be expecting to be able to find the DNS entry for domain verification, containing the contents of dns_contents. Sample: _pki-validation.ansible.com |
| dns_resource_type string | changed and if verification_method is dns
| The type of resource record that ECS will be expecting for the DNS record located at dns_location. Sample: TXT |
| domain_status string | changed or success | Status of the current domain. Will be one of APPROVED, DECLINED, CANCELLED, INITIAL_VERIFICATION, DECLINED, CANCELLED, RE_VERIFICATION, EXPIRED, EXPIRING
Sample: APPROVED |
| emails list / elements=string |
verification_method is email
| The list of emails used to request validation of this domain. Domains requested using this module will only have a list of size 1. Sample: |
| ev_days_remaining integer | success and ev_eligible is true and domain_status is APPROVED, RE_VERIFICATION or EXPIRING. | The number of days the domain remains eligible for submission of "EV" certificates. Will never be greater than the value of ov_days_remaining
Sample: 94 |
| ev_eligible boolean | success and domain_status is APPROVED, RE_VERIFICATION or EXPIRING, or EXPIRED. | Whether the domain is eligible for submission of "EV" certificates. Will never be true if ov_eligible is false
Sample: True |
| file_contents string |
verification_method is web_server
| The contents of the file that ECS will be expecting to find at file_location.Sample: AB23CD41432522FF2526920393982FAB |
| file_location string |
verification_method is web_server
| The location that ECS will be expecting to be able to find the file for domain verification, containing the contents of file_contents. Sample: http://ansible.com/.well-known/pki-validation/abcd.txt |
| ov_days_remaining integer | success and ov_eligible is true and domain_status is APPROVED, RE_VERIFICATION or EXPIRING. | The number of days the domain remains eligible for submission of "OV" certificates. Will never be less than the value of ev_days_remaining
Sample: 129 |
| ov_eligible boolean | success and domain_status is APPROVED, RE_VERIFICATION, EXPIRING, or EXPIRED. | Whether the domain is eligible for submission of "OV" certificates. Will never be false if ov_eligible is true
Sample: True |
| verification_method string | changed or success | Verification method used to request the domain validation. If changed will be the same as verification_method input parameter.Sample: dns |
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/crypto/ecs_domain_module.html