From 0ca9624802f290834e0aef10eeff99c0c586e5db Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Tue, 8 Oct 2019 19:45:25 -0500 Subject: [PATCH] Backport/2.9/docs2 (#63250) * Concise file module example description (#62932) A file won't be created by the example, the execution would fail unless the file already exists as specified by the module options (cherry picked from commit 87a6f8397ec367be74c815aa8162dd6d31b9d78d) * Added suffix note to process_name_exact parameter (#62849) (cherry picked from commit 992b81e8fc9b7810088a7a9fde636f814f38471a) * Fix broken link to powershell resources (#62845) The previous link (https://docs.microsoft.com/en-us/powershell/dsc/builtinresource ) is a 404 . MS has a new link https://docs.microsoft.com/en-us/powershell/dsc/resources/resources with the same content (cherry picked from commit cae4255a16835d13411bdcd5d6b582a4295b3bff) * Update playbooks_environment.rst (#62800) (cherry picked from commit cea8a222a3bfdf1e580721866c77abdc95280a2a) * Update win_dsc.py (#62863) (cherry picked from commit 798c5a55fa7ea0196b0db307bcd86c1b3dfe6cb1) * Adjust documentation for yum clean to use best practices (#62898) The yum module docs suggested using `shell: yum clean all`, which gives an `ansible-lint` error. Plus, you should use the `command` module unless you need more advanced features than just passing in an arbitrary command. Fixes that problem by using the `command` module in the example instead. (cherry picked from commit 1e6fd6f54de4c1c487961b77603fc76cad9d2efd) * This should never have been "support:network" (#63068) (cherry picked from commit 7ae46329f2aa9122b8b1c6eb3588f5d5828041c3) * Add docs on hiding sensitive data in loops (#63096) (cherry picked from commit 03118977221ad9cb19789bf01f121574ee284745) * Doc updates to openssl_certificate and ecs_certificate (#63006) * Update lib/ansible/modules/crypto/entrust/ecs_certificate.py Co-Authored-By: Felix Fontein (cherry picked from commit e55f46f3026f4bc17f5c51341bb568b0886e4dfe) * Update intro_installation.rst (#62994) (cherry picked from commit f2214951c58eb7447004a3c0f3932412d17e71d4) * Update xml.py (#63128) Update example to remove escape characters in front of special characters as it is not needed to add explicitly anymore with latest ansible version (cherry picked from commit 82a6f9d198bd428fc3ebb14baa19b503fc827fbc) --- .../installation_guide/intro_installation.rst | 4 +- .../rst/user_guide/playbooks_environment.rst | 2 +- .../rst/user_guide/playbooks_loops.rst | 2 + .../modules/crypto/entrust/ecs_certificate.py | 78 ++++++++++--------- .../modules/crypto/openssl_certificate.py | 20 ++--- lib/ansible/modules/files/file.py | 2 +- lib/ansible/modules/files/xml.py | 2 +- lib/ansible/modules/network/nxos/nxos_ping.py | 2 +- lib/ansible/modules/packaging/os/yum.py | 4 +- lib/ansible/modules/windows/win_dsc.py | 4 +- .../modules/windows/win_wait_for_process.py | 2 +- .../plugins/doc_fragments/ecs_credential.py | 8 +- 12 files changed, 67 insertions(+), 63 deletions(-) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 964b9ac8438..c61bb33a4b1 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -82,8 +82,8 @@ later). modules to use. You will still need to set :ref:`ansible_python_interpreter` if the Python 2 interpreter is not installed to :command:`/usr/bin/python`. - * Ansible's "raw" module (for executing commands in a quick and dirty way) and the script module - don't even need Python installed. So technically, you can use Ansible to install a compatible + * Ansible's :ref:`raw module`, and the :ref:`script module`, do not depend + on a client side install of Python to run. Technically, you can use Ansible to install a compatible version of Python using the :ref:`raw module`, which then allows you to use everything else. For example, if you need to bootstrap Python 2 onto a RHEL-based system, you can install it via diff --git a/docs/docsite/rst/user_guide/playbooks_environment.rst b/docs/docsite/rst/user_guide/playbooks_environment.rst index e617708a2d3..a89ade3f8fd 100644 --- a/docs/docsite/rst/user_guide/playbooks_environment.rst +++ b/docs/docsite/rst/user_guide/playbooks_environment.rst @@ -39,7 +39,7 @@ The environment can also be stored in a variable, and accessed like so:: package: name: cobbler state: present - environment: "{{proxy_env}}" + environment: "{{ proxy_env }}" You can also use it at a play level:: diff --git a/docs/docsite/rst/user_guide/playbooks_loops.rst b/docs/docsite/rst/user_guide/playbooks_loops.rst index 4dbfaa66aee..9e6fd59d9f8 100644 --- a/docs/docsite/rst/user_guide/playbooks_loops.rst +++ b/docs/docsite/rst/user_guide/playbooks_loops.rst @@ -317,6 +317,8 @@ When looping over complex data structures, the console output of your task can b The output of this task will display just the ``name`` field for each ``item`` instead of the entire contents of the multi-line ``{{ item }}`` variable. +.. note:: This is for making console output more readable, not protecting sensitive data. If there is sensitive data in ``loop``, set ``no_log: yes`` on the task to prevent disclosure. + Pausing within a loop --------------------- .. versionadded:: 2.2 diff --git a/lib/ansible/modules/crypto/entrust/ecs_certificate.py b/lib/ansible/modules/crypto/entrust/ecs_certificate.py index f6f1ee98666..dd1330653e0 100644 --- a/lib/ansible/modules/crypto/entrust/ecs_certificate.py +++ b/lib/ansible/modules/crypto/entrust/ecs_certificate.py @@ -31,7 +31,7 @@ requirements: options: backup: description: - - Path to store a backup of the initial certificate, if I(path) pointed to an existing file certificate. + - Whether a backup should be made for the certificate in I(path). type: bool default: false force: @@ -44,16 +44,17 @@ options: default: false path: description: - - Path to put the certificate file as a PEM encoded cert. - - If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested regardless of validity. - - If there is already an Entrust certificate at this location, whether it is replaced is dependent upon the I(remaining_days) calculation. - - If an existing certificate is being replaced (see I(remaining_days), I(force), I(tracking_id)), the operation taken to replace it is dependent - on I(request_type) + - The destination path for the generated certificate as a PEM encoded cert. + - If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested even if the current + certificate is technically valid. + - If there is already an Entrust certificate at this location, whether it is replaced is depends on the I(remaining_days) calculation. + - If an existing certificate is being replaced (see I(remaining_days), I(force), and I(tracking_id)), whether a new certificate is requested + or the existing certificate is renewed or reissued is based on I(request_type). type: path required: true full_chain_path: description: - - Path to put the full certificate chain of the certificate, intermediates, and roots. + - The destination path for the full certificate chain of the certificate, intermediates, and roots. type: path csr: description: @@ -68,23 +69,23 @@ options: type: str tracking_id: description: - - Tracking ID of certificate to reissue or renew. + - The tracking ID of the certificate to reissue or renew. - I(tracking_id) is invalid if C(request_type=new) or C(request_type=validate_only). - If there is a certificate present in I(path) and it is an ECS certificate, I(tracking_id) will be ignored. - - If there is not a certificate present in I(path) or there is but it is from another provider, the certificate represented by I(tracking_id) will + - If there is no certificate present in I(path) or there is but it is from another provider, the certificate represented by I(tracking_id) will be renewed or reissued and saved to I(path). - - If there is not a certificate present in I(path) and the I(force) and I(remaining_days) parameters do not indicate a new certificate is needed, + - If there is no certificate present in I(path) and the I(force) and I(remaining_days) parameters do not indicate a new certificate is needed, the certificate referenced by I(tracking_id) certificate will be saved to I(path). - This can be used when a known certificate is not currently present on a server, but you want to renew or reissue it to be managed by an ansible playbook. For example, if you specify C(request_type=renew), I(tracking_id) of an issued certificate, and I(path) to a file that does not exist, - the first run of a task will download the certificate specified by I(tracking_id) (assuming it is still valid), and future runs of the task will + the first run of a task will download the certificate specified by I(tracking_id) (assuming it is still valid). Future runs of the task will (if applicable - see I(force) and I(remaining_days)) renew the certificate now present in I(path). type: int remaining_days: description: - The number of days the certificate must have left being valid. If C(cert_days < remaining_days) then a new certificate will be obtained using I(request_type). - - If C(request_type=renew), a renew will fail if the certificate being renewed has been issued within the past 30 days, so do not set a + - If C(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30 days, so do not set a I(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon. (e.g. if you are requesting Certificates with a 90 day lifetime, do not set remaining_days to a value C(60) or higher). - The I(force) option may be used to ensure that a new certificate is always obtained. @@ -92,8 +93,8 @@ options: default: 30 request_type: description: - - Operation performed if I(tracking_id) references a valid certificate to reissue, or there is already a certificate present in I(path) but either - I(force) is specified or C(cert_days < remaining_days). + - The operation performed if I(tracking_id) references a valid certificate to reissue, or there is already a certificate present in I(path) but + either I(force) is specified or C(cert_days < remaining_days). - Specifying C(request_type=validate_only) means the request will be validated against the ECS API, but no certificate will be issued. - Specifying C(request_type=new) means a certificate request will always be submitted and a new certificate issued. - Specifying C(request_type=renew) means that an existing certificate (specified by I(tracking_id) if present, otherwise I(path)) will be renewed. @@ -112,7 +113,7 @@ options: default: new cert_type: description: - - The type of certificate product to request. + - Specify the type of certificate requested. - If a certificate is being reissued or renewed, this parameter is ignored, and the C(cert_type) of the initial certificate is used. type: str choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CODE_SIGNING', 'EV_CODE_SIGNING', @@ -153,7 +154,7 @@ options: description: - Organization "O=" to include in the certificate. - If I(org) is not specified, the organization from the client represented by I(client_id) is used. - - Unless the I(cert_type) is C(PD_SSL), this field may not be specified if the value of I(client_id) is not the primary client of "1". For all + - Unless the I(cert_type) is C(PD_SSL), this field may not be specified if the value of I(client_id) is not "1" (the primary client). non-primary clients, certificates may only be issued with the organization of that client. type: str ou: @@ -180,15 +181,15 @@ options: description: Free form tracking information to attach to the record for the certificate. type: str requester_name: - description: Requester name to associate with certificate tracking information. + description: The requester name to associate with certificate tracking information. type: str required: true requester_email: - description: Requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate. + description: The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate. type: str required: true requester_phone: - description: Requester phone number to associate with certificate tracking information. + description: The requester phone number to associate with certificate tracking information. type: str required: true additional_emails: @@ -203,49 +204,49 @@ options: type: dict suboptions: text1: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text2: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text3: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text4: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text5: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text6: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text7: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text8: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text9: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text10: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text11: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text12: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text13: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text14: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str text15: - description: Custom text field of maximum size 500. + description: Custom text field (maximum 500 characters) type: str number1: description: Custom number field. @@ -309,14 +310,15 @@ options: type: str cert_expiry: description: - - The date the certificate should be set to expire, as an RFC3339 compliant date or date-time. For example, + - The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example, C(2020-02-23), C(2020-02-23T15:00:00.05Z). - I(cert_expiry) is only supported for requests of C(request_type=new) or C(request_type=renew). If C(request_type=reissue), I(cert_expiry) will be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial certificate. - A reissued certificate will always have the same expiry as the original certificate. - - Note that only the date (day, month, year) is supported for specifying expiry date. If you choose to specify an expiry time with the expiry date, - the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous day. + - Note that only the date (day, month, year) is supported for specifying the expiry date. If you choose to specify an expiry time with the expiry + date, the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous + day. - Applies only to accounts with a pooling inventory model. - Only one of I(cert_expiry) or I(cert_lifetime) may be specified. type: str @@ -461,7 +463,7 @@ EXAMPLES = r''' RETURN = ''' filename: - description: Path to the generated Certificate. + description: The destination path for the generated certificate. returned: changed or success type: str sample: /etc/ssl/crt/www.ansible.com.crt diff --git a/lib/ansible/modules/crypto/openssl_certificate.py b/lib/ansible/modules/crypto/openssl_certificate.py index ad836512ddc..e06946a862a 100644 --- a/lib/ansible/modules/crypto/openssl_certificate.py +++ b/lib/ansible/modules/crypto/openssl_certificate.py @@ -470,7 +470,7 @@ options: entrust_cert_type: description: - - The type of certificate product to request. + - Specify the type of certificate requested. - This is only used by the C(entrust) provider. type: str default: STANDARD_SSL @@ -519,7 +519,7 @@ options: entrust_api_client_cert_path: description: - - The path of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. + - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. - This is only used by the C(entrust) provider. - This is required if the provider is C(entrust). type: path @@ -527,7 +527,7 @@ options: entrust_api_client_cert_key_path: description: - - The path of the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. + - The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. - This is only used by the C(entrust) provider. - This is required if the provider is C(entrust). type: path @@ -536,15 +536,15 @@ options: entrust_not_after: description: - The point in time at which the certificate stops being valid. - - Time can be specified either as relative time or as absolute timestamp. + - Time can be specified either as relative time or as an absolute timestamp. + - A valid absolute time format is C(ASN.1 TIME) such as C(2019-06-18). + - A valid relative time format is C([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as C(+365d) or C(+32w1d2h)). - Time will always be interpreted as UTC. - - Note that only the date (day, month, year) is supported for specifying expiry date of the issued certificate. + - Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate. - The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day earlier than expected if a relative time is used. - The minimum certificate lifetime is 90 days, and maximum is three years. - - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer - + C([w | d | h | m | s]) (e.g. C(+32w1d2h). - - If this value is not specified, the certificate will stop being valid 365 days from now. + - If this value is not specified, the certificate will stop being valid 365 days the date of issue. - This is only used by the C(entrust) provider. type: str default: +365d @@ -552,8 +552,8 @@ options: entrust_api_specification_path: description: - - Path to the specification file defining the Entrust Certificate Services (ECS) API. - - Can be used to keep a local copy of the specification to avoid downloading it every time the module is used. + - 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. - This is only used by the C(entrust) provider. type: path default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml diff --git a/lib/ansible/modules/files/file.py b/lib/ansible/modules/files/file.py index daa5a490fe6..575f3c7d275 100644 --- a/lib/ansible/modules/files/file.py +++ b/lib/ansible/modules/files/file.py @@ -126,7 +126,7 @@ EXAMPLES = r''' group: foo mode: '0644' -- name: Create an insecure file +- name: Give insecure permissions to an existing file file: path: /work owner: root diff --git a/lib/ansible/modules/files/xml.py b/lib/ansible/modules/files/xml.py index 5e707c65256..ab69d8ef57d 100644 --- a/lib/ansible/modules/files/xml.py +++ b/lib/ansible/modules/files/xml.py @@ -225,7 +225,7 @@ EXAMPLES = r''' - name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element xml: path: /foo/bar.xml - xpath: '/business/beers/beer[text()=\"Rochefort 10\"]' + xpath: '/business/beers/beer[text()="Rochefort 10"]' insertbefore: yes add_children: - beer: Old Rasputin diff --git a/lib/ansible/modules/network/nxos/nxos_ping.py b/lib/ansible/modules/network/nxos/nxos_ping.py index d2340e6a5f6..3c64f4b6af6 100644 --- a/lib/ansible/modules/network/nxos/nxos_ping.py +++ b/lib/ansible/modules/network/nxos/nxos_ping.py @@ -18,7 +18,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], - 'supported_by': 'network'} + 'supported_by': 'community'} DOCUMENTATION = ''' diff --git a/lib/ansible/modules/packaging/os/yum.py b/lib/ansible/modules/packaging/os/yum.py index ef188ed2803..6235893e0bf 100644 --- a/lib/ansible/modules/packaging/os/yum.py +++ b/lib/ansible/modules/packaging/os/yum.py @@ -225,8 +225,8 @@ notes: Use the "yum group list hidden ids" command to see which category of group the group you want to install falls into.' - 'The yum module does not support clearing yum cache in an idempotent way, so it - was decided not to implement it, the only method is to use shell and call the yum - command directly, namely "shell: yum clean all" + was decided not to implement it, the only method is to use command and call the yum + command directly, namely "command: yum clean all" https://github.com/ansible/ansible/pull/31450#issuecomment-352889579' # informational: requirements for nodes requirements: diff --git a/lib/ansible/modules/windows/win_dsc.py b/lib/ansible/modules/windows/win_dsc.py index 86df7d5082c..27412e140bc 100644 --- a/lib/ansible/modules/windows/win_dsc.py +++ b/lib/ansible/modules/windows/win_dsc.py @@ -64,7 +64,7 @@ options: required: true notes: - By default there are a few builtin resources that come with PowerShell 5.0, - see U(https://docs.microsoft.com/en-us/powershell/dsc/builtinresource) for + see U(https://docs.microsoft.com/en-us/powershell/dsc/resources/resources) for more information on these resources. - Custom DSC resources can be installed with M(win_psmodule) using the I(name) option. @@ -92,7 +92,7 @@ EXAMPLES = r''' Name: telnet-client - name: Edit HKCU reg key under specific user - win_regedit: + win_dsc: resource_name: Registry Ensure: Present Key: HKEY_CURRENT_USER\ExampleKey diff --git a/lib/ansible/modules/windows/win_wait_for_process.py b/lib/ansible/modules/windows/win_wait_for_process.py index 168a914b3cc..a26e2be5fe3 100644 --- a/lib/ansible/modules/windows/win_wait_for_process.py +++ b/lib/ansible/modules/windows/win_wait_for_process.py @@ -22,7 +22,7 @@ description: options: process_name_exact: description: - - The name of the process(es) for which to wait. + - The name of the process(es) for which to wait. The name of the process(es) should not include the file extension suffix. type: list process_name_pattern: description: diff --git a/lib/ansible/plugins/doc_fragments/ecs_credential.py b/lib/ansible/plugins/doc_fragments/ecs_credential.py index 36bbbd34833..5f20fc7fd51 100644 --- a/lib/ansible/plugins/doc_fragments/ecs_credential.py +++ b/lib/ansible/plugins/doc_fragments/ecs_credential.py @@ -24,18 +24,18 @@ options: required: true entrust_api_client_cert_path: description: - - The path of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. + - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. type: path required: true entrust_api_client_cert_key_path: description: - - The path of the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. + - The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. type: path required: true entrust_api_specification_path: description: - - Path to the specification file defining the Entrust Certificate Services (ECS) API. - - Can be used to keep a local copy of the specification to avoid downloading it every time the module is used. + - 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. type: path default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml requirements: