From d8630271598c4014e224348416cf229f2f31fdf7 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Thu, 3 Jan 2019 17:50:44 +0100 Subject: [PATCH] Windows: Add missing parameter types and doc fixes (#50232) * Windows: Add missing parameter types and doc fixes This PR includes: - Adding missing parameter types - Various documentation fixes * Update lib/ansible/modules/windows/win_copy.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_credential.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_domain_computer.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_domain_user.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_environment.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_psexec.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_uri.py Co-Authored-By: dagwieers * Update lib/ansible/modules/windows/win_wait_for.py Co-Authored-By: dagwieers * Ensure docstrings are raw strings --- lib/ansible/modules/windows/win_acl.py | 9 +- .../modules/windows/win_acl_inheritance.py | 13 ++- .../windows/win_audit_policy_system.py | 14 ++- lib/ansible/modules/windows/win_audit_rule.py | 24 ++-- .../modules/windows/win_certificate_store.py | 28 +++-- lib/ansible/modules/windows/win_chocolatey.py | 35 +++--- .../modules/windows/win_chocolatey_config.py | 11 +- .../modules/windows/win_chocolatey_feature.py | 10 +- .../modules/windows/win_chocolatey_source.py | 17 +-- lib/ansible/modules/windows/win_command.py | 5 +- lib/ansible/modules/windows/win_copy.py | 33 +++--- lib/ansible/modules/windows/win_credential.py | 33 ++---- lib/ansible/modules/windows/win_defrag.py | 17 +-- lib/ansible/modules/windows/win_disk_facts.py | 40 +++---- lib/ansible/modules/windows/win_disk_image.py | 37 +++--- lib/ansible/modules/windows/win_dns_client.py | 6 +- lib/ansible/modules/windows/win_domain.py | 4 +- .../modules/windows/win_domain_computer.py | 61 +++++----- .../modules/windows/win_domain_controller.py | 30 ++--- .../modules/windows/win_domain_group.py | 22 +++- .../modules/windows/win_domain_membership.py | 13 ++- .../modules/windows/win_domain_user.py | 56 ++++++--- .../modules/windows/win_dotnet_ngen.py | 4 +- lib/ansible/modules/windows/win_dsc.py | 7 +- .../modules/windows/win_environment.py | 6 +- lib/ansible/modules/windows/win_eventlog.py | 13 ++- lib/ansible/modules/windows/win_feature.py | 44 +++---- lib/ansible/modules/windows/win_file.py | 3 +- .../modules/windows/win_file_version.py | 20 ++-- lib/ansible/modules/windows/win_find.py | 108 +++++++++--------- lib/ansible/modules/windows/win_firewall.py | 18 ++- .../modules/windows/win_firewall_rule.py | 26 +++-- lib/ansible/modules/windows/win_get_url.py | 16 +-- lib/ansible/modules/windows/win_group.py | 5 +- .../modules/windows/win_group_membership.py | 4 +- lib/ansible/modules/windows/win_hostname.py | 7 +- lib/ansible/modules/windows/win_hotfix.py | 17 +-- .../windows/win_iis_virtualdirectory.py | 5 + .../modules/windows/win_iis_webapplication.py | 9 +- .../modules/windows/win_iis_webapppool.py | 24 ++-- .../modules/windows/win_iis_webbinding.py | 9 ++ .../modules/windows/win_iis_website.py | 10 ++ lib/ansible/modules/windows/win_lineinfile.py | 33 +++--- .../modules/windows/win_mapped_drive.py | 5 +- lib/ansible/modules/windows/win_msg.py | 4 +- lib/ansible/modules/windows/win_nssm.py | 12 +- lib/ansible/modules/windows/win_owner.py | 15 +-- lib/ansible/modules/windows/win_package.py | 15 ++- lib/ansible/modules/windows/win_pagefile.py | 10 +- lib/ansible/modules/windows/win_partition.py | 2 +- lib/ansible/modules/windows/win_path.py | 8 +- lib/ansible/modules/windows/win_pester.py | 27 ++--- lib/ansible/modules/windows/win_ping.py | 16 ++- lib/ansible/modules/windows/win_power_plan.py | 18 +-- .../modules/windows/win_product_facts.ps1 | 2 +- .../modules/windows/win_product_facts.py | 6 +- lib/ansible/modules/windows/win_psexec.py | 35 +++--- lib/ansible/modules/windows/win_psmodule.py | 20 ++-- .../modules/windows/win_psrepository.py | 6 +- .../modules/windows/win_rabbitmq_plugin.py | 9 +- lib/ansible/modules/windows/win_reboot.py | 4 +- lib/ansible/modules/windows/win_reg_stat.py | 6 +- lib/ansible/modules/windows/win_regedit.py | 15 ++- lib/ansible/modules/windows/win_region.py | 43 ++++--- lib/ansible/modules/windows/win_regmerge.py | 9 +- lib/ansible/modules/windows/win_robocopy.py | 21 ++-- lib/ansible/modules/windows/win_route.py | 5 +- lib/ansible/modules/windows/win_say.py | 8 +- .../modules/windows/win_scheduled_task.py | 55 +++++++-- .../windows/win_scheduled_task_stat.py | 38 +++--- .../modules/windows/win_security_policy.py | 11 +- lib/ansible/modules/windows/win_service.py | 15 ++- lib/ansible/modules/windows/win_share.py | 22 ++-- lib/ansible/modules/windows/win_shell.py | 27 ++--- lib/ansible/modules/windows/win_shortcut.py | 8 +- lib/ansible/modules/windows/win_snmp.py | 13 ++- lib/ansible/modules/windows/win_stat.py | 87 +++++++------- lib/ansible/modules/windows/win_tempfile.py | 7 +- lib/ansible/modules/windows/win_template.py | 15 ++- lib/ansible/modules/windows/win_timezone.py | 5 +- lib/ansible/modules/windows/win_toast.py | 4 + lib/ansible/modules/windows/win_unzip.py | 13 +-- lib/ansible/modules/windows/win_updates.py | 37 +++--- lib/ansible/modules/windows/win_uri.py | 23 ++-- lib/ansible/modules/windows/win_user.py | 15 ++- lib/ansible/modules/windows/win_user_right.py | 10 +- lib/ansible/modules/windows/win_wait_for.py | 19 +-- .../modules/windows/win_wait_for_process.py | 8 +- lib/ansible/modules/windows/win_wakeonlan.py | 3 + lib/ansible/modules/windows/win_webpicmd.py | 3 +- lib/ansible/modules/windows/win_whoami.py | 2 +- lib/ansible/modules/windows/win_xml.py | 31 ++--- 92 files changed, 982 insertions(+), 716 deletions(-) diff --git a/lib/ansible/modules/windows/win_acl.py b/lib/ansible/modules/windows/win_acl.py index a5385780b47..382e555f896 100644 --- a/lib/ansible/modules/windows/win_acl.py +++ b/lib/ansible/modules/windows/win_acl.py @@ -22,20 +22,24 @@ options: path: description: - The path to the file or directory. + type: str required: yes user: description: - User or Group to add specified rights to act on src file/folder or registry key. + type: str required: yes state: description: - Specify whether to add C(present) or remove C(absent) the specified access rule. + type: str choices: [ absent, present ] default: present type: description: - Specify whether to allow or deny the rights specified. + type: str required: yes choices: [ allow, deny ] rights: @@ -46,6 +50,7 @@ options: FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx). - If C(path) is a registry key, rights can be any right under MSDN RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx). + type: str required: yes inherit: description: @@ -55,12 +60,14 @@ options: - For more information on the choices see MSDN InheritanceFlags enumeration at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). - Defaults to C(ContainerInherit, ObjectInherit) for Directories. + type: str choices: [ ContainerInherit, ObjectInherit ] propagation: description: - Propagation flag on the ACL rules. - For more information on the choices see MSDN PropagationFlags enumeration at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx). + type: str choices: [ InheritOnly, None, NoPropagateInherit ] default: "None" notes: @@ -92,7 +99,7 @@ EXAMPLES = r''' inherit: ContainerInherit, ObjectInherit propagation: 'None' -- name: set registry key right +- name: Set registry key right win_acl: path: HKCU:\Bovine\Key user: BUILTIN\Users diff --git a/lib/ansible/modules/windows/win_acl_inheritance.py b/lib/ansible/modules/windows/win_acl_inheritance.py index d2ebd2e3f09..c9a7869dd20 100644 --- a/lib/ansible/modules/windows/win_acl_inheritance.py +++ b/lib/ansible/modules/windows/win_acl_inheritance.py @@ -26,17 +26,18 @@ options: type: path state: description: - - Specify whether to enable I(present) or disable I(absent) ACL inheritance + - Specify whether to enable I(present) or disable I(absent) ACL inheritance. + type: str choices: [ absent, present ] default: absent reorganize: description: - - For P(state) = I(absent), indicates if the inherited ACE's should be copied from the parent directory. This is necessary - (in combination with removal) for a simple ACL instead of using multiple ACE deny entries. - - For P(state) = I(present), indicates if the inherited ACE's should be deduplicated compared to the parent directory. This removes complexity - of the ACL structure. + - For P(state) = I(absent), indicates if the inherited ACE's should be copied from the parent directory. + This is necessary (in combination with removal) for a simple ACL instead of using multiple ACE deny entries. + - For P(state) = I(present), indicates if the inherited ACE's should be deduplicated compared to the parent directory. + This removes complexity of the ACL structure. type: bool - default: 'no' + default: no seealso: - module: win_acl author: diff --git a/lib/ansible/modules/windows/win_audit_policy_system.py b/lib/ansible/modules/windows/win_audit_policy_system.py index 331792cb73c..bbcff6aad71 100644 --- a/lib/ansible/modules/windows/win_audit_policy_system.py +++ b/lib/ansible/modules/windows/win_audit_policy_system.py @@ -9,7 +9,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: win_audit_policy_system short_description: Used to make changes to the system wide Audit Policy @@ -22,16 +22,18 @@ options: - Single string value for the category you would like to adjust the policy on. - Cannot be used with I(subcategory). You must define one or the other. - Changing this setting causes all subcategories to be adjusted to the defined I(audit_type). + type: str subcategory: description: - Single string value for the subcategory you would like to adjust the policy on. - Cannot be used with I(category). You must define one or the other. + type: str audit_type: description: - The type of event you would like to audit for. - Accepts a list. See examples. - required: yes type: list + required: yes choices: [ failure, none, success ] notes: - It is recommended to take a backup of the policies before adjusting them for the first time. @@ -43,23 +45,23 @@ author: ''' EXAMPLES = r''' -- name: enable failure auditing for the subcategory "File System" +- name: Enable failure auditing for the subcategory "File System" win_audit_policy_system: subcategory: File System audit_type: failure -- name: enable all auditing types for the category "Account logon events" +- name: Enable all auditing types for the category "Account logon events" win_audit_policy_system: category: Account logon events audit_type: success, failure -- name: disable auditing for the subcategory "File System" +- name: Disable auditing for the subcategory "File System" win_audit_policy_system: subcategory: File System audit_type: none ''' -RETURN = ''' +RETURN = r''' current_audit_policy: description: details on the policy being targetted returned: always diff --git a/lib/ansible/modules/windows/win_audit_rule.py b/lib/ansible/modules/windows/win_audit_rule.py index 9665b4b25dc..d5687c120eb 100644 --- a/lib/ansible/modules/windows/win_audit_rule.py +++ b/lib/ansible/modules/windows/win_audit_rule.py @@ -24,13 +24,14 @@ options: description: - Path to the file, folder, or registry key. - Registry paths should be in Powershell format, beginning with an abbreviation for the root - such as, 'hklm:\software'. - required: yes + such as, C(HKLM:\Software). type: path + required: yes aliases: [ dest, destination ] user: description: - The user or group to adjust rules for. + type: str required: yes rights: description: @@ -39,8 +40,8 @@ options: FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx). - If I(path) is a registry key, rights can be any right under MSDN RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx). - required: yes type: list + required: yes inheritance_flags: description: - Defines what objects inside of a folder or registry key will inherit the settings. @@ -48,28 +49,29 @@ options: - For more information on the choices see MSDN PropagationFlags enumeration at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). type: list - default: "ContainerInherit,ObjectInherit" choices: [ ContainerInherit, ObjectInherit ] + default: ContainerInherit,ObjectInherit propagation_flags: description: - Propagation flag on the audit rules. - This value is ignored when the path type is a file. - For more information on the choices see MSDN PropagationFlags enumeration at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx). - default: "None" choices: [ None, InherityOnly, NoPropagateInherit ] + default: "None" audit_flags: description: - Defines whether to log on failure, success, or both. - To log both define as comma separated list "Success, Failure". - required: yes type: list + required: yes choices: [ Failure, Success ] state: description: - Whether the rule should be C(present) or C(absent). - For absent, only I(path), I(user), and I(state) are required. - Specifying C(absent) will remove all rules matching the defined I(user). + type: str choices: [ absent, present ] default: present seealso: @@ -79,7 +81,7 @@ author: ''' EXAMPLES = r''' -- name: add filesystem audit rule for a folder +- name: Add filesystem audit rule for a folder win_audit_rule: path: C:\inetpub\wwwroot\website user: BUILTIN\Users @@ -87,7 +89,7 @@ EXAMPLES = r''' audit_flags: success,failure inheritance_flags: ContainerInherit,ObjectInherit -- name: add filesystem audit rule for a file +- name: Add filesystem audit rule for a file win_audit_rule: path: C:\inetpub\wwwroot\website\web.config user: BUILTIN\Users @@ -95,20 +97,20 @@ EXAMPLES = r''' audit_flags: success,failure inheritance_flags: None -- name: add registry audit rule +- name: Add registry audit rule win_audit_rule: path: HKLM:\software user: BUILTIN\Users rights: delete audit_flags: 'success' -- name: remove filesystem audit rule +- name: Remove filesystem audit rule win_audit_rule: path: C:\inetpub\wwwroot\website user: BUILTIN\Users state: absent -- name: remove registry audit rule +- name: Remove registry audit rule win_audit_rule: path: HKLM:\software user: BUILTIN\Users diff --git a/lib/ansible/modules/windows/win_certificate_store.py b/lib/ansible/modules/windows/win_certificate_store.py index 7eecd77617b..dc617e33fd1 100644 --- a/lib/ansible/modules/windows/win_certificate_store.py +++ b/lib/ansible/modules/windows/win_certificate_store.py @@ -32,6 +32,7 @@ options: specified by I(thumbprint). - When exporting a certificate, if I(path) is a directory then the module will fail, otherwise the file will be replaced if needed. + type: str choices: [ absent, exported, present ] default: present path: @@ -45,6 +46,7 @@ options: description: - The thumbprint as a hex string to either export or remove. - See the examples for how to specify the thumbprint. + type: str store_name: description: - The store name to use when importing a certificate or searching for a @@ -57,7 +59,7 @@ options: - "C(Root): The X.509 certificate store for trusted root certificate authorities (CAs)" - "C(TrustedPeople): The X.509 certificate store for directly trusted people and resources" - "C(TrustedPublisher): The X.509 certificate store for directly trusted publishers" - default: My + type: str choices: - AddressBook - AuthRoot @@ -67,6 +69,7 @@ options: - Root - TrustedPeople - TrustedPublisher + default: My store_location: description: - The store location to use when importing a certificate or searching for a @@ -80,6 +83,7 @@ options: set when C(state=exported) and C(file_type=pkcs12). - If the pkcs12 file has no password set or no password should be set on the exported file, do not set this option. + type: str key_exportable: description: - Whether to allow the private key to be exported. @@ -87,7 +91,7 @@ options: the certificate and the private key cannot be exported. - Used when C(state=present) only. type: bool - default: 'yes' + default: yes key_storage: description: - Specifies where Windows will store the private key when it is imported. @@ -99,6 +103,7 @@ options: - Used when C(state=present) only and cannot be changed once imported. - See U(https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509keystorageflags.aspx) for more details. + type: str choices: [ default, machine, user ] default: default file_type: @@ -110,6 +115,7 @@ options: the certificate and private key unlike the other options. - When C(pkcs12) is set and the private key is not exportable or accessible by the current user, it will throw an exception. + type: str choices: [ der, pem, pkcs12 ] default: der notes: @@ -127,12 +133,12 @@ author: ''' EXAMPLES = r''' -- name: import a certificate +- name: Import a certificate win_certificate_store: path: C:\Temp\cert.pem state: present -- name: import pfx certificate that is password protected +- name: Import pfx certificate that is password protected win_certificate_store: path: C:\Temp\cert.pfx state: present @@ -140,7 +146,7 @@ EXAMPLES = r''' become: yes become_method: runas -- name: import pfx certificate without password and set private key as un-exportable +- name: Import pfx certificate without password and set private key as un-exportable win_certificate_store: path: C:\Temp\cert.pfx state: present @@ -149,30 +155,30 @@ EXAMPLES = r''' vars: ansible_winrm_transport: credssp -- name: remove a certificate based on file thumbprint +- name: Remove a certificate based on file thumbprint win_certificate_store: path: C:\Temp\cert.pem state: absent -- name: remove a certificate based on thumbprint +- name: Remove a certificate based on thumbprint win_certificate_store: thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27 state: absent -- name: remove certificate based on thumbprint is CurrentUser/TrustedPublishers store +- name: Remove certificate based on thumbprint is CurrentUser/TrustedPublishers store win_certificate_store: thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27 state: absent store_location: CurrentUser store_name: TrustedPublisher -- name: export certificate as der encoded file +- name: Export certificate as der encoded file win_certificate_store: path: C:\Temp\cert.cer state: exported file_type: der -- name: export certificate and key as pfx encoded file +- name: Export certificate and key as pfx encoded file win_certificate_store: path: C:\Temp\cert.pfx state: exported @@ -182,7 +188,7 @@ EXAMPLES = r''' become_method: runas become_user: SYSTEM -- name: import certificate be used by IIS +- name: Import certificate be used by IIS win_certificate_store: path: C:\Temp\cert.pfx file_type: pkcs12 diff --git a/lib/ansible/modules/windows/win_chocolatey.py b/lib/ansible/modules/windows/win_chocolatey.py index ed60cb5fe59..6e4cf71f5c0 100644 --- a/lib/ansible/modules/windows/win_chocolatey.py +++ b/lib/ansible/modules/windows/win_chocolatey.py @@ -30,7 +30,7 @@ options: - Use M(win_chocolatey_feature) with the name C(allowEmptyChecksums) to control this option globally. type: bool - default: 'no' + default: no version_added: '2.2' allow_multiple: description: @@ -46,7 +46,7 @@ options: - If I(state) is C(latest), the latest pre-release package will be installed. type: bool - default: 'no' + default: no version_added: '2.6' architecture: description: @@ -55,9 +55,7 @@ options: - When setting C(x86), will ensure Chocolatey installs the x86 package even when on an x64 bit OS. type: str - choices: - - default - - x86 + choices: [ default, x86 ] default: default version_added: '2.7' force: @@ -66,7 +64,7 @@ options: - Using I(force) will cause Ansible to always report that a change was made. type: bool - default: 'no' + default: no install_args: description: - Arguments to pass to the native installer. @@ -80,20 +78,20 @@ options: - Use M(win_chocolatey_feature) with the name C(checksumFiles) to control this option globally. type: bool - default: 'no' + default: no version_added: '2.2' ignore_dependencies: description: - Ignore dependencies, only install/upgrade the package itself. type: bool - default: 'no' + default: no version_added: '2.1' name: description: - Name of the package(s) to be installed. - Set to C(all) to run the action on all the installed packages. - required: yes type: list + required: yes package_params: description: - Parameters to pass to the package. @@ -102,8 +100,7 @@ options: - Before Ansible 2.7, this option was just I(params). type: str version_added: '2.1' - aliases: - - params + aliases: [ params ] proxy_url: description: - Proxy URL used to install chocolatey and the package. @@ -134,7 +131,7 @@ options: - Do not run I(chocolateyInstall.ps1) or I(chocolateyUninstall.ps1) scripts when installing a package. type: bool - default: 'no' + default: no version_added: '2.4' source: description: @@ -172,22 +169,16 @@ options: - When C(latest), will ensure the package is installed to the latest available version. - When C(reinstalled), will uninstall and reinstall the package. - choices: - - absent - - downgrade - - latest - - present - - reinstalled - default: present type: str + choices: [ absent, downgrade, latest, present, reinstalled ] + default: present timeout: description: - The time to allow chocolatey to finish before timing out. type: int default: 2700 version_added: '2.3' - aliases: - - execution_timeout + aliases: [ execution_timeout ] validate_certs: description: - Used when downloading the Chocolatey install script if Chocolatey is not @@ -197,7 +188,7 @@ options: - This should only be used on personally controlled sites using self-signed certificate. type: bool - default: 'yes' + default: yes version_added: '2.7' version: description: diff --git a/lib/ansible/modules/windows/win_chocolatey_config.py b/lib/ansible/modules/windows/win_chocolatey_config.py index 20b9ae9577d..1d20bab311f 100644 --- a/lib/ansible/modules/windows/win_chocolatey_config.py +++ b/lib/ansible/modules/windows/win_chocolatey_config.py @@ -23,15 +23,15 @@ options: valid configuration settings that can be changed. - Any config values that contain encrypted values like a password are not idempotent as the plaintext value cannot be read. + type: str required: yes state: description: - When C(absent), it will ensure the setting is unset or blank. - When C(present), it will ensure the setting is set to the value of I(value). - choices: - - absent - - present + type: str + choices: [ absent, present ] default: present value: description: @@ -39,6 +39,7 @@ options: setting. - Cannot be null or an empty string, use C(state=absent) to unset a config value instead. + type: str seealso: - module: win_chocolatey - module: win_chocolatey_facts @@ -49,13 +50,13 @@ author: ''' EXAMPLES = r''' -- name: set the cache location +- name: Set the cache location win_chocolatey_config: name: cacheLocation state: present value: D:\chocolatey_temp -- name: unset the cache location +- name: Unset the cache location win_chocolatey_config: name: cacheLocation state: absent diff --git a/lib/ansible/modules/windows/win_chocolatey_feature.py b/lib/ansible/modules/windows/win_chocolatey_feature.py index 4f8512bf242..13358f4e1ee 100644 --- a/lib/ansible/modules/windows/win_chocolatey_feature.py +++ b/lib/ansible/modules/windows/win_chocolatey_feature.py @@ -21,14 +21,14 @@ options: - The name of the feature to manage. - Run C(choco.exe feature list) to get a list of features that can be managed. + type: str required: yes state: description: - When C(disabled) then the feature will be disabled. - When C(enabled) then the feature will be enabled. - choices: - - disabled - - enabled + type: str + choices: [ disabled, enabled ] default: enabled seealso: - module: win_chocolatey @@ -40,12 +40,12 @@ author: ''' EXAMPLES = r''' -- name: disable file checksum matching +- name: Disable file checksum matching win_chocolatey_feature: name: checksumFiles state: disabled -- name: stop Chocolatey on the first package failure +- name: Stop Chocolatey on the first package failure win_chocolatey_feature: name: stopOnFirstPackageFailure state: enabled diff --git a/lib/ansible/modules/windows/win_chocolatey_source.py b/lib/ansible/modules/windows/win_chocolatey_source.py index 12b2b713c86..69f62bab3bb 100644 --- a/lib/ansible/modules/windows/win_chocolatey_source.py +++ b/lib/ansible/modules/windows/win_chocolatey_source.py @@ -21,24 +21,25 @@ options: description: - Makes the source visible to Administrators only. - Requires Chocolatey >= 0.10.8. - - When creating a new source, this defaults to C(False). + - When creating a new source, this defaults to C(no). type: bool allow_self_service: description: - Allow the source to be used with self-service - Requires Chocolatey >= 0.10.4. - - When creating a new source, this defaults to C(False). + - When creating a new source, this defaults to C(no). type: bool bypass_proxy: description: - Bypass the proxy when using this source. - Requires Chocolatey >= 0.10.4. - - When creating a new source, this defaults to C(False). + - When creating a new source, this defaults to C(no). type: bool certificate: description: - The path to a .pfx file to use for X509 authenticated feeds. - Requires Chocolatey >= 0.9.10. + type: str certificate_password: description: - The password for I(certificate) if required. @@ -97,18 +98,18 @@ author: ''' EXAMPLES = r''' -- name: remove the default public source +- name: Remove the default public source win_chocolatey_source: name: chocolatey state: absent -- name: add new internal source +- name: Add new internal source win_chocolatey_source: name: internal repo state: present source: http://chocolatey-server/chocolatey -- name: create HTTP source with credentials +- name: Create HTTP source with credentials win_chocolatey_source: name: internal repo state: present @@ -116,9 +117,9 @@ EXAMPLES = r''' source_username: username source_password: password -- name: disable Chocolatey source +- name: Disable Chocolatey source win_chocolatey_source: - name: chocoaltey + name: chocolatey state: disabled ''' diff --git a/lib/ansible/modules/windows/win_command.py b/lib/ansible/modules/windows/win_command.py index 17d7fcd3732..8fda93913ac 100644 --- a/lib/ansible/modules/windows/win_command.py +++ b/lib/ansible/modules/windows/win_command.py @@ -25,6 +25,7 @@ options: description: - The C(win_command) module takes a free form command to run. - There is no parameter actually named 'free form'. See the examples! + type: str required: yes creates: description: @@ -41,6 +42,7 @@ options: stdin: description: - Set the stdin of the command directly to the specified value. + type: str version_added: '2.5' notes: - If you want to run a command through a shell (say you are using C(<), @@ -49,7 +51,6 @@ notes: environment. - C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this. - - For non-Windows targets, use the M(command) module instead. seealso: - module: command - module: psexec @@ -82,7 +83,7 @@ msg: description: changed returned: always type: bool - sample: True + sample: true start: description: The command execution start time returned: always diff --git a/lib/ansible/modules/windows/win_copy.py b/lib/ansible/modules/windows/win_copy.py index cf01af7d4db..b70707945d6 100644 --- a/lib/ansible/modules/windows/win_copy.py +++ b/lib/ansible/modules/windows/win_copy.py @@ -21,19 +21,21 @@ options: content: description: - When used instead of C(src), sets the contents of a file directly to the - specified value. This is for simple values, for anything complex or with - formatting please switch to the template module. + specified value. + - This is for simple values, for anything complex or with formatting please + switch to the M(template) module. + type: str version_added: '2.3' decrypt: description: - This option controls the autodecryption of source files using vault. type: bool - default: 'yes' + default: yes version_added: '2.5' dest: description: - - Remote absolute path where the file should be copied to. If src is a - directory, this must be a directory too. + - Remote absolute path where the file should be copied to. + - If C(src) is a directory, this must be a directory too. - Use \ for path separators or \\ when in "double quotes". - If C(dest) ends with \ then source or the contents of source will be copied to the directory without renaming. @@ -52,21 +54,21 @@ options: - If set to C(no), no checksuming of the content is performed which can help improve performance on larger files. type: bool - default: 'yes' + default: yes version_added: '2.3' local_follow: description: - This flag indicates that filesystem links in the source tree, if they exist, should be followed. type: bool - default: 'yes' + default: yes version_added: '2.4' remote_src: description: - If C(no), it will search for src at originating/master machine. - If C(yes), it will go to the remote/target machine for the src. type: bool - default: 'no' + default: no version_added: '2.3' src: description: @@ -79,10 +81,9 @@ options: end with "/", the directory itself with all contents is copied. - If path is a file and dest ends with "\", the file is copied to the folder with the same filename. - required: yes type: path + required: yes notes: -- For non-Windows targets, use the M(copy) module instead. - Currently win_copy does not support copying symbolic links from both local to remote and remote to remote. - It is recommended that backslashes C(\) are used instead of C(/) when dealing @@ -141,32 +142,32 @@ EXAMPLES = r''' RETURN = r''' dest: - description: destination file/path + description: Destination file/path. returned: changed type: str sample: C:\Temp\ src: - description: source file used for the copy on the target machine + description: Source file used for the copy on the target machine. returned: changed type: str sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source checksum: - description: sha1 checksum of the file after running copy + description: SHA1 checksum of the file after running copy. returned: success, src is a file type: str sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827 size: - description: size of the target, after execution + description: Size of the target, after execution. returned: changed, src is a file type: int sample: 1220 operation: - description: whether a single file copy took place or a folder copy + description: Whether a single file copy took place or a folder copy. returned: success type: str sample: file_copy original_basename: - description: basename of the copied file + description: Basename of the copied file. returned: changed, src is a file type: str sample: foo.txt diff --git a/lib/ansible/modules/windows/win_credential.py b/lib/ansible/modules/windows/win_credential.py index 47976926f2a..6912f6b7e8c 100644 --- a/lib/ansible/modules/windows/win_credential.py +++ b/lib/ansible/modules/windows/win_credential.py @@ -36,7 +36,8 @@ options: - The key for the attribute. - This is not a unique identifier as multiple attributes can have the same key. - required: True + type: str + required: true data: description: - The value for the attribute. @@ -48,9 +49,7 @@ options: - If C(base64), I(data) is a base64 string that is base64 decoded to bytes. type: str - choices: - - base64 - - text + choices: [ base64, text ] default: text comment: description: @@ -66,8 +65,8 @@ options: - See C(TargetName) in U(https://docs.microsoft.com/en-us/windows/desktop/api/wincred/ns-wincred-_credentiala) for more details on what this value can be. - This is used with I(type) to produce a unique credential. - required: True type: str + required: true persistence: description: - Defines the persistence of the credential. @@ -76,9 +75,7 @@ options: - C(enterprise) is the same as C(local) but the credential is visible to the same domain user when running on other hosts and not just localhost. type: str - choices: - - enterprise - - local + choices: [ enterprise, local ] default: local secret: description: @@ -95,9 +92,7 @@ options: - If C(base64), I(secret) is a base64 string that is base64 decoded to bytes. type: str - choices: - - base64 - - text + choices: [ base64, text ] default: text state: description: @@ -106,9 +101,7 @@ options: - When C(present), the credential specified by I(name) and I(type) is removed. type: str - choices: - - absent - - present + choices: [ absent, present ] default: present type: description: @@ -120,13 +113,9 @@ options: particular authentication package. - It is recommended to use a C(domain) type as only authentication providers can access the secret. - required: True type: str - choices: - - domain_password - - domain_certificate - - generic_password - - generic_certificate + required: true + choices: [ domain_certificate, domain_password, generic_certificate, generic_password ] update_secret: description: - When C(always), the secret will always be updated if they differ. @@ -135,9 +124,7 @@ options: - If the secret cannot be retrieved and this is set to C(always), the module will always result in a change. type: str - choices: - - always - - on_create + choices: [ always, on_create ] default: always username: description: diff --git a/lib/ansible/modules/windows/win_defrag.py b/lib/ansible/modules/windows/win_defrag.py index 7bfd20bc595..6889dfb7dce 100644 --- a/lib/ansible/modules/windows/win_defrag.py +++ b/lib/ansible/modules/windows/win_defrag.py @@ -31,16 +31,19 @@ options: freespace_consolidation: description: - Perform free space consolidation on the specified volumes. + type: bool + default: no priority: description: - Run the operation at low or normal priority. + type: str choices: [ low, normal ] default: low parallel: description: - Run the operation on each volume in parallel in the background. type: bool - default: 'no' + default: no author: - Dag Wieers (@dagwieers) ''' @@ -66,27 +69,27 @@ EXAMPLES = r''' RETURN = r''' cmd: - description: The complete command line used by the module + description: The complete command line used by the module. returned: always type: str sample: defrag.exe /C /V rc: - description: The return code for the command + description: The return code for the command. returned: always type: int sample: 0 stdout: - description: The standard output from the command + description: The standard output from the command. returned: always type: str sample: Success. stderr: - description: The error output from the command + description: The error output from the command. returned: always type: str sample: msg: - description: Possible error message on failure + description: Possible error message on failure. returned: failed type: str sample: Command 'defrag.exe' not found in $env:PATH. @@ -94,5 +97,5 @@ changed: description: Whether or not any changes were made. returned: always type: bool - sample: True + sample: true ''' diff --git a/lib/ansible/modules/windows/win_disk_facts.py b/lib/ansible/modules/windows/win_disk_facts.py index 16d912fdc9e..2a9f293545a 100644 --- a/lib/ansible/modules/windows/win_disk_facts.py +++ b/lib/ansible/modules/windows/win_disk_facts.py @@ -17,12 +17,12 @@ description: - With the module you can retrieve and output detailed information about the attached disks of the target and its volumes and partitions if existent. requirements: - - Windows 8.1 / Windows 2012 (NT 6.2) + - Windows 8.1 / Windows 2012 (NT 6.2) notes: - In order to understand all the returned properties and values please visit the following site and open the respective MSFT class U(https://msdn.microsoft.com/en-us/library/windows/desktop/hh830612.aspx) author: - - Marc Tschapek (@marqelme) + - Marc Tschapek (@marqelme) ''' EXAMPLES = r''' @@ -41,7 +41,7 @@ EXAMPLES = r''' disk: '{{ ansible_facts.disks|selectattr("system_disk")|first }}' # Show disk size in Gibibytes - disksize_gib_human: '{{ disk.size|filesizeformat(True) }}' # returns "223.6 GiB" (human readable) + disksize_gib_human: '{{ disk.size|filesizeformat(true) }}' # returns "223.6 GiB" (human readable) disksize_gib: '{{ (disk.size/1024|pow(3))|round|int }} GiB' # returns "224 GiB" (value in GiB) # Show disk size in Gigabytes @@ -108,22 +108,22 @@ ansible_facts: description: Read only status of the particular disk. returned: always type: bool - sample: True + sample: true bootable: description: Information whether the particular disk is a bootable disk. returned: always type: bool - sample: False + sample: false system_disk: description: Information whether the particular disk is a system disk. returned: always type: bool - sample: True + sample: true clustered: description: Information whether the particular disk is clustered (part of a failover cluster). returned: always type: bool - sample: False + sample: false manufacturer: description: Manufacturer of the particular disk. returned: always @@ -194,7 +194,7 @@ ansible_facts: description: Information whether the particular partition has a default drive letter or not. returned: if partition_style property of the particular disk has value "GPT" type: bool - sample: True + sample: true mbr_type: description: mbr type of the particular partition. returned: if partition_style property of the particular disk has value "MBR" @@ -204,7 +204,7 @@ ansible_facts: description: Information whether the particular partition is an active partition or not. returned: if partition_style property of the particular disk has value "MBR" type: bool - sample: True + sample: true drive_letter: description: Drive letter of the particular partition. returned: if existent @@ -224,12 +224,12 @@ ansible_facts: description: Information whether the particular partition is hidden or not. returned: always type: bool - sample: True + sample: true shadow_copy: description: Information whether the particular partition is a shadow copy of another partition. returned: always type: bool - sample: False + sample: false guid: description: GUID of the particular partition. returned: if existent @@ -383,7 +383,7 @@ ansible_facts: description: Information whether the particular physical disk can be added to a storage pool. returned: always type: bool - sample: False + sample: false cannot_pool_reason: description: Information why the particular physical disk can not be added to a storage pool. returned: if can_pool property has value false @@ -393,12 +393,12 @@ ansible_facts: description: Information whether indication is enabled for the particular physical disk. returned: always type: bool - sample: True + sample: true partial: description: Information whether the particular physical disk is partial. returned: always type: bool - sample: False + sample: false serial_number: description: Serial number of the particular physical disk. returned: always @@ -507,27 +507,27 @@ ansible_facts: description: Information whether deduplication is enabled for the particular virtual disk. returned: always type: bool - sample: True + sample: true enclosure_aware: description: Information whether the particular virtual disk is enclosure aware. returned: always type: bool - sample: False + sample: false manual_attach: description: Information whether the particular virtual disk is manual attached. returned: always type: bool - sample: True + sample: true snapshot: description: Information whether the particular virtual disk is a snapshot. returned: always type: bool - sample: False + sample: false tiered: description: Information whether the particular virtual disk is tiered. returned: always type: bool - sample: True + sample: true physical_sector_size: description: Physical sector size in bytes of the particular virtual disk. returned: always @@ -567,7 +567,7 @@ ansible_facts: description: Information whether the particular virtual disk requests no single point of failure. returned: always type: bool - sample: True + sample: true resiliency_setting_name: description: Type of the physical disk redundancy of the particular virtual disk. returned: always diff --git a/lib/ansible/modules/windows/win_disk_image.py b/lib/ansible/modules/windows/win_disk_image.py index 2153013f4bf..9a83e49693f 100644 --- a/lib/ansible/modules/windows/win_disk_image.py +++ b/lib/ansible/modules/windows/win_disk_image.py @@ -8,41 +8,31 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' module: win_disk_image short_description: Manage ISO/VHD/VHDX mounts on Windows hosts version_added: '2.3' description: - Manages mount behavior for a specified ISO, VHD, or VHDX image on a Windows host. When C(state) is C(present), the image will be mounted under a system-assigned drive letter, which will be returned in the C(mount_path) value - of the module result. Requires Windows 8+ or Windows Server 2012+. + of the module result. + - Requires Windows 8+ or Windows Server 2012+. options: image_path: description: - Path to an ISO, VHD, or VHDX image on the target Windows host (the file cannot reside on a network share) + type: str required: yes state: description: - Whether the image should be present as a drive-letter mount or not. + type: str choices: [ absent, present ] default: present author: - Matt Davis (@nitzmahone) ''' -RETURN = r''' -mount_path: - description: filesystem path where the target image is mounted, this has been deprecated in favour of C(mount_paths) - returned: when C(state) is C(present) - type: str - sample: F:\ -mount_paths: - description: a list of filesystem paths mounted from the target image - returned: when C(state) is C(present) - type: list - sample: [ 'E:\', 'F:\' ] -''' - EXAMPLES = r''' # Run installer from mounted ISO, then unmount - name: Ensure an ISO is mounted @@ -51,14 +41,27 @@ EXAMPLES = r''' state: present register: disk_image_out -- name: Run installer from mounted iso +- name: Run installer from mounted ISO win_package: path: '{{ disk_image_out.mount_paths[0] }}setup\setup.exe' product_id: 35a4e767-0161-46b0-979f-e61f282fee21 state: present -- name: Unmount iso +- name: Unmount ISO win_disk_image: image_path: C:\install.iso state: absent ''' + +RETURN = r''' +mount_path: + description: Filesystem path where the target image is mounted, this has been deprecated in favour of C(mount_paths). + returned: when C(state) is C(present) + type: str + sample: F:\ +mount_paths: + description: A list of filesystem paths mounted from the target image. + returned: when C(state) is C(present) + type: list + sample: [ 'E:\', 'F:\' ] +''' diff --git a/lib/ansible/modules/windows/win_dns_client.py b/lib/ansible/modules/windows/win_dns_client.py index 465c8cc1c6c..9483a23e76e 100644 --- a/lib/ansible/modules/windows/win_dns_client.py +++ b/lib/ansible/modules/windows/win_dns_client.py @@ -19,12 +19,14 @@ options: adapter_names: description: - Adapter name or list of adapter names for which to manage DNS settings ('*' is supported as a wildcard value). - The adapter name used is the connection caption in the Network Control Panel or via C(Get-NetAdapter), eg C(Local Area Connection). + - The adapter name used is the connection caption in the Network Control Panel or via C(Get-NetAdapter), eg C(Local Area Connection). + type: str required: yes ipv4_addresses: description: - Single or ordered list of DNS server IPv4 addresses to configure for lookup. An empty list will configure the adapter to use the DHCP-assigned values on connections where DHCP is enabled, or disable DNS lookup on statically-configured connections. + type: str required: yes notes: - When setting an empty list of DNS server addresses on an adapter with DHCP enabled, a change will always be registered, since it is not possible to @@ -53,6 +55,6 @@ EXAMPLES = r''' ipv4_addresses: [] ''' -RETURN = ''' +RETURN = r''' ''' diff --git a/lib/ansible/modules/windows/win_domain.py b/lib/ansible/modules/windows/win_domain.py index 8aa50aecb23..730486513ae 100644 --- a/lib/ansible/modules/windows/win_domain.py +++ b/lib/ansible/modules/windows/win_domain.py @@ -20,8 +20,8 @@ options: dns_domain_name: description: - The DNS name of the domain which should exist and be reachable or reside on the target Windows host. - required: yes type: str + required: yes domain_netbios_name: description: - The NetBIOS name for the root domain in the new forest. @@ -32,8 +32,8 @@ options: safe_mode_password: description: - Safe mode password for the domain controller. - required: yes type: str + required: yes database_path: description: - The path to a directory on a fixed disk of the Windows host where the diff --git a/lib/ansible/modules/windows/win_domain_computer.py b/lib/ansible/modules/windows/win_domain_computer.py index 67c4d3719fb..13a149ce9f3 100644 --- a/lib/ansible/modules/windows/win_domain_computer.py +++ b/lib/ansible/modules/windows/win_domain_computer.py @@ -4,13 +4,11 @@ # Copyright: (c) 2017, AMTEGA - Xunta de Galicia # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) - ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} - -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: win_domain_computer short_description: Manage computers in Active Directory @@ -22,49 +20,55 @@ version_added: '2.6' options: name: description: - - Specifies the name of the object. This parameter sets the Name property - of the Active Directory object. The LDAP display name (ldapDisplayName) - of this property is name. + - Specifies the name of the object. + - This parameter sets the Name property of the Active Directory object. + - The LDAP display name (ldapDisplayName) of this property is name. + type: str required: true sam_account_name: description: - Specifies the Security Account Manager (SAM) account name of the - computer. It maximum is 256 characters, 15 is advised for older - operating systems compatibility. The LDAP display name - (ldapDisplayName) for this property is sAMAccountName. If ommitted the - value is the same as C(name). - Note. All computer SAMAccountNames needs to end with a $. + computer. + - It maximum is 256 characters, 15 is advised for older + operating systems compatibility. + - The LDAP display name (ldapDisplayName) for this property is sAMAccountName. + - If ommitted the value is the same as C(name). + - Note that all computer SAMAccountNames need to end with a $. + type: str enabled: description: - - Specifies if an account is enabled. An enabled account requires a - password. This parameter sets the Enabled property for an account - object. This parameter also sets the ADS_UF_ACCOUNTDISABLE flag of the + - Specifies if an account is enabled. + - An enabled account requires a password. + - This parameter sets the Enabled property for an account object. + - This parameter also sets the ADS_UF_ACCOUNTDISABLE flag of the Active Directory User Account Control (UAC) attribute. type: bool - default: 'yes' + default: yes ou: description: - Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. Required when I(state=present). + type: str description: description: - - Specifies a description of the object. This parameter sets the value - of the Description property for the object. The LDAP display name - (ldapDisplayName) for this property is description. + - Specifies a description of the object. + - This parameter sets the value of the Description property for the object. + - The LDAP display name (ldapDisplayName) for this property is description. + type: str default: '' dns_hostname: description: - - Specifies the fully qualified domain name (FQDN) of the computer. This - parameter sets the DNSHostName property for a computer object. The LDAP - display name for this property is dNSHostName. Required when - I(state=present). + - Specifies the fully qualified domain name (FQDN) of the computer. + - This parameter sets the DNSHostName property for a computer object. + - The LDAP display name for this property is dNSHostName. + - Required when I(state=present). + type: str state: description: - Specified whether the computer should be C(present) or C(absent) in Active Directory. - choices: - - present - - absent + type: str + choices: [ absent, present ] default: present seealso: - module: win_domain @@ -72,10 +76,11 @@ seealso: - module: win_domain_group - module: win_domain_membership - module: win_domain_user -author: Daniel Sánchez Fábregas (@Daniel-Sanchez-Fabregas) +author: +- Daniel Sánchez Fábregas (@Daniel-Sanchez-Fabregas) ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Add linux computer to Active Directory OU using a windows machine win_domain_computer: name: one_linux_server.my_org.local @@ -94,5 +99,5 @@ EXAMPLES = ''' delegate_to: my_windows_bridge.my_org.local ''' -RETURN = ''' +RETURN = r''' ''' diff --git a/lib/ansible/modules/windows/win_domain_controller.py b/lib/ansible/modules/windows/win_domain_controller.py index f3f0b7dd29b..8bfd84cb09b 100644 --- a/lib/ansible/modules/windows/win_domain_controller.py +++ b/lib/ansible/modules/windows/win_domain_controller.py @@ -14,45 +14,48 @@ module: win_domain_controller short_description: Manage domain controller/member server state for a Windows host version_added: '2.3' description: - - Ensure that a Windows Server 2012+ host is configured as a domain controller or demoted to member server. This module may require - subsequent use of the M(win_reboot) action if changes are made. + - Ensure that a Windows Server 2012+ host is configured as a domain controller or demoted to member server. + - This module may require subsequent use of the M(win_reboot) action if changes are made. options: dns_domain_name: description: - When C(state) is C(domain_controller), the DNS name of the domain for which the targeted Windows host should be a DC. + type: str domain_admin_user: description: - Username of a domain admin for the target domain (necessary to promote or demote a domain controller). + type: str required: true domain_admin_password: description: - Password for the specified C(domain_admin_user). + type: str required: true safe_mode_password: description: - Safe mode password for the domain controller (required when C(state) is C(domain_controller)). + type: str local_admin_password: description: - Password to be assigned to the local C(Administrator) user (required when C(state) is C(member_server)). + type: str read_only: description: - - Whether to install the domain controller as a read only replica for an - existing domain. + - Whether to install the domain controller as a read only replica for an existing domain. type: bool - default: 'no' + default: no version_added: '2.5' site_name: description: - - Specifies the name of an existing site where you can place the new - domain controller. + - Specifies the name of an existing site where you can place the new domain controller. - This option is required when I(read_only) is C(yes). + type: str version_added: '2.5' state: description: - Whether the target host should be a domain controller or a member server. - choices: - - domain_controller - - member_server + type: str + choices: [ domain_controller, member_server ] database_path: description: - The path to a directory on a fixed disk of the Windows host where the @@ -77,17 +80,16 @@ author: - Matt Davis (@nitzmahone) ''' -RETURN = ''' +RETURN = r''' reboot_required: description: True if changes were made that require a reboot. returned: always type: bool sample: true - ''' EXAMPLES = r''' -- name: ensure a server is a domain controller +- name: Ensure a server is a domain controller win_domain_controller: dns_domain_name: ansible.vagrant domain_admin_user: testguy@ansible.vagrant @@ -109,7 +111,7 @@ EXAMPLES = r''' state: member_server log_path: C:\ansible_win_domain_controller.txt -- name: promote server as a read only domain controller +- name: Promote server as a read only domain controller win_domain_controller: dns_domain_name: ansible.vagrant domain_admin_user: testguy@ansible.vagrant diff --git a/lib/ansible/modules/windows/win_domain_group.py b/lib/ansible/modules/windows/win_domain_group.py index a55a956a99c..6542dee0f86 100644 --- a/lib/ansible/modules/windows/win_domain_group.py +++ b/lib/ansible/modules/windows/win_domain_group.py @@ -23,32 +23,39 @@ options: - This can be used to set custom attributes that are not exposed as module parameters, e.g. C(mail). - See the examples on how to format this parameter. + type: dict category: description: - The category of the group, this is the value to assign to the LDAP C(groupType) attribute. - If a new group is created then C(security) will be used by default. + type: str choices: [ distribution, security ] description: description: - The value to be assigned to the LDAP C(description) attribute. + type: str display_name: description: - The value to assign to the LDAP C(displayName) attribute. + type: str domain_username: description: - The username to use when interacting with AD. - If this is not set then the user Ansible used to log in with will be used instead. + type: str domain_password: description: - The password for C(username). + type: str domain_server: description: - Specifies the Active Directory Domain Services instance to connect to. - Can be in the form of an FQDN or NetBIOS name. - If not specified then the value is based on the domain of the computer running PowerShell. + type: str version_added: '2.5' ignore_protection: description: @@ -57,24 +64,26 @@ options: - The module will fail if one of these actions need to occur and this value is set to C(no). type: bool - default: 'no' + default: no managed_by: description: - The value to be assigned to the LDAP C(managedBy) attribute. - This value can be in the forms C(Distinguished Name), C(objectGUID), C(objectSid) or C(sAMAccountName), see examples for more details. + type: str name: description: - The name of the group to create, modify or remove. - This value can be in the forms C(Distinguished Name), C(objectGUID), C(objectSid) or C(sAMAccountName), see examples for more details. + type: str required: yes organizational_unit: description: - The full LDAP path to create or move the group to. - - This should be the path to the parent object to create or move the group - to. + - This should be the path to the parent object to create or move the group to. - See examples for details of how this path is formed. + type: str aliases: [ ou, path ] protect: description: @@ -86,17 +95,18 @@ options: description: - The scope of the group. - If C(state=present) and the group doesn't exist then this must be set. + type: str choices: [domainlocal, global, universal] state: description: - If C(state=present) this module will ensure the group is created and is configured accordingly. - If C(state=absent) this module will delete the group if it exists + type: str choices: [ absent, present ] default: present notes: -- This must be run on a host that has the ActiveDirectory powershell module - installed. +- This must be run on a host that has the ActiveDirectory powershell module installed. seealso: - module: win_domain - module: win_domain_controller @@ -218,7 +228,7 @@ protected_from_accidental_deletion: description: Whether the group is protected from accidental deletion. returned: group exists type: bool - sample: True + sample: true sid: description: The Security ID of the group. returned: group exists diff --git a/lib/ansible/modules/windows/win_domain_membership.py b/lib/ansible/modules/windows/win_domain_membership.py index 6808013b8b5..e74a0d8c01c 100644 --- a/lib/ansible/modules/windows/win_domain_membership.py +++ b/lib/ansible/modules/windows/win_domain_membership.py @@ -8,7 +8,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' module: win_domain_membership short_description: Manage domain/workgroup membership for a Windows host version_added: '2.3' @@ -19,28 +19,35 @@ options: dns_domain_name: description: - When C(state) is C(domain), the DNS name of the domain to which the targeted Windows host should be joined. + type: str domain_admin_user: description: - Username of a domain admin for the target domain (required to join or leave the domain). + type: str required: yes domain_admin_password: description: - Password for the specified C(domain_admin_user). + type: str hostname: description: - The desired hostname for the Windows host. + type: str domain_ou_path: description: - The desired OU path for adding the computer object. - This is only used when adding the target host to a domain, if it is already a member then it is ignored. + type: str version_added: "2.4" state: description: - Whether the target host should be a member of a domain or workgroup. + type: str choices: [ domain, workgroup ] workgroup_name: description: - When C(state) is C(workgroup), the name of the workgroup that the Windows host should be in. + type: str seealso: - module: win_domain - module: win_domain_controller @@ -54,7 +61,7 @@ author: - Matt Davis (@nitzmahone) ''' -RETURN = ''' +RETURN = r''' reboot_required: description: True if changes were made that require a reboot. returned: always @@ -62,7 +69,7 @@ reboot_required: sample: true ''' -EXAMPLES = ''' +EXAMPLES = r''' # host should be a member of domain ansible.vagrant; module will ensure the hostname is mydomainclient # and will use the passed credentials to join domain if necessary. diff --git a/lib/ansible/modules/windows/win_domain_user.py b/lib/ansible/modules/windows/win_domain_user.py index 33980f872a0..90105691725 100644 --- a/lib/ansible/modules/windows/win_domain_user.py +++ b/lib/ansible/modules/windows/win_domain_user.py @@ -21,12 +21,14 @@ options: name: description: - Name of the user to create, remove or modify. + type: str required: true state: description: - - When C(present), creates or updates the user account. When C(absent), - removes the user account if it exists. When C(query), - retrieves the user account details without making any changes. + - When C(present), creates or updates the user account. + - When C(absent), removes the user account if it exists. + - When C(query), retrieves the user account details without making any changes. + type: str choices: [ absent, present, query ] default: present enabled: @@ -34,39 +36,41 @@ options: - C(yes) will enable the user account. - C(no) will disable the account. type: bool - default: 'yes' + default: yes account_locked: description: - - C(no) will unlock the user account if locked. Note that there is not a - way to lock an account as an administrator. Accounts are locked due to - user actions; as an admin, you may only unlock a locked account. If you - wish to administratively disable an account, set I(enabled) to C(no). - choices: [ 'no' ] + - C(no) will unlock the user account if locked. + - Note that there is not a way to lock an account as an administrator. + - Accounts are locked due to user actions; as an admin, you may only unlock a locked account. + - If you wish to administratively disable an account, set I(enabled) to C(no). + choices: [ no ] description: description: - Description of the user + type: str groups: description: - Adds or removes the user from this list of groups, - depending on the value of I(groups_action). To remove all but the - Principal Group, set C(groups=) and - I(groups_action=replace). Note that users cannot be removed from - their principal group (for example, "Domain Users"). + depending on the value of I(groups_action). + - To remove all but the Principal Group, set C(groups=) and + I(groups_action=replace). + - Note that users cannot be removed from their principal group (for example, "Domain Users"). type: list groups_action: description: - - If C(add), the user is added to each group in I(groups) where not - already a member. + - If C(add), the user is added to each group in I(groups) where not already a member. - If C(remove), the user is removed from each group in I(groups). - If C(replace), the user is added as a member of each group in I(groups) and removed from any other groups. + type: str choices: [ add, remove, replace ] default: replace password: description: - - Optionally set the user's password to this (plain text) value. In order - to enable an account - I(enabled) - a password must already be + - Optionally set the user's password to this (plain text) value. + - To enable an account - I(enabled) - a password must already be configured on the account, or you must provide a password here. + type: str update_password: description: - C(always) will update passwords if they differ. @@ -74,6 +78,7 @@ options: - Note that C(always) will always report an Ansible status of 'changed' because we cannot determine whether the new password differs from the old password. + type: str choices: [ always, on_create ] default: always password_expired: @@ -96,63 +101,77 @@ options: firstname: description: - Configures the user's first name (given name). + type: str surname: description: - Configures the user's last name (surname). + type: str company: description: - Configures the user's company name. + type: str upn: description: - Configures the User Principal Name (UPN) for the account. - This is not required, but is best practice to configure for modern versions of Active Directory. - The format is C(@). + type: str email: description: - Configures the user's email address. - This is a record in AD and does not do anything to configure any email servers or systems. + type: str street: description: - Configures the user's street address. + type: str city: description: - Configures the user's city. + type: str state_province: description: - Configures the user's state or province. + type: str postal_code: description: - Configures the user's postal code / zip code. + type: str country: description: - Configures the user's country code. - Note that this is a two-character ISO 3166 code. + type: str path: description: - Container or OU for the new user; if you do not specify this, the user will be placed in the default container for users in the domain. - Setting the path is only available when a new user is created; if you specify a path on an existing user, the user's path will not - be updated - you must delete (e.g., state=absent) the user and + be updated - you must delete (e.g., C(state=absent)) the user and then re-add the user with the appropriate path. + type: str attributes: description: - A dict of custom LDAP attributes to set on the user. - This can be used to set custom attributes that are not exposed as module parameters, e.g. C(telephoneNumber). - See the examples on how to format this parameter. + type: str version_added: '2.5' domain_username: description: - The username to use when interacting with AD. - If this is not set then the user Ansible used to log in with will be used instead when using CredSSP or Kerberos with credential delegation. + type: str version_added: '2.5' domain_password: description: - The password for I(username). + type: str version_added: '2.5' domain_server: description: @@ -160,6 +179,7 @@ options: - Can be in the form of an FQDN or NetBIOS name. - If not specified then the value is based on the domain of the computer running PowerShell. + type: str version_added: '2.5' notes: - Works with Windows 2012R2 and newer. diff --git a/lib/ansible/modules/windows/win_dotnet_ngen.py b/lib/ansible/modules/windows/win_dotnet_ngen.py index 0faccdc234d..ae8f3799c35 100644 --- a/lib/ansible/modules/windows/win_dotnet_ngen.py +++ b/lib/ansible/modules/windows/win_dotnet_ngen.py @@ -21,17 +21,17 @@ description: - This happens via scheduled task, usually at some inopportune time. - This module allows you to run this task on your own schedule, so you incur the CPU hit at some more convenient and controlled time. - U(http://blogs.msdn.com/b/dotnet/archive/2013/08/06/wondering-why-mscorsvw-exe-has-high-cpu-usage-you-can-speed-it-up.aspx) +options: {} notes: - There are in fact two scheduled tasks for ngen but they have no triggers so aren't a problem. - There's no way to test if they've been completed. - The stdout is quite likely to be several megabytes. author: - Peter Mounce (@petemounce) -options: {} ''' EXAMPLES = r''' -- name: run ngen tasks +- name: Run ngen tasks win_dotnet_ngen: ''' diff --git a/lib/ansible/modules/windows/win_dsc.py b/lib/ansible/modules/windows/win_dsc.py index e4efe56470a..966d0928400 100644 --- a/lib/ansible/modules/windows/win_dsc.py +++ b/lib/ansible/modules/windows/win_dsc.py @@ -25,6 +25,7 @@ options: description: - The name of the DSC Resource to use. - Must be accessible to PowerShell using any of the default paths. + type: str required: yes module_version: description: @@ -34,6 +35,7 @@ options: containing the DSC resource. - If not specified, the module will follow standard PowerShell convention and use the highest version available. + type: str default: latest free_form: description: @@ -52,6 +54,7 @@ options: provided but a comma separated string also work. Use a list where possible as no escaping is required and it works with more complex types list C(CimInstance[]). + type: str required: true notes: - By default there are a few builtin resources that come with PowerShell 5.0, @@ -142,9 +145,9 @@ reboot_required: the machine requires a reboot for the invoked changes to take effect. returned: always type: bool - sample: True + sample: true message: - description: any error message from invoking the DSC resource + description: Any error message from invoking the DSC resource. returned: error type: str sample: Multiple DSC modules found with resource name xyz diff --git a/lib/ansible/modules/windows/win_environment.py b/lib/ansible/modules/windows/win_environment.py index f100feeb12c..b3214f89adf 100644 --- a/lib/ansible/modules/windows/win_environment.py +++ b/lib/ansible/modules/windows/win_environment.py @@ -21,25 +21,29 @@ options: description: - Set to C(present) to ensure environment variable is set. - Set to C(absent) to ensure it is removed. + type: str choices: [ absent, present ] default: present name: description: - The name of the environment variable. + type: str required: yes value: description: - The value to store in the environment variable. - Must be set when C(state=present) and cannot be an empty string. - Can be omitted for C(state=absent). + type: str level: description: - The level at which to set the environment variable. - Use C(machine) to set for all users. - Use C(user) to set for the current user that ansible is connected as. - Use C(process) to set for the current process. Probably not that useful. - choices: [ machine, user, process ] + type: str required: yes + choices: [ machine, process, user ] notes: - This module is best-suited for setting the entire value of an environment variable. For safe element-based management of diff --git a/lib/ansible/modules/windows/win_eventlog.py b/lib/ansible/modules/windows/win_eventlog.py index 940c6861470..85cb9487017 100644 --- a/lib/ansible/modules/windows/win_eventlog.py +++ b/lib/ansible/modules/windows/win_eventlog.py @@ -24,6 +24,7 @@ options: name: description: - Name of the event log to manage. + type: str required: yes state: description: @@ -31,6 +32,7 @@ options: - When C(sources) is populated, state is checked for sources. - When C(sources) is not populated, state is checked for the specified log itself. - If C(state) is C(clear), event log entries are cleared for the target log. + type: str choices: [ absent, clear, present ] default: present sources: @@ -56,16 +58,15 @@ options: - The maximum size of the event log. - Value must be between 64KB and 4GB, and divisible by 64KB. - Size can be specified in KB, MB or GB (e.g. 128KB, 16MB, 2.5GB). + type: str overflow_action: description: - The action for the log to take once it reaches its maximum size. - - For C(OverwriteOlder), new log entries overwrite those older than the C(retention_days) value. - - For C(OverwriteAsNeeded), each new entry overwrites the oldest entry. - For C(DoNotOverwrite), all existing entries are kept and new entries are not retained. - choices: - - OverwriteOlder - - OverwriteAsNeeded - - DoNotOverwrite + - For C(OverwriteAsNeeded), each new entry overwrites the oldest entry. + - For C(OverwriteOlder), new log entries overwrite those older than the C(retention_days) value. + type: str + choices: [ DoNotOverwrite, OverwriteAsNeeded, OverwriteOlder ] retention_days: description: - The minimum number of days event entries must remain in the log. diff --git a/lib/ansible/modules/windows/win_feature.py b/lib/ansible/modules/windows/win_feature.py index 52ee1f6f585..773538dcd53 100644 --- a/lib/ansible/modules/windows/win_feature.py +++ b/lib/ansible/modules/windows/win_feature.py @@ -12,43 +12,45 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} - DOCUMENTATION = r''' --- module: win_feature version_added: "1.7" short_description: Installs and uninstalls Windows Features on Windows Server description: - - Installs or uninstalls Windows Roles or Features on Windows Server. This module uses the Add/Remove-WindowsFeature Cmdlets on Windows 2008 R2 - and Install/Uninstall-WindowsFeature Cmdlets on Windows 2012, which are not available on client os machines. + - Installs or uninstalls Windows Roles or Features on Windows Server. + - This module uses the Add/Remove-WindowsFeature Cmdlets on Windows 2008 R2 + and Install/Uninstall-WindowsFeature Cmdlets on Windows 2012, which are not available on client os machines. options: name: description: - Names of roles or features to install as a single feature or a comma-separated list of features. - To list all available features use the PowerShell command C(Get-WindowsFeature). - required: yes type: list + required: yes state: description: - State of the features or roles on the system. + type: str choices: [ absent, present ] default: present include_sub_features: description: - Adds all subfeatures of the specified feature. type: bool - default: 'no' + default: no include_management_tools: description: - Adds the corresponding management tools to the specified feature. - Not supported in Windows 2008 R2 and will be ignored. type: bool - default: 'no' + default: no source: description: - Specify a source to install the feature from. - Not supported in Windows 2008 R2 and will be ignored. - Can either be C({driveletter}:\sources\sxs) or C(\\{IP}\share\sources\sxs). + type: str version_added: "2.1" seealso: - module: win_chocolatey @@ -85,62 +87,62 @@ EXAMPLES = r''' include_management_tools: yes register: win_feature -- name: reboot if installing Web-Server feature requires it +- name: Reboot if installing Web-Server feature requires it win_reboot: when: win_feature.reboot_required ''' RETURN = r''' exitcode: - description: The stringified exit code from the feature installation/removal command + description: The stringified exit code from the feature installation/removal command. returned: always type: str sample: Success feature_result: - description: List of features that were installed or removed + description: List of features that were installed or removed. returned: success type: complex sample: contains: display_name: - description: Feature display name + description: Feature display name. returned: always type: str sample: "Telnet Client" id: - description: A list of KB article IDs that apply to the update + description: A list of KB article IDs that apply to the update. returned: always type: int sample: 44 message: - description: Any messages returned from the feature subsystem that occurred during installation or removal of this feature + description: Any messages returned from the feature subsystem that occurred during installation or removal of this feature. returned: always type: list of strings sample: [] reboot_required: - description: True when the target server requires a reboot as a result of installing or removing this feature + description: True when the target server requires a reboot as a result of installing or removing this feature. returned: always type: bool - sample: True + sample: true restart_needed: description: DEPRECATED in Ansible 2.4 (refer to C(reboot_required) instead). True when the target server requires a reboot as a - result of installing or removing this feature + result of installing or removing this feature. returned: always type: bool - sample: True + sample: true skip_reason: - description: The reason a feature installation or removal was skipped + description: The reason a feature installation or removal was skipped. returned: always type: str sample: NotSkipped success: - description: If the feature installation or removal was successful + description: If the feature installation or removal was successful. returned: always type: bool - sample: True + sample: true reboot_required: - description: True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot) + description: True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot). returned: success type: bool - sample: True + sample: true ''' diff --git a/lib/ansible/modules/windows/win_file.py b/lib/ansible/modules/windows/win_file.py index d42696c6847..915980fdf94 100644 --- a/lib/ansible/modules/windows/win_file.py +++ b/lib/ansible/modules/windows/win_file.py @@ -35,9 +35,8 @@ options: - If C(touch), an empty file will be created if the C(path) does not exist, while an existing file or directory will receive updated file access and modification times (similar to the way C(touch) works from the command line). + type: str choices: [ absent, directory, file, touch ] -notes: - - For non-Windows targets, use the M(file) module instead. seealso: - module: assemble - module: copy diff --git a/lib/ansible/modules/windows/win_file_version.py b/lib/ansible/modules/windows/win_file_version.py index effa7152938..390927821bf 100644 --- a/lib/ansible/modules/windows/win_file_version.py +++ b/lib/ansible/modules/windows/win_file_version.py @@ -22,8 +22,8 @@ options: description: - File to get version. - Always provide absolute path. - required: yes type: path + required: yes seealso: - module: win_file author: @@ -41,37 +41,37 @@ EXAMPLES = r''' ''' RETURN = r''' -win_file_version.path: +path: description: file path returned: always type: str -win_file_version.file_version: - description: file version number. +file_version: + description: File version number.. returned: no error type: str -win_file_version.product_version: - description: the version of the product this file is distributed with. +product_version: + description: The version of the product this file is distributed with. returned: no error type: str -win_file_version.file_major_part: +file_major_part: description: the major part of the version number. returned: no error type: str -win_file_version.file_minor_part: +file_minor_part: description: the minor part of the version number of the file. returned: no error type: str -win_file_version.file_build_part: +file_build_part: description: build number of the file. returned: no error type: str -win_file_version.file_private_part: +file_private_part: description: file private part number. returned: no error type: str diff --git a/lib/ansible/modules/windows/win_find.py b/lib/ansible/modules/windows/win_find.py index 385ee6f661f..5954891ff46 100644 --- a/lib/ansible/modules/windows/win_find.py +++ b/lib/ansible/modules/windows/win_find.py @@ -24,24 +24,30 @@ options: age: description: - Select files or folders whose age is equal to or greater than - the specified time. Use a negative age to find files equal to or - less than the specified time. You can choose seconds, minutes, - hours, days or weeks by specifying the first letter of an of + the specified time. + - Use a negative age to find files equal to or less than + the specified time. + - You can choose seconds, minutes, hours, days or weeks + by specifying the first letter of an of those words (e.g., "2s", "10d", 1w"). + type: str age_stamp: description: - - Choose the file property against which we compare C(age). The - default attribute we compare with is the last modification time. + - Choose the file property against which we compare C(age). + - The default attribute we compare with is the last modification time. + type: str choices: [ atime, ctime, mtime ] default: mtime checksum_algorithm: description: - - Algorithm to determine the checksum of a file. Will throw an error - if the host is unable to use specified algorithm. + - Algorithm to determine the checksum of a file. + - Will throw an error if the host is unable to use specified algorithm. + type: str choices: [ md5, sha1, sha256, sha384, sha512 ] default: sha1 file_type: description: Type of file to search for. + type: str choices: [ directory, file ] default: file follow: @@ -49,47 +55,47 @@ options: - Set this to C(yes) to follow symlinks in the path. - This needs to be used in conjunction with C(recurse). type: bool - default: 'no' + default: no get_checksum: description: - Whether to return a checksum of the file in the return info (default sha1), use C(checksum_algorithm) to change from the default. type: bool - default: 'yes' + default: yes hidden: description: Set this to include hidden files or folders. type: bool - default: 'no' + default: no paths: description: - List of paths of directories to search for files or folders in. - This can be supplied as a single path or a list of paths. + - This can be supplied as a single path or a list of paths. + type: list required: yes patterns: description: - - One or more (powershell or regex) patterns to compare filenames - with. The type of pattern matching is controlled by C(use_regex) - option. The patterns retrict the list of files or folders to be - returned based on the filenames. For a file to be matched it - only has to match with one pattern in a list provided. + - One or more (powershell or regex) patterns to compare filenames with. + - The type of pattern matching is controlled by C(use_regex) option. + - The patterns retrict the list of files or folders to be returned based on the filenames. + - For a file to be matched it only has to match with one pattern in a list provided. + type: list recurse: description: - - Will recursively descend into the directory looking for files - or folders. + - Will recursively descend into the directory looking for files or folders. type: bool - default: 'no' + default: no size: description: - - Select files or folders whose size is equal to or greater than - the specified size. Use a negative value to find files equal to - or less than the specified size. You can specify the size with - a suffix of the byte type i.e. kilo = k, mega = m... Size is not - evaluated for symbolic links. + - Select files or folders whose size is equal to or greater than the specified size. + - Use a negative value to find files equal to or less than the specified size. + - You can specify the size with a suffix of the byte type i.e. kilo = k, mega = m... + - Size is not evaluated for symbolic links. + type: str use_regex: description: - Will set patterns to run as a regex check if set to C(yes). type: bool - default: 'no' + default: no author: - Jordan Borean (@jborean93) ''' @@ -198,102 +204,102 @@ EXAMPLES = r''' RETURN = r''' examined: - description: The number of files/folders that was checked + description: The number of files/folders that was checked. returned: always type: int sample: 10 matched: - description: The number of files/folders that match the criteria + description: The number of files/folders that match the criteria. returned: always type: int sample: 2 files: - description: Information on the files/folders that match the criteria returned as a list of dictionary elements for each file matched + description: Information on the files/folders that match the criteria returned as a list of dictionary elements for each file matched. returned: success type: complex contains: attributes: - description: attributes of the file at path in raw form + description: attributes of the file at path in raw form. returned: success, path exists type: str sample: "Archive, Hidden" checksum: - description: The checksum of a file based on checksum_algorithm specified + description: The checksum of a file based on checksum_algorithm specified. returned: success, path exists, path is a file, get_checksum == True type: str sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 creationtime: - description: the create time of the file represented in seconds since epoch + description: The create time of the file represented in seconds since epoch. returned: success, path exists type: float sample: 1477984205.15 extension: - description: the extension of the file at path + description: The extension of the file at path. returned: success, path exists, path is a file type: str sample: ".ps1" isarchive: - description: if the path is ready for archiving or not + description: If the path is ready for archiving or not. returned: success, path exists type: bool - sample: True + sample: true isdir: - description: if the path is a directory or not + description: If the path is a directory or not. returned: success, path exists type: bool - sample: True + sample: true ishidden: - description: if the path is hidden or not + description: If the path is hidden or not. returned: success, path exists type: bool - sample: True + sample: true islnk: - description: if the path is a symbolic link or junction or not + description: If the path is a symbolic link or junction or not. returned: success, path exists type: bool - sample: True + sample: true isreadonly: - description: if the path is read only or not + description: If the path is read only or not. returned: success, path exists type: bool - sample: True + sample: true isshared: - description: if the path is shared or not + description: If the path is shared or not. returned: success, path exists type: bool - sample: True + sample: true lastaccesstime: - description: the last access time of the file represented in seconds since epoch + description: The last access time of the file represented in seconds since epoch. returned: success, path exists type: float sample: 1477984205.15 lastwritetime: - description: the last modification time of the file represented in seconds since epoch + description: The last modification time of the file represented in seconds since epoch. returned: success, path exists type: float sample: 1477984205.15 lnk_source: - description: the target of the symbolic link, will return null if not a link or the link is broken + description: The target of the symbolic link, will return null if not a link or the link is broken. return: success, path exists, path is a symbolic link type: str sample: C:\temp owner: - description: the owner of the file + description: The owner of the file. returned: success, path exists type: str sample: BUILTIN\Administrators path: - description: the full absolute path to the file + description: The full absolute path to the file. returned: success, path exists type: str sample: BUILTIN\Administrators sharename: - description: the name of share if folder is shared + description: The name of share if folder is shared. returned: success, path exists, path is a directory and isshared == True type: str sample: file-share size: - description: the size in bytes of a file or folder + description: The size in bytes of a file or folder. returned: success, path exists, path is not a link type: int sample: 1024 diff --git a/lib/ansible/modules/windows/win_firewall.py b/lib/ansible/modules/windows/win_firewall.py index a851366d75b..26becafb50a 100644 --- a/lib/ansible/modules/windows/win_firewall.py +++ b/lib/ansible/modules/windows/win_firewall.py @@ -25,17 +25,13 @@ options: description: - Specify one or more profiles to change. type: list - choices: - - Domain - - Private - - Public - default: [Domain, Private, Public] + choices: [ Domain, Private, Public ] + default: [ Domain, Private, Public ] state: description: - Set state of firewall for given profile. - choices: - - enabled - - disabled + type: str + choices: [ disabled, enabled ] seealso: - module: win_firewall_rule author: @@ -62,17 +58,17 @@ EXAMPLES = r''' RETURN = r''' enabled: - description: current firewall status for chosen profile (after any potential change) + description: Current firewall status for chosen profile (after any potential change). returned: always type: bool sample: true profiles: - description: chosen profile + description: Chosen profile. returned: always type: str sample: Domain state: - description: desired state of the given firewall profile(s) + description: Desired state of the given firewall profile(s). returned: always type: list sample: enabled diff --git a/lib/ansible/modules/windows/win_firewall_rule.py b/lib/ansible/modules/windows/win_firewall_rule.py index 3a6295f4f07..563fbd25a61 100644 --- a/lib/ansible/modules/windows/win_firewall_rule.py +++ b/lib/ansible/modules/windows/win_firewall_rule.py @@ -19,55 +19,67 @@ description: options: enabled: description: - - Is this firewall rule enabled or disabled. + - Whether this firewall rule is enabled or disabled. type: bool - default: 'yes' + default: yes aliases: [ enable ] state: description: - Should this rule be added or removed. + type: str choices: [ absent, present ] default: present name: description: - - The rules name + - The rules name. + type: str required: yes direction: description: - - Is this rule for inbound or outbound traffic. + - Whether this rule is for inbound or outbound traffic. + type: str required: yes choices: [ in, out ] action: description: - What to do with the items this rule is for. + type: str required: yes choices: [ allow, block ] description: description: - Description for the firewall rule. + type: str localip: description: - The local ip address this rule applies to. + type: str default: any remoteip: description: - The remote ip address/range this rule applies to. + type: str default: any localport: description: - The local port this rule applies to. + type: str remoteport: description: - The remote port this rule applies to. + type: str program: description: - The program this rule applies to. + type: str service: description: - The service this rule applies to. + type: str protocol: description: - The protocol this rule applies to. + type: str default: any profiles: description: @@ -78,10 +90,10 @@ options: force: description: - Replace any existing rule by removing it first. - - This is no longer required in 2.4 as rules no longer need replacing when being modified. - - DEPRECATED in 2.4 and will be removed in 2.9. + - This is no longer required in Ansible 2.4 as rules no longer need replacing when being modified. + - DEPRECATED in Ansible 2.4 and will be removed in Ansible 2.9. type: bool - default: 'no' + default: no seealso: - module: win_firewall author: diff --git a/lib/ansible/modules/windows/win_get_url.py b/lib/ansible/modules/windows/win_get_url.py index ebe558ce80e..f15fff8c6ff 100644 --- a/lib/ansible/modules/windows/win_get_url.py +++ b/lib/ansible/modules/windows/win_get_url.py @@ -17,21 +17,21 @@ module: win_get_url version_added: "1.7" short_description: Downloads file from HTTP, HTTPS, or FTP to node description: -- Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote - server I(must) have direct access to the remote resource. +- Downloads files from HTTP, HTTPS, or FTP to the remote server. +- The remote server I(must) have direct access to the remote resource. - For non-Windows targets, use the M(get_url) module instead. options: url: description: - The full URL of a file to download. - required: yes type: str + required: yes dest: description: - The location to save the file at the URL. - Be sure to include a filename and extension as appropriate. - required: yes type: path + required: yes force: description: - If C(yes), will always download the file. If C(no), will only @@ -41,7 +41,7 @@ options: time of the requested resource, so for this to work, the remote web server must support HEAD requests. type: bool - default: 'yes' + default: yes version_added: "2.0" headers: description: @@ -63,7 +63,7 @@ options: - If C(yes), will add a Basic authentication header on the initial request. - If C(no), will use Microsoft's WebClient to handle authentication. type: bool - default: 'no' + default: no version_added: "2.5" validate_certs: description: @@ -71,7 +71,7 @@ options: on personally controlled sites using self-signed certificates. - If C(skip_certificate_validation) was set, it overrides this option. type: bool - default: 'yes' + default: yes version_added: '2.4' proxy_url: description: @@ -93,7 +93,7 @@ options: - If C(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts. type: bool - default: 'yes' + default: yes version_added: '2.4' timeout: description: diff --git a/lib/ansible/modules/windows/win_group.py b/lib/ansible/modules/windows/win_group.py index a46ab5774c3..64c4152ec2a 100644 --- a/lib/ansible/modules/windows/win_group.py +++ b/lib/ansible/modules/windows/win_group.py @@ -23,17 +23,18 @@ options: name: description: - Name of the group. + type: str required: yes description: description: - Description of the group. + type: str state: description: - Create or remove the group. + type: str choices: [ absent, present ] default: present -notes: - - For non-Windows targets, please use the M(group) module instead. seealso: - module: group - module: win_domain_group diff --git a/lib/ansible/modules/windows/win_group_membership.py b/lib/ansible/modules/windows/win_group_membership.py index add62833c03..d6f97d0a344 100644 --- a/lib/ansible/modules/windows/win_group_membership.py +++ b/lib/ansible/modules/windows/win_group_membership.py @@ -20,6 +20,7 @@ options: name: description: - Name of the local group to manage membership on. + type: str required: yes members: description: @@ -29,11 +30,12 @@ options: - Accepts service users as NT AUTHORITY\username. - Accepts all local, domain and service user types as username, favoring domain lookups when in a domain. - required: yes type: list + required: yes state: description: - Desired state of the members in the group. + type: str choices: [ absent, present ] default: present seealso: diff --git a/lib/ansible/modules/windows/win_hostname.py b/lib/ansible/modules/windows/win_hostname.py index 23530c504a2..6602ad93796 100644 --- a/lib/ansible/modules/windows/win_hostname.py +++ b/lib/ansible/modules/windows/win_hostname.py @@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = r''' module: win_hostname version_added: "2.6" -short_description: Manages local Windows computer name. +short_description: Manages local Windows computer name description: - Manages local Windows computer name. - A reboot is required for the computer name to take effect. @@ -22,6 +22,7 @@ options: name: description: - The hostname to set for the computer. + type: str required: true seealso: - module: win_dns_client @@ -42,12 +43,12 @@ EXAMPLES = r''' RETURN = r''' old_name: - description: The original hostname that was set before it was changed + description: The original hostname that was set before it was changed. returned: always type: str sample: old_hostname reboot_required: - description: Whether a reboot is required to complete the hostname change + description: Whether a reboot is required to complete the hostname change. returned: always type: bool sample: true diff --git a/lib/ansible/modules/windows/win_hotfix.py b/lib/ansible/modules/windows/win_hotfix.py index dc831056bf6..ac3537ef653 100644 --- a/lib/ansible/modules/windows/win_hotfix.py +++ b/lib/ansible/modules/windows/win_hotfix.py @@ -27,6 +27,7 @@ options: - You can get the identifier by running 'Get-WindowsPackage -Online -PackagePath path-to-cab-in-msu' after expanding the msu file. + type: str hotfix_kb: description: - The name of the KB the hotfix relates to, see examples for details. @@ -35,11 +36,13 @@ options: against this value, if it does not match an error will occur. - Because DISM uses the identifier as a key and doesn't refer to a KB in all cases it is recommended to use C(hotfix_identifier) instead. + type: str state: description: - Whether to install or uninstall the hotfix. - When C(present), C(source) MUST be set. - When C(absent), C(hotfix_identifier) or C(hotfix_kb) MUST be set. + type: str default: present choices: [ absent, present ] source: @@ -64,14 +67,14 @@ author: ''' EXAMPLES = r''' -- name: install Windows ADK with DISM for Server 2008 R2 +- name: Install Windows ADK with DISM for Server 2008 R2 win_chocolatey: name: windows-adk version: 8.100.26866.0 state: present install_args: /features OptionId.DeploymentTools -- name: install hotfix without validating the KB and Identifier +- name: Install hotfix without validating the KB and Identifier win_hotfix: source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu state: present @@ -80,7 +83,7 @@ EXAMPLES = r''' - win_reboot: when: hotfix_install.reboot_required -- name: install hotfix validating KB +- name: Install hotfix validating KB win_hotfix: hotfix_kb: KB3172729 source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu @@ -90,7 +93,7 @@ EXAMPLES = r''' - win_reboot: when: hotfix_install.reboot_required -- name: install hotfix validating Identifier +- name: Install hotfix validating Identifier win_hotfix: hotfix_identifier: Package_for_KB3172729~31bf3856ad364e35~amd64~~6.3.1.0 source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu @@ -100,7 +103,7 @@ EXAMPLES = r''' - win_reboot: when: hotfix_install.reboot_required -- name: uninstall hotfix with Identifier +- name: Uninstall hotfix with Identifier win_hotfix: hotfix_identifier: Package_for_KB3172729~31bf3856ad364e35~amd64~~6.3.1.0 state: absent @@ -109,7 +112,7 @@ EXAMPLES = r''' - win_reboot: when: hotfix_uninstall.reboot_required -- name: uninstall hotfix with KB (not recommended) +- name: Uninstall hotfix with KB (not recommended) win_hotfix: hotfix_kb: KB3172729 state: absent @@ -135,5 +138,5 @@ reboot_required: finalise. returned: success type: str - sample: True + sample: true ''' diff --git a/lib/ansible/modules/windows/win_iis_virtualdirectory.py b/lib/ansible/modules/windows/win_iis_virtualdirectory.py index 14c3040865e..e5505e78aa4 100644 --- a/lib/ansible/modules/windows/win_iis_virtualdirectory.py +++ b/lib/ansible/modules/windows/win_iis_virtualdirectory.py @@ -19,23 +19,28 @@ options: name: description: - The name of the virtual directory to create or remove. + type: str required: yes state: description: - Whether to add or remove the specified virtual directory. + type: str choices: [ absent, present ] default: present site: description: - The site name under which the virtual directory is created or exists. + type: str required: yes application: description: - The application under which the virtual directory is created or exists. + type: str physical_path: description: - The physical path to the folder in which the new virtual directory is created. - The specified folder must already exist. + type: str seealso: - module: win_iis_webapplication - module: win_iis_webapppool diff --git a/lib/ansible/modules/windows/win_iis_webapplication.py b/lib/ansible/modules/windows/win_iis_webapplication.py index 5d289a11768..2ddc32b4ab5 100644 --- a/lib/ansible/modules/windows/win_iis_webapplication.py +++ b/lib/ansible/modules/windows/win_iis_webapplication.py @@ -19,23 +19,28 @@ options: name: description: - Name of the web application. + type: str required: yes site: description: - Name of the site on which the application is created. + type: str required: yes state: description: - State of the web application. + type: str choices: [ absent, present ] default: present physical_path: description: - The physical path on the remote host to use for the new application. - The specified folder must already exist. + type: str application_pool: description: - The application pool in which the new site executes. + type: str seealso: - module: win_iis_virtualdirectory - module: win_iis_webapppool @@ -56,12 +61,12 @@ EXAMPLES = r''' RETURN = r''' application_pool: - description: The used/implemented application_pool value + description: The used/implemented application_pool value. returned: success type: str sample: DefaultAppPool physical_path: - description: The used/implemented physical_path value + description: The used/implemented physical_path value. returned: success type: str sample: C:\apps\acme\api diff --git a/lib/ansible/modules/windows/win_iis_webapppool.py b/lib/ansible/modules/windows/win_iis_webapppool.py index 557eb7cdd02..e5cf1110333 100644 --- a/lib/ansible/modules/windows/win_iis_webapppool.py +++ b/lib/ansible/modules/windows/win_iis_webapppool.py @@ -39,10 +39,9 @@ options: name: description: - Name of the application pool. + type: str required: yes state: - choices: [ absent, present, restarted, started, stopped ] - default: present description: - The state of the application pool. - If C(absent) will ensure the app pool is removed. @@ -51,6 +50,9 @@ options: is never idempotent. - If C(started) will ensure the app pool exists and is started. - If C(stopped) will ensure the app pool exists and is stopped. + type: str + choices: [ absent, present, restarted, started, stopped ] + default: present seealso: - module: win_iis_virtualdirectory - module: win_iis_webapplication @@ -62,34 +64,34 @@ author: ''' EXAMPLES = r''' -- name: return information about an existing application pool +- name: Return information about an existing application pool win_iis_webapppool: name: DefaultAppPool state: present -- name: create a new application pool in 'Started' state +- name: Create a new application pool in 'Started' state win_iis_webapppool: name: AppPool state: started -- name: stop an application pool +- name: Stop an application pool win_iis_webapppool: name: AppPool state: stopped -- name: restart an application pool (non-idempotent) +- name: Restart an application pool (non-idempotent) win_iis_webapppool: name: AppPool state: restart -- name: change application pool attributes using new dict style +- name: Change application pool attributes using new dict style win_iis_webapppool: name: AppPool attributes: managedRuntimeVersion: v4.0 autoStart: no -- name: creates an application pool, sets attributes and starts it +- name: Creates an application pool, sets attributes and starts it win_iis_webapppool: name: AnotherAppPool state: started @@ -99,7 +101,7 @@ EXAMPLES = r''' # In the below example we are setting attributes in child element processModel # https://www.iis.net/configreference/system.applicationhost/applicationpools/add/processmodel -- name: manage child element and set identity of application pool +- name: Manage child element and set identity of application pool win_iis_webapppool: name: IdentitiyAppPool state: started @@ -108,9 +110,9 @@ EXAMPLES = r''' processModel.identityType: SpecificUser processModel.userName: '{{ansible_user}}' processModel.password: '{{ansible_password}}' - processModel.loadUserProfile: True + processModel.loadUserProfile: true -- name: manage a timespan attribute +- name: Manage a timespan attribute win_iis_webapppool: name: TimespanAppPool state: started diff --git a/lib/ansible/modules/windows/win_iis_webbinding.py b/lib/ansible/modules/windows/win_iis_webbinding.py index 7063eda8916..8fcb00c8c54 100644 --- a/lib/ansible/modules/windows/win_iis_webbinding.py +++ b/lib/ansible/modules/windows/win_iis_webbinding.py @@ -20,35 +20,43 @@ options: name: description: - Names of web site. + type: str required: yes aliases: [ website ] state: description: - State of the binding. + type: str choices: [ absent, present ] default: present port: description: - The port to bind to / use for the new site. + type: str default: 80 ip: description: - The IP address to bind to / use for the new site. + type: str default: '*' host_header: description: - The host header to bind to / use for the new site. - If you are creating/removing a catch-all binding, omit this parameter rather than defining it as '*'. + type: str protocol: description: - The protocol to be used for the Web binding (usually HTTP, HTTPS, or FTP). + type: str default: http certificate_hash: description: - Certificate hash (thumbprint) for the SSL binding. The certificate hash is the unique identifier for the certificate. + type: str certificate_store_name: description: - Name of the certificate store where the certificate for the binding is located. + type: str default: my ssl_flags: description: @@ -56,6 +64,7 @@ options: - Primarily used for enabling and disabling server name indication (SNI). - Set to c(0) to disable SNI. - Set to c(1) to enable SNI. + type: str version_added: "2.5" seealso: - module: win_iis_virtualdirectory diff --git a/lib/ansible/modules/windows/win_iis_website.py b/lib/ansible/modules/windows/win_iis_website.py index 3dce64f40c4..c059b4171c8 100644 --- a/lib/ansible/modules/windows/win_iis_website.py +++ b/lib/ansible/modules/windows/win_iis_website.py @@ -19,38 +19,48 @@ options: name: description: - Names of web site. + type: str required: yes site_id: description: - Explicitly set the IIS numeric ID for a site. - Note that this value cannot be changed after the website has been created. + type: str version_added: "2.1" state: description: - State of the web site + type: str choices: [ absent, started, stopped, restarted ] physical_path: description: - The physical path on the remote host to use for the new site. - The specified folder must already exist. + type: str application_pool: description: - The application pool in which the new site executes. + type: str port: description: - The port to bind to / use for the new site. + type: int ip: description: - The IP address to bind to / use for the new site. + type: str hostname: description: - The host header to bind to / use for the new site. + type: str ssl: description: - Enables HTTPS binding on the site.. + type: str parameters: description: - Custom site Parameters from string where properties are separated by a pipe and property name/values by colon Ex. "foo:1|bar:2" + type: str seealso: - module: win_iis_virtualdirectory - module: win_iis_webapplication diff --git a/lib/ansible/modules/windows/win_lineinfile.py b/lib/ansible/modules/windows/win_lineinfile.py index 731ba2ae2f3..2cf7d8f1c81 100644 --- a/lib/ansible/modules/windows/win_lineinfile.py +++ b/lib/ansible/modules/windows/win_lineinfile.py @@ -20,9 +20,9 @@ options: description: - The path of the file to modify. - Note that the Windows path delimiter C(\) must be escaped as C(\\) when the line is double quoted. - - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). - required: yes + - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name). type: path + required: yes aliases: [ dest, destfile, name ] regexp: description: @@ -32,6 +32,7 @@ options: state: description: - Whether the line should be there or not. + type: str choices: [ absent, present ] default: present line: @@ -40,6 +41,7 @@ options: expanded with the C(regexp) capture groups if the regexp matches. - Be aware that the line is processed first on the controller and thus is dependent on yaml quoting rules. Any double quoted line will have control characters, such as '\r\n', expanded. To print such characters literally, use single or no quotes. + type: str backrefs: description: - Used with C(state=present). If set, line can contain backreferences (both positional and named) that will get populated if the C(regexp) @@ -47,12 +49,13 @@ options: doesn't match anywhere in the file, the file will be left unchanged. - If the C(regexp) does match, the last matching line will be replaced by the expanded line parameter. type: bool - default: 'no' + default: no insertafter: description: - Used with C(state=present). If specified, the line will be inserted after the last match of specified regular expression. A special value is available; C(EOF) for inserting the line at the end of the file. - If specified regular expression has no matches, EOF will be used instead. May not be used with C(backrefs). + type: str choices: [ EOF, '*regex*' ] default: EOF insertbefore: @@ -60,21 +63,23 @@ options: - Used with C(state=present). If specified, the line will be inserted before the last match of specified regular expression. A value is available; C(BOF) for inserting the line at the beginning of the file. - If specified regular expression has no matches, the line will be inserted at the end of the file. May not be used with C(backrefs). + type: str choices: [ BOF, '*regex*' ] create: description: - Used with C(state=present). If specified, the file will be created if it does not already exist. By default it will fail if the file is missing. type: bool - default: 'no' + default: no backup: description: - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. type: bool - default: 'no' + default: no validate: description: - Validation to run before copying into place. Use %s in the command to indicate the current file to validate. - The command is passed securely so shell features like expansion and pipes won't work. + type: str encoding: description: - Specifies the encoding of the source text file to operate on (and thus what the output encoding will be). The default of C(auto) will cause @@ -83,11 +88,13 @@ options: see U(https://msdn.microsoft.com/en-us/library/system.text.encoding%28v=vs.110%29.aspx). - This is mostly useful with C(create=yes) if you want to create a new file with a specific encoding. If C(create=yes) is specified without a specific encoding, the default encoding (UTF-8, no BOM) will be used. + type: str default: auto newline: description: - Specifies the line separator style to use for the modified file. This defaults to the windows line separator (C(\r\n)). Note that the indicated line separator will be used for file output regardless of the original line separator that appears in the input file. + type: str choices: [ unix, windows ] default: windows notes: @@ -100,8 +107,8 @@ author: ''' EXAMPLES = r''' -# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' -- name: insert path without converting \r\n +# Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' +- name: Insert path without converting \r\n win_lineinfile: path: c:\file.txt line: c:\return\new @@ -133,21 +140,21 @@ EXAMPLES = r''' insertbefore: '^www.*80/tcp' line: '# port for http by default' -# Create file if it doesn't exist with a specific encoding -- win_lineinfile: +- name: Create file if it doesn't exist with a specific encoding + win_lineinfile: path: C:\Temp\utf16.txt create: yes encoding: utf-16 line: This is a utf-16 encoded file -# Add a line to a file and ensure the resulting file uses unix line separators -- win_lineinfile: +- name: Add a line to a file and ensure the resulting file uses unix line separators + win_lineinfile: path: C:\Temp\testfile.txt line: Line added to file newline: unix -# Update a line using backrefs -- win_lineinfile: +- name: Update a line using backrefs + win_lineinfile: path: C:\Temp\example.conf backrefs: yes regexp: '(^name=)' diff --git a/lib/ansible/modules/windows/win_mapped_drive.py b/lib/ansible/modules/windows/win_mapped_drive.py index be08b0b07e1..d8f09e85720 100644 --- a/lib/ansible/modules/windows/win_mapped_drive.py +++ b/lib/ansible/modules/windows/win_mapped_drive.py @@ -11,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} - DOCUMENTATION = r''' --- module: win_mapped_drive @@ -24,6 +23,7 @@ options: description: - The letter of the network path to map to. - This letter must not already be in use with Windows. + type: str required: yes password: description: @@ -31,6 +31,7 @@ options: connection. - This is never saved with a mapped drive, use the M(win_credential) module to persist a username and password for a host. + type: str path: description: - The UNC path to map the drive to. @@ -44,6 +45,7 @@ options: description: - If C(present) will ensure the mapped drive exists. - If C(absent) will ensure the mapped drive does not exist. + type: str choices: [ absent, present ] default: present username: @@ -55,6 +57,7 @@ options: custom credentials and become, or CredSSP cannot be used. - If become or CredSSP is used, any credentials saved with M(win_credential) will automatically be used instead. + type: str notes: - You cannot use this module to access a mapped drive in another Ansible task, drives mapped with this module are only accessible when logging in diff --git a/lib/ansible/modules/windows/win_msg.py b/lib/ansible/modules/windows/win_msg.py index 07883026e19..4f9ea959de6 100644 --- a/lib/ansible/modules/windows/win_msg.py +++ b/lib/ansible/modules/windows/win_msg.py @@ -22,6 +22,7 @@ options: to: description: - Who to send the message to. Can be a username, sessionname or sessionid. + type: str default: '*' display_seconds: description: @@ -39,6 +40,7 @@ options: description: - The text of the message to be displayed. - The message must be less than 256 characters. + type: str default: Hello world! notes: - This module must run on a windows host, so ensure your play targets windows @@ -72,7 +74,7 @@ display_seconds: type: str sample: 10 rc: - description: The return code of the API call + description: The return code of the API call. returned: always type: int sample: 0 diff --git a/lib/ansible/modules/windows/win_nssm.py b/lib/ansible/modules/windows/win_nssm.py index 51200dca02a..5631624430b 100644 --- a/lib/ansible/modules/windows/win_nssm.py +++ b/lib/ansible/modules/windows/win_nssm.py @@ -24,12 +24,14 @@ options: name: description: - Name of the service to operate on. + type: str required: true state: description: - State of the service on the system. - Note that NSSM actions like "pause", "continue", "rotate" do not fit the declarative style of ansible, so these should be implemented via the ansible command module. + type: str choices: [ absent, present, started, stopped, restarted ] default: started application: @@ -44,33 +46,41 @@ options: stdout_file: description: - Path to receive output. + type: str stderr_file: description: - Path to receive error output. + type: str app_parameters: description: - A string representing a dictionary of parameters to be passed to the application when it starts. - Use either this or C(app_parameters_free_form), not both. + type: str app_parameters_free_form: - version_added: "2.3.0" description: - Single string of parameters to be passed to the service. - Use either this or C(app_parameters), not both. + type: str + version_added: "2.3" dependencies: description: - Service dependencies that has to be started to trigger startup, separated by comma. + type: list user: description: - User to be used for service startup. + type: str password: description: - Password to be used for service startup. + type: str start_mode: description: - If C(auto) is selected, the service will start at bootup. - C(delayed) causes a delayed but automatic start after boot (added in version 2.5). - C(manual) means that the service will start only when another service needs it. - C(disabled) means that the service will stay off, regardless if it is needed or not. + type: str choices: [ auto, delayed, disabled, manual ] default: auto seealso: diff --git a/lib/ansible/modules/windows/win_owner.py b/lib/ansible/modules/windows/win_owner.py index 640bc5877d5..883c47ac088 100644 --- a/lib/ansible/modules/windows/win_owner.py +++ b/lib/ansible/modules/windows/win_owner.py @@ -14,22 +14,23 @@ module: win_owner version_added: "2.1" short_description: Set owner description: - - Set owner of files or directories + - Set owner of files or directories. options: path: description: - - Path to be used for changing owner - required: yes + - Path to be used for changing owner. type: path + required: yes user: description: - - Name to be used for changing owner + - Name to be used for changing owner. + type: str required: yes recurse: description: - - Indicates if the owner should be changed recursively + - Indicates if the owner should be changed recursively. type: bool - default: 'no' + default: no seealso: - module: win_file author: @@ -37,7 +38,7 @@ author: ''' EXAMPLES = r''' -- name: Change owner of Path +- name: Change owner of path win_owner: path: C:\apache user: apache diff --git a/lib/ansible/modules/windows/win_package.py b/lib/ansible/modules/windows/win_package.py index 3d83d7a2744..19db8895860 100644 --- a/lib/ansible/modules/windows/win_package.py +++ b/lib/ansible/modules/windows/win_package.py @@ -32,6 +32,7 @@ options: module will escape the arguments as necessary, it is recommended to use a string when dealing with MSI packages due to the unique escaping issues with msiexec. + type: str chdir: description: - Set the specified path as the current working directory before installing @@ -50,6 +51,7 @@ options: - Will check the existing of the service specified and use the result to determine whether the package is already installed. - You can use this in conjunction with C(product_id) and other C(creates_*). + type: str version_added: '2.4' creates_version: description: @@ -57,12 +59,13 @@ options: use the result to determine whether the package is already installed. - C(creates_path) MUST be set and is a file. - You can use this in conjunction with C(product_id) and other C(creates_*). + type: str version_added: '2.4' expected_return_code: description: - One or more return codes from the package installation that indicates success. - - Before Ansible 2.4 this was just 0 but since 2.4 this is both C(0) and + - Before Ansible 2.4 this was just 0 but since Ansible 2.4 this is both C(0) and C(3010). - A return code of C(3010) usually means that a reboot is required, the C(reboot_required) return value is set if the return code is C(3010). @@ -71,6 +74,7 @@ options: password: description: - The password for C(user_name), must be set when C(user_name) is. + type: str aliases: [ user_password ] path: description: @@ -85,6 +89,7 @@ options: - If C(state=present) then this value MUST be set. - If C(state=absent) then this value does not need to be set if C(product_id) is. + type: str product_id: description: - The product id of the installed packaged. @@ -98,12 +103,14 @@ options: - This SHOULD be set when the package is not an MSI, or the path is a url or a network share and credential delegation is not being used. The C(creates_*) options can be used instead but is not recommended. + type: str aliases: [ productid ] state: description: - Whether to install or uninstall the package. - The module uses C(product_id) and whether it exists at the registry path to see whether it needs to install or uninstall the package. + type: str choices: [ absent, present ] default: present aliases: [ ensure ] @@ -113,6 +120,7 @@ options: file share. - This is only needed if the WinRM transport is over an auth method that does not support credential delegation like Basic or NTLM. + type: str aliases: [ user_name ] validate_certs: description: @@ -120,10 +128,9 @@ options: used on personally controlled sites using self-signed certificates. - Before Ansible 2.4 this defaulted to C(no). type: bool - default: 'yes' + default: yes version_added: '2.4' notes: -- For non Windows targets, use the M(package) module instead. - When C(state=absent) and the product is an exe, the path may be different from what was used to install the package originally. If path is not set then the path used will be what is set under C(UninstallString) in the registry @@ -241,7 +248,7 @@ reboot_required: to true if the executable return code is 3010. returned: always type: bool - sample: True + sample: true stdout: description: The stdout stream of the package process. returned: failure during install or uninstall diff --git a/lib/ansible/modules/windows/win_pagefile.py b/lib/ansible/modules/windows/win_pagefile.py index 6cef5652ba0..af65d97772d 100644 --- a/lib/ansible/modules/windows/win_pagefile.py +++ b/lib/ansible/modules/windows/win_pagefile.py @@ -24,6 +24,7 @@ options: drive: description: - The drive of the pagefile. + type: str initial_size: description: - The initial size of the pagefile in megabytes. @@ -36,12 +37,12 @@ options: description: - Override the current pagefile on the drive. type: bool - default: 'yes' + default: yes system_managed: description: - Configures current pagefile to be managed by the system. type: bool - default: 'no' + default: no automatic: description: - Configures AutomaticManagedPagefile for the entire system. @@ -50,15 +51,16 @@ options: description: - Remove all pagefiles in the system, not including automatic managed. type: bool - default: 'no' + default: no test_path: description: - Use Test-Path on the drive to make sure the drive is accessible before creating the pagefile. type: bool - default: 'yes' + default: yes state: description: - State of the pagefile. + type: str choices: [ absent, present, query ] default: query notes: diff --git a/lib/ansible/modules/windows/win_partition.py b/lib/ansible/modules/windows/win_partition.py index b5143622c6a..c8a3febcf81 100644 --- a/lib/ansible/modules/windows/win_partition.py +++ b/lib/ansible/modules/windows/win_partition.py @@ -62,8 +62,8 @@ options: description: - Sets the partition offline. - Adding a mount point (such as a drive letter) will cause the partition to go online again. - required: no type: bool + required: no mbr_type: description: - Specify the partition's MBR type if the disk's partition style is MBR. diff --git a/lib/ansible/modules/windows/win_path.py b/lib/ansible/modules/windows/win_path.py index 1f20e0e4308..3117033b3e8 100644 --- a/lib/ansible/modules/windows/win_path.py +++ b/lib/ansible/modules/windows/win_path.py @@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: win_path version_added: "2.3" @@ -22,6 +22,7 @@ options: name: description: - Target path environment variable name. + type: str default: PATH elements: description: @@ -33,14 +34,17 @@ options: - New path elements are appended to the path, and existing path elements may be moved closer to the end to satisfy the requested ordering. - Paths are compared in a case-insensitive fashion, and trailing backslashes are ignored for comparison purposes. However, note that trailing backslashes in YAML require quotes. + type: list required: yes state: description: - Whether the path elements specified in C(elements) should be present or absent. + type: str choices: [ absent, present ] scope: description: - The level at which the environment variable specified by C(name) should be managed (either for the current user or global machine scope). + type: str choices: [ machine, user ] default: machine notes: @@ -51,7 +55,7 @@ notes: This means that the minority of windows applications which can have their environment changed without restarting will not be notified and therefore will need restarting to pick up new environment settings. - User level environment variables will require an interactive user to + - User level environment variables will require an interactive user to log out and in again before they become available. seealso: - module: win_environment diff --git a/lib/ansible/modules/windows/win_pester.py b/lib/ansible/modules/windows/win_pester.py index 25918dcec5b..5046bf9c216 100644 --- a/lib/ansible/modules/windows/win_pester.py +++ b/lib/ansible/modules/windows/win_pester.py @@ -24,6 +24,7 @@ options: description: - Path to a pester test file or a folder where tests can be found. - If the path is a folder, the module will consider all ps1 files as Pester tests. + type: str required: true version: description: @@ -32,19 +33,6 @@ author: - Erwan Quelin (@equelin) ''' -RETURN = r''' -pester_version: - description: Version of the pester module found on the remote host. - returned: always - type: str - sample: 4.3.1 -output: - description: Results of the Pester tests. - returned: success - type: list - sample: False -''' - EXAMPLES = r''' - name: Get facts setup: @@ -66,3 +54,16 @@ EXAMPLES = r''' path: C:\Pester\test01.test.ps1 version: 4.1.0 ''' + +RETURN = r''' +pester_version: + description: Version of the pester module found on the remote host. + returned: always + type: str + sample: 4.3.1 +output: + description: Results of the Pester tests. + returned: success + type: list + sample: false +''' diff --git a/lib/ansible/modules/windows/win_ping.py b/lib/ansible/modules/windows/win_ping.py index 7ca5cba68d4..6d35f379940 100644 --- a/lib/ansible/modules/windows/win_ping.py +++ b/lib/ansible/modules/windows/win_ping.py @@ -26,10 +26,8 @@ options: description: - Alternate data to return instead of 'pong'. - If this parameter is set to C(crash), the module will cause an exception. + type: str default: pong -notes: - - For non-Windows targets, use the M(ping) module instead. - - For Network targets, use the M(net_ping) module instead. seealso: - module: ping author: @@ -40,17 +38,17 @@ EXAMPLES = r''' # Test connectivity to a windows host # ansible winserver -m win_ping -# Example from an Ansible Playbook -- win_ping: +- name: Example from an Ansible Playbook + win_ping: -# Induce an exception to see what happens -- win_ping: +- name: Induce an exception to see what happens + win_ping: data: crash ''' -RETURN = ''' +RETURN = r''' ping: - description: value provided with the data parameter + description: Value provided with the data parameter. returned: success type: str sample: pong diff --git a/lib/ansible/modules/windows/win_power_plan.py b/lib/ansible/modules/windows/win_power_plan.py index 3ab5bcb3e24..054379c1dcf 100644 --- a/lib/ansible/modules/windows/win_power_plan.py +++ b/lib/ansible/modules/windows/win_power_plan.py @@ -8,7 +8,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: win_power_plan short_description: Changes the power plan of a Windows system @@ -22,14 +22,16 @@ requirements: options: name: description: - - String value that indicates the desired power plan. The power plan must already be - present on the system. Commonly there will be options for C(balanced) and C(high performance). + - String value that indicates the desired power plan. + - The power plan must already be present on the system. + - Commonly there will be options for C(balanced) and C(high performance). + type: str required: yes author: - Noah Sparks (@nwsparks) ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Change power plan to high performance win_power_plan: name: high performance @@ -37,17 +39,17 @@ EXAMPLES = ''' RETURN = r''' power_plan_name: - description: Value of the intended power plan + description: Value of the intended power plan. returned: always type: str sample: balanced power_plan_enabled: - description: State of the intended power plan + description: State of the intended power plan. returned: success type: bool - sample: True + sample: true all_available_plans: - description: The name and enabled state of all power plans + description: The name and enabled state of all power plans. returned: always type: dict sample: | diff --git a/lib/ansible/modules/windows/win_product_facts.ps1 b/lib/ansible/modules/windows/win_product_facts.ps1 index bde347f9186..6563bd92a00 100644 --- a/lib/ansible/modules/windows/win_product_facts.ps1 +++ b/lib/ansible/modules/windows/win_product_facts.ps1 @@ -1,6 +1,6 @@ #!powershell -# Copyright: (c) 2017, Dag Wieers (dagwieers) +# Copyright: (c) 2017, Dag Wieers (@dagwieers) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) #AnsibleRequires -CSharpUtil Ansible.Basic diff --git a/lib/ansible/modules/windows/win_product_facts.py b/lib/ansible/modules/windows/win_product_facts.py index 8f9a6a60a15..a54a8519f6d 100644 --- a/lib/ansible/modules/windows/win_product_facts.py +++ b/lib/ansible/modules/windows/win_product_facts.py @@ -1,14 +1,14 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# Copyright: (c) 2017, Dag Wieers (dagwieers) +# Copyright: (c) 2017, Dag Wieers (@dagwieers) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: win_product_facts short_description: Provides Windows product information (product id, product key) @@ -25,7 +25,7 @@ EXAMPLES = r''' win_product_facts: ''' -RETURN = ''' +RETURN = r''' ansible_facts: description: returned facts by this module returned: always diff --git a/lib/ansible/modules/windows/win_psexec.py b/lib/ansible/modules/windows/win_psexec.py index d46a2223ac2..d38af881479 100644 --- a/lib/ansible/modules/windows/win_psexec.py +++ b/lib/ansible/modules/windows/win_psexec.py @@ -14,14 +14,15 @@ module: win_psexec version_added: '2.3' short_description: Runs commands (remotely) as another (privileged) user description: -- Run commands (remotely) through the PsExec service -- Run commands as another (domain) user (with elevated privileges) +- Run commands (remotely) through the PsExec service. +- Run commands as another (domain) user (with elevated privileges). requirements: - Microsoft PsExec options: command: description: - The command line to run through PsExec (limited to 260 characters). + type: str required: yes executable: description: @@ -37,10 +38,12 @@ options: description: - The (remote) user to run the command as. - If not provided, the current user is used. + type: str password: description: - The password for the (remote) user to run the command as. - This is mandatory in order authenticate yourself. + type: str chdir: description: - Run the command from this (remote) directory. @@ -50,23 +53,23 @@ options: - Do not display the startup banner and copyright message. - This only works for specific versions of the PsExec binary. type: bool - default: 'no' + default: no version_added: '2.4' noprofile: description: - Run the command without loading the account's profile. type: bool - default: 'no' + default: no elevated: description: - Run the command with elevated privileges. type: bool - default: 'no' + default: no interactive: description: - Run the program so that it interacts with the desktop on the remote system. type: bool - default: 'no' + default: no session: description: - Specifies the session ID to use. @@ -78,22 +81,16 @@ options: description: - Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group). type: bool - default: 'no' + default: no system: description: - Run the remote command in the System account. type: bool - default: 'no' + default: no priority: description: - Used to run the command at a different priority. - choices: - - background - - low - - belownormal - - abovenormal - - high - - realtime + choices: [ abovenormal, background, belownormal, high, low, realtime ] timeout: description: - The connection timeout in seconds @@ -103,7 +100,7 @@ options: - Wait for the application to terminate. - Only use for non-interactive applications. type: bool - default: 'yes' + default: yes notes: - More information related to Microsoft PsExec is available from U(https://technet.microsoft.com/en-us/sysinternals/bb897553.aspx) @@ -153,17 +150,17 @@ cmd: type: str sample: psexec.exe -nobanner \\remote_server -u "DOMAIN\Administrator" -p "some_password" -accepteula E:\setup.exe rc: - description: The return code for the command + description: The return code for the command. returned: always type: int sample: 0 stdout: - description: The standard output from the command + description: The standard output from the command. returned: always type: str sample: Success. stderr: - description: The error output from the command + description: The error output from the command. returned: always type: str sample: Error 15 running E:\setup.exe diff --git a/lib/ansible/modules/windows/win_psmodule.py b/lib/ansible/modules/windows/win_psmodule.py index fa487338994..cbdc4093886 100644 --- a/lib/ansible/modules/windows/win_psmodule.py +++ b/lib/ansible/modules/windows/win_psmodule.py @@ -22,22 +22,26 @@ options: name: description: - Name of the powershell module that has to be installed. + type: str required: yes allow_clobber: description: - If C(yes) imports all commands, even if they have the same names as commands that already exists. Available only in Powershell 5.1 or higher. type: bool - default: 'no' + default: no repository: description: - Name of the custom repository to register or use. + type: str url: description: - URL of the custom repository to register. + type: str state: description: - If C(present) a new module is installed. - If C(absent) a module is removed. + type: str choices: [ absent, present ] default: present notes: @@ -48,7 +52,7 @@ author: - Daniele Lazzari (@dlazz) ''' -EXAMPLES = ''' +EXAMPLES = r''' --- - name: Add a powershell module win_psmodule: @@ -80,21 +84,21 @@ EXAMPLES = ''' state: absent ''' -RETURN = ''' +RETURN = r''' --- output: - description: a message describing the task result. + description: A message describing the task result. returned: always sample: "Module PowerShellCookbook installed" type: str nuget_changed: - description: true when Nuget package provider is installed + description: True when Nuget package provider is installed. returned: always type: bool - sample: True + sample: true repository_changed: - description: true when a custom repository is installed or removed + description: True when a custom repository is installed or removed. returned: always type: bool - sample: True + sample: true ''' diff --git a/lib/ansible/modules/windows/win_psrepository.py b/lib/ansible/modules/windows/win_psrepository.py index 24996e88f70..5887ce6299e 100644 --- a/lib/ansible/modules/windows/win_psrepository.py +++ b/lib/ansible/modules/windows/win_psrepository.py @@ -23,26 +23,30 @@ options: name: description: - Name of the repository to work with. + type: str required: yes source: description: - Specifies the URI for discovering and installing modules from this repository. - A URI can be a NuGet server feed (most common situation), HTTP, HTTPS, FTP or file location. + type: str state: description: - If C(present) a new repository is added or updated. - If C(absent) a repository is removed. + type: str choices: [ absent, present ] default: present installation_policy: description: - Sets the C(InstallationPolicy) of a repository. - Will default to C(trusted) when creating a new repository. + type: str choices: [ trusted, untrusted ] notes: - The PowerShellGet module (version 1.6.0 or newer) and the NuGet package provider (version 2.8.5.201 or newer) are required. - See the examples on how to update the NuGet package provider. - - You can't use C(win_psrepository) to re-register (add) removed PSGallery, use the command C(Register-PSRepository -Default) instead. + - You can not use C(win_psrepository) to re-register (add) removed PSGallery, use the command C(Register-PSRepository -Default) instead. seealso: - module: win_psmodule author: diff --git a/lib/ansible/modules/windows/win_rabbitmq_plugin.py b/lib/ansible/modules/windows/win_rabbitmq_plugin.py index 534d9443ad6..783559c5953 100644 --- a/lib/ansible/modules/windows/win_rabbitmq_plugin.py +++ b/lib/ansible/modules/windows/win_rabbitmq_plugin.py @@ -19,6 +19,7 @@ options: names: description: - Comma-separated list of plugin names. + type: str required: yes aliases: [ name ] new_only: @@ -26,15 +27,17 @@ options: - Only enable missing plugins. - Does not disable plugins that are not in the names list. type: bool - default: "no" + default: no state: description: - Specify if plugins are to be enabled or disabled. + type: str choices: [ disabled, enabled ] default: enabled prefix: description: - Specify a custom install prefix to a Rabbit. + type: str author: - Artem Zinenko (@ar7z1) ''' @@ -48,12 +51,12 @@ EXAMPLES = r''' RETURN = r''' enabled: - description: list of plugins enabled during task run + description: List of plugins enabled during task run. returned: always type: list sample: ["rabbitmq_management"] disabled: - description: list of plugins disabled during task run + description: List of plugins disabled during task run. returned: always type: list sample: ["rabbitmq_management"] diff --git a/lib/ansible/modules/windows/win_reboot.py b/lib/ansible/modules/windows/win_reboot.py index f98b90b6c67..f2d44e3e27d 100644 --- a/lib/ansible/modules/windows/win_reboot.py +++ b/lib/ansible/modules/windows/win_reboot.py @@ -13,6 +13,7 @@ module: win_reboot short_description: Reboot a windows machine description: - Reboot a Windows machine, wait for it to go down, come back up, and respond to commands. +- For non-Windows targets, use the M(reboot) module instead. version_added: '2.1' options: pre_reboot_delay: @@ -64,7 +65,6 @@ notes: - If a shutdown was already scheduled on the system, C(win_reboot) will abort the scheduled shutdown and enforce its own shutdown. - Beware that when C(win_reboot) returns, the Windows system may not have settled yet and some base services could be in limbo. This can result in unexpected behavior. Check the examples for ways to mitigate this. -- For non-Windows targets, use the M(reboot) module instead. seealso: - module: reboot author: @@ -109,7 +109,7 @@ EXAMPLES = r''' RETURN = r''' rebooted: - description: true if the machine was rebooted + description: True if the machine was rebooted. returned: always type: bool sample: true diff --git a/lib/ansible/modules/windows/win_reg_stat.py b/lib/ansible/modules/windows/win_reg_stat.py index 631f99b5283..fb88aca0afe 100644 --- a/lib/ansible/modules/windows/win_reg_stat.py +++ b/lib/ansible/modules/windows/win_reg_stat.py @@ -23,11 +23,13 @@ description: options: path: description: The full registry key path including the hive to search for. + type: str required: yes aliases: [ key ] name: description: - The registry property name to get information for, the return json will not include the sub_keys and properties entries for the I(key) specified. + type: str aliases: [ entry, value, property ] seealso: - module: win_regedit @@ -54,12 +56,12 @@ changed: description: Whether anything was changed. returned: always type: bool - sample: True + sample: true exists: description: States whether the registry key/property exists. returned: success and path/property exists type: bool - sample: True + sample: true properties: description: A dictionary containing all the properties and their values in the registry key. returned: success, path exists and property not specified diff --git a/lib/ansible/modules/windows/win_regedit.py b/lib/ansible/modules/windows/win_regedit.py index 03a3f34e9e2..ac7c2954c56 100644 --- a/lib/ansible/modules/windows/win_regedit.py +++ b/lib/ansible/modules/windows/win_regedit.py @@ -28,6 +28,7 @@ options: - Name of the registry path. - 'Should be in one of the following registry hives: HKCC, HKCR, HKCU, HKLM, HKU.' + type: str required: yes aliases: [ key ] name: @@ -35,6 +36,7 @@ options: - Name of the registry entry in the above C(path) parameters. - If not provided, or empty then the '(Default)' property for the key will be used. + type: str aliases: [ entry ] data: description: @@ -51,15 +53,18 @@ options: or a hex value. - Multistring values should be passed in as a list. - See the examples for more details on how to format this data. + type: str type: description: - The registry value data type. + type: str choices: [ binary, dword, expandstring, multistring, string, qword ] default: string aliases: [ datatype ] state: description: - The state of the registry entry. + type: str choices: [ absent, present ] default: present delete_key: @@ -68,7 +73,7 @@ options: - If C(no) then it will only clear out the '(Default)' property for that key. type: bool - default: 'yes' + default: yes version_added: '2.4' hive: description: @@ -193,13 +198,13 @@ EXAMPLES = r''' RETURN = r''' data_changed: - description: whether this invocation changed the data in the registry value + description: Whether this invocation changed the data in the registry value. returned: success type: bool - sample: False + sample: false data_type_changed: - description: whether this invocation changed the datatype of the registry value + description: Whether this invocation changed the datatype of the registry value. returned: success type: bool - sample: True + sample: true ''' diff --git a/lib/ansible/modules/windows/win_region.py b/lib/ansible/modules/windows/win_region.py index fc10200ef70..0c88102e896 100644 --- a/lib/ansible/modules/windows/win_region.py +++ b/lib/ansible/modules/windows/win_region.py @@ -23,21 +23,24 @@ options: - The location to set for the current user, see U(https://msdn.microsoft.com/en-us/library/dd374073.aspx) for a list of GeoIDs you can use and what location it relates to. - This needs to be set if C(format) or C(unicode_language) is not + - This needs to be set if C(format) or C(unicode_language) is not set. + type: str format: description: - The language format to set for the current user, see U(https://msdn.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx) - for a list of culture names to use. This needs to be set if - C(location) or C(unicode_language) is not set. + for a list of culture names to use. + - This needs to be set if C(location) or C(unicode_language) is not set. + type: str unicode_language: description: - The unicode language format to set for all users, see U(https://msdn.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx) - for a list of culture names to use. This needs to be set if - C(location) or C(format) is not set. After setting this + for a list of culture names to use. + - This needs to be set if C(location) or C(format) is not set. After setting this value a reboot is required for it to take effect. + type: str copy_settings: description: - This will copy the current format and location values to new user @@ -46,7 +49,7 @@ options: change. If this process runs then it will always result in a change. type: bool - default: 'no' + default: no seealso: - module: win_timezone author: @@ -54,28 +57,30 @@ author: ''' EXAMPLES = r''' -# Set the region format to English United States -- win_region: +- name: Set the region format to English United States + win_region: format: en-US -# Set the region format to English Australia and copy settings to new profiles -- win_region: +- name: Set the region format to English Australia and copy settings to new profiles + win_region: format: en-AU copy_settings: yes -# Set the unicode language to English Great Britain, reboot if required -- win_region: +- name: Set the location to United States + win_region: + location: 244 + +# Reboot when region settings change +- name: Set the unicode language to English Great Britain, reboot if required + win_region: unicode_language: en-GB register: result - win_reboot: when: result.restart_required -# Set the location to United States -- win_region: - location: 244 - -# Set format, location and unicode to English Australia and copy settings, reboot if required +# Reboot when format, location or unicode has changed +- name: Set format, location and unicode to English Australia and copy settings, reboot if required - win_region: location: 12 format: en-AU @@ -88,8 +93,8 @@ EXAMPLES = r''' RETURN = r''' restart_required: - description: Whether a reboot is required for the change to take effect + description: Whether a reboot is required for the change to take effect. returned: success type: bool - sample: True + sample: true ''' diff --git a/lib/ansible/modules/windows/win_regmerge.py b/lib/ansible/modules/windows/win_regmerge.py index d2c3546c5ca..98d7b6cc635 100644 --- a/lib/ansible/modules/windows/win_regmerge.py +++ b/lib/ansible/modules/windows/win_regmerge.py @@ -28,22 +28,23 @@ options: path: description: - The full path including file name to the registry file on the remote machine to be merged - required: yes type: path + required: yes compare_key: description: - The parent key to use when comparing the contents of the registry to the contents of the file. Needs to be in HKLM or HKCU part of registry. Use a PS-Drive style path for example HKLM:\SOFTWARE not HKEY_LOCAL_MACHINE\SOFTWARE If not supplied, or the registry key is not found, no comparison will be made, and the module will report changed. + type: str notes: - Organise your registry files so that they contain a single root registry key if you want to use the compare_to functionality. - This module does not force registry settings to be in the state + - This module does not force registry settings to be in the state described in the file. If registry settings have been modified externally the module will merge the contents of the file but continue to report differences on subsequent runs. - To force registry change, use M(win_regedit) with state=absent before - using M(win_regmerge). + - To force registry change, use M(win_regedit) with C(state=absent) before + using C(win_regmerge). seealso: - module: win_reg_stat - module: win_regedit diff --git a/lib/ansible/modules/windows/win_robocopy.py b/lib/ansible/modules/windows/win_robocopy.py index 941340216af..c30b94c64d4 100644 --- a/lib/ansible/modules/windows/win_robocopy.py +++ b/lib/ansible/modules/windows/win_robocopy.py @@ -24,28 +24,31 @@ options: src: description: - Source file/directory to sync. - required: yes type: path + required: yes dest: description: - Destination file/directory to sync (Will receive contents of src). - required: yes type: path + required: yes recurse: description: - Includes all subdirectories (Toggles the C(/e) flag to RoboCopy). - If C(flags) is set, this will be ignored. type: bool - default: 'no' + default: no purge: description: - Deletes any files/directories found in the destination that do not exist in the source. - - Toggles the C(/purge) flag to RoboCopy. If C(flags) is set, this will be ignored. + - Toggles the C(/purge) flag to RoboCopy. + - If C(flags) is set, this will be ignored. type: bool - default: 'no' + default: no flags: description: - - Directly supply Robocopy flags. If set, C(purge) and C(recurse) will be ignored. + - Directly supply Robocopy flags. + - If set, C(purge) and C(recurse) will be ignored. + type: str notes: - This is not a complete port of the M(synchronize) module. Unlike the M(synchronize) module this only performs the sync/copy on the remote machine, not from the master to the remote machine. @@ -97,7 +100,7 @@ EXAMPLES = r''' RETURN = r''' cmd: - description: The used command line + description: The used command line. returned: always type: str sample: robocopy C:\DirectoryOne C:\DirectoryTwo /e /purge @@ -115,12 +118,12 @@ recurse: description: Whether or not the recurse flag was toggled. returned: always type: bool - sample: False + sample: false purge: description: Whether or not the purge flag was toggled. returned: always type: bool - sample: False + sample: false flags: description: Any flags passed in by the user. returned: always diff --git a/lib/ansible/modules/windows/win_route.py b/lib/ansible/modules/windows/win_route.py index 4912c22e5b9..51e0366ad90 100644 --- a/lib/ansible/modules/windows/win_route.py +++ b/lib/ansible/modules/windows/win_route.py @@ -21,12 +21,14 @@ description: options: destination: description: - - Destination IP address in CIDR format (ip address/prefix length) + - Destination IP address in CIDR format (ip address/prefix length). + type: str required: yes gateway: description: - The gateway used by the static route. - If C(gateway) is not provided it will be set to C(0.0.0.0). + type: str metric: description: - Metric used by the static route. @@ -36,6 +38,7 @@ options: description: - If C(absent), it removes a network static route. - If C(present), it adds a network static route. + type: str choices: [ absent, present ] default: present notes: diff --git a/lib/ansible/modules/windows/win_say.py b/lib/ansible/modules/windows/win_say.py index 74ada0fdf63..cfd921631fa 100644 --- a/lib/ansible/modules/windows/win_say.py +++ b/lib/ansible/modules/windows/win_say.py @@ -25,6 +25,7 @@ options: - The text to be spoken. - Use either C(msg) or C(msg_file). - Optional so that you can use this module just to play sounds. + type: str msg_file: description: - Full path to a windows format text file containing the text to be spokend. @@ -36,6 +37,7 @@ options: - Which voice to use. See notes for how to discover installed voices. - If the requested voice is not available the default voice will be used. Example voice names from Windows 10 are C(Microsoft Zira Desktop) and C(Microsoft Hazel Desktop). + type: str default: system default voice speech_speed: description: @@ -98,17 +100,17 @@ EXAMPLES = r''' RETURN = r''' message_text: - description: the text that the module attempted to speak + description: The text that the module attempted to speak. returned: success type: str sample: "Warning, deployment commencing in 5 minutes." voice: - description: the voice used to speak the text. + description: The voice used to speak the text. returned: success type: str sample: Microsoft Hazel Desktop voice_info: - description: the voice used to speak the text. + description: The voice used to speak the text. returned: when requested voice could not be loaded type: str sample: Could not load voice TestVoice, using system default voice diff --git a/lib/ansible/modules/windows/win_scheduled_task.py b/lib/ansible/modules/windows/win_scheduled_task.py index 0ee3c6d07fe..116343b016a 100644 --- a/lib/ansible/modules/windows/win_scheduled_task.py +++ b/lib/ansible/modules/windows/win_scheduled_task.py @@ -20,6 +20,7 @@ options: name: description: - The name of the scheduled task without the path. + type: str required: yes path: description: @@ -28,11 +29,13 @@ options: already exist. - Will remove the folder when C(state=absent) and there are no tasks left in the folder. + type: str default: \ state: description: - When C(state=present) will ensure the task exists. - When C(state=absent) will ensure the task does not exist. + type: str choices: [ absent, present ] default: present @@ -52,13 +55,16 @@ options: path: description: - The path to the executable for the ExecAction. + type: str required: yes arguments: description: - An argument string to supply for the executable. + type: str working_directory: description: - The working directory to run the executable from. + type: str version_added: '2.5' # Trigger options @@ -78,6 +84,7 @@ options: description: - The trigger type, this value controls what below options are required. + type: str required: yes choices: [ boot, daily, event, idle, logon, monthlydow, monthly, registration, time, weekly, session_state_change ] enabled: @@ -96,15 +103,18 @@ options: C(time), C(weekly), (session_state_change). - Optional for the rest of the trigger types. - This is in ISO 8601 DateTime format C(YYYY-MM-DDThh:mm:ss). + type: str end_boundary: description: - The end time for when the trigger is deactivated. - This is in ISO 8601 DateTime format C(YYYY-MM-DDThh:mm:ss). + type: str execution_time_limit: description: - The maximum amount of time that the task is allowed to run for. - Optional for all the trigger types. - Is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S). + type: str delay: description: - The time to delay the task from running once the trigger has been @@ -112,6 +122,7 @@ options: - Optional when C(type) is C(boot), C(event), C(logon), C(registration), C(session_state_change). - Is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S). + type: str random_delay: description: - The delay time that is randomly added to the start time of the @@ -119,11 +130,13 @@ options: - Optional when C(type) is C(daily), C(monthlydow), C(monthly), C(time), C(weekly). - Is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S). + type: str subscription: description: - Only used and is required for C(type=event). - The XML query string that identifies the event that fires the trigger. + type: str user_id: description: - The username that the trigger will target. @@ -132,6 +145,7 @@ options: - When C(type=logon) and you want the trigger to fire when a user in a group logs on, leave this as null and set C(group) to the group you wish to trigger. + type: str days_of_week: description: - The days of the week for the trigger. @@ -139,6 +153,7 @@ options: instead of mon. - Required when C(type) is C(weekly), C(type=session_state_change). - Optional when C(type=monthlydow). + type: str days_of_month: description: - The days of the month from 1 to 31 for the triggers. @@ -146,18 +161,21 @@ options: use C(run_on_last_day_of_month). - Can be a list or comma separated string of day numbers. - Required when C(type=monthly). + type: str weeks_of_month: description: - The weeks of the month for the trigger. - Can be a list or comma separated string of the numbers 1 to 4 representing the first to 4th week of the month. - Optional when C(type=monthlydow). + type: str months_of_year: description: - The months of the year for the trigger. - Can be a list or comma separated string of full month names e.g. march instead of mar. - Optional when C(type) is C(monthlydow), C(monthly). + type: str run_on_last_week_of_month: description: - Boolean value that sets whether the task runs on the last week of the @@ -175,6 +193,7 @@ options: - The interval of weeks to run on, e.g. C(1) means every week while C(2) means every other week. - Optional when C(type=weekly). + type: int repetition: description: - Allows you to define the repetition action of the trigger that defines how often the task is run and how long the repetition pattern is repeated @@ -202,6 +221,7 @@ options: display_name: description: - The name of the user/group that is displayed in the Task Scheduler UI. + type: str version_added: '2.5' group: description: @@ -209,6 +229,7 @@ options: - C(group) and C(username) are exclusive to each other and cannot be set at the same time. - C(logon_type) can either be not set or equal C(group). + type: str version_added: '2.5' logon_type: description: @@ -223,20 +244,23 @@ options: - C(group) means that the task will run as a group. - C(service_account) means that a service account like System, Local Service or Network Service will run the task. + type: str choices: [ none, password, s4u, interactive_token, group, service_account, token_or_password ] version_added: '2.5' run_level: description: - The level of user rights used to run the task. - If not specified the task will be created with limited rights. + type: str choices: [ limited, highest ] - version_added: '2.4' aliases: [ runlevel ] + version_added: '2.4' username: description: - The user to run the scheduled task as. - Will default to the current user under an interactive token if not specified during creation. + type: str aliases: [ user ] password: description: @@ -245,35 +269,41 @@ options: excluding the builtin service accounts. - If set, will always result in a change unless C(update_password) is set to C(no) and no othr changes are required for the service. + type: str version_added: '2.4' update_password: description: - Whether to update the password even when not other changes have occured. - When C(yes) will always result in a change when executing the module. type: bool - default: 'yes' + default: yes version_added: '2.5' # RegistrationInfo options author: description: - The author of the task. + type: str version_added: '2.5' date: description: - The date when the task was registered. + type: str version_added: '2.5' description: description: - The description of the task. + type: str version_added: '2.5' source: description: - The source of the task. + type: str version_added: '2.5' version: description: - The version number of the task. + type: str version_added: '2.5' # Settings options @@ -305,6 +335,7 @@ options: - A task expires after the end_boundary has been exceeded for all triggers associated with the task. - This is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S). + type: str version_added: '2.5' disallow_start_if_on_batteries: description: @@ -322,6 +353,7 @@ options: - The amount of time allowed to complete the task. - When not set, the time limit is infinite. - This is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S). + type: str version_added: '2.5' hidden: description: @@ -362,6 +394,7 @@ options: - The maximum allowed time is 31 days. - The minimum allowed time is 1 minute. - This is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S). + type: str version_added: '2.5' run_only_if_idle: description: @@ -393,7 +426,7 @@ options: version_added: '2.5' notes: - In Ansible 2.4 and earlier, this could only be run on Server 2012/Windows 8 - or newer. Since 2.5 this restriction has been lifted. + or newer. Since Ansible 2.5 this restriction has been lifted. - The option names and structure for actions and triggers of a service follow the C(RegisteredTask) naming standard and requirements, it would be useful to read up on this guide if coming across any issues U(https://msdn.microsoft.com/en-us/library/windows/desktop/aa382542.aspx). @@ -405,7 +438,7 @@ author: ''' EXAMPLES = r''' -- name: create a task to open 2 command prompts as SYSTEM +- name: Create a task to open 2 command prompts as SYSTEM win_scheduled_task: name: TaskName description: open command prompt @@ -421,7 +454,7 @@ EXAMPLES = r''' state: present enabled: yes -- name: create task to run a PS script as NETWORK service on boot +- name: Create task to run a PS script as NETWORK service on boot win_scheduled_task: name: TaskName2 description: Run a PowerShell script @@ -434,20 +467,20 @@ EXAMPLES = r''' run_level: highest state: present -- name: change above task to run under a domain user account, storing the passwords +- name: Change above task to run under a domain user account, storing the passwords win_scheduled_task: name: TaskName2 username: DOMAIN\User password: Password logon_type: password -- name: change the above task again, choosing not to store the password +- name: Change the above task again, choosing not to store the password win_scheduled_task: name: TaskName2 username: DOMAIN\User logon_type: s4u -- name: create task with multiple triggers +- name: Create task with multiple triggers win_scheduled_task: name: TriggerTask path: \Custom @@ -458,7 +491,7 @@ EXAMPLES = r''' - type: monthlydow username: SYSTEM -- name: set logon type to password but don't force update the password +- name: Set logon type to password but don't force update the password win_scheduled_task: name: TriggerTask path: \Custom @@ -468,12 +501,12 @@ EXAMPLES = r''' password: password update_password: no -- name: disable a task that already exists +- name: Disable a task that already exists win_scheduled_task: name: TaskToDisable enabled: no -- name: create a task that will be repeated every minute for five minutes +- name: Create a task that will be repeated every minute for five minutes win_scheduled_task: name: RepeatedTask description: open command prompt diff --git a/lib/ansible/modules/windows/win_scheduled_task_stat.py b/lib/ansible/modules/windows/win_scheduled_task_stat.py index 269927be07c..428bd72721b 100644 --- a/lib/ansible/modules/windows/win_scheduled_task_stat.py +++ b/lib/ansible/modules/windows/win_scheduled_task_stat.py @@ -23,11 +23,13 @@ description: options: path: description: The folder path where the task lives. + type: str default: \ name: description: - The name of the scheduled task to get information for. - If C(name) is set and exists, will return information on the task itself. + type: str seealso: - module: win_scheduled_task author: @@ -35,17 +37,17 @@ author: ''' EXAMPLES = r''' -- name: get information about a folder +- name: Get information about a folder win_scheduled_task_stat: path: \folder name register: task_folder_stat -- name: get information about a task in the root folder +- name: Get information about a task in the root folder win_scheduled_task_stat: name: task name register: task_stat -- name: get information about a task in a custom folder +- name: Get information about a task in a custom folder win_scheduled_task_stat: path: \folder name name: task name @@ -70,7 +72,7 @@ folder_exists: description: Whether the folder set at path exists. returned: always type: bool - sample: True + sample: true folder_task_count: description: The number of tasks that exist in the folder. returned: always @@ -172,12 +174,12 @@ settings: command of the Context menu. returned: '' type: bool - sample: True + sample: true allow_hard_terminate: description: Whether the task can terminated by using TerminateProcess. returned: '' type: bool - sample: True + sample: true compatibility: description: The compatibility level of the task returned: '' @@ -194,18 +196,18 @@ settings: running on battery power. returned: '' type: bool - sample: False + sample: false disallow_start_on_remote_app_session: description: Whether the task will not be started when in a remote app session. returned: '' type: bool - sample: True + sample: true enabled: description: Whether the task is enabled. returned: '' type: bool - sample: True + sample: true execution_time_limit: description: The amount of time allowed to complete the task. returned: '' @@ -215,7 +217,7 @@ settings: description: Whether the task is hidden in the UI. returned: '' type: bool - sample: False + sample: false idle_settings: description: The idle settings of the task. returned: '' @@ -267,40 +269,40 @@ settings: state. returned: '' type: bool - sample: True + sample: true run_only_if_network_available: description: Whether the task will run only when a network is available. returned: '' type: bool - sample: False + sample: false start_when_available: description: Whether the task can start at any time after its scheduled time has passed. returned: '' type: bool - sample: False + sample: false stop_if_going_on_batteries: description: Whether the task will be stopped if the computer begins to run on battery power. returned: '' type: bool - sample: True + sample: true use_unified_scheduling_engine: description: Whether the task will use the unifed scheduling engine. returned: '' type: bool - sample: False + sample: false volatile: description: Whether thet ask is volatile. returned: '' type: bool - sample: False + sample: false wake_to_run: description: Whether the task will wake the computer when it is time to run the task. returned: '' type: bool - sample: False + sample: false state: description: Details on the state of the task returned: name is specified and task exists @@ -336,7 +338,7 @@ task_exists: description: Whether the task at the folder exists. returned: name is specified type: bool - sample: True + sample: true triggers: description: A list of triggers. returned: name is specified and task exists diff --git a/lib/ansible/modules/windows/win_security_policy.py b/lib/ansible/modules/windows/win_security_policy.py index a57e1b2690a..d582a532317 100644 --- a/lib/ansible/modules/windows/win_security_policy.py +++ b/lib/ansible/modules/windows/win_security_policy.py @@ -28,16 +28,19 @@ options: 'File System' - If wanting to edit the C(Privilege Rights) section, use the M(win_user_right) module instead. + type: str required: yes key: description: - The ini key of the section or policy name to modify. - The module will return an error if this key is invalid. + type: str required: yes value: description: - The value for the ini key or policy name. - If the key takes in a boolean value then 0 = False and 1 = True. + type: str required: yes notes: - This module uses the SecEdit.exe tool to configure the values, more details @@ -56,25 +59,25 @@ author: ''' EXAMPLES = r''' -- name: change the guest account name +- name: Change the guest account name win_security_policy: section: System Access key: NewGuestName value: Guest Account -- name: set the maximum password age +- name: Set the maximum password age win_security_policy: section: System Access key: MaximumPasswordAge value: 15 -- name: do not store passwords using reversible encryption +- name: Do not store passwords using reversible encryption win_security_policy: section: System Access key: ClearTextPassword value: 0 -- name: enable system events +- name: Enable system events win_security_policy: section: Event Audit key: AuditSystemEvents diff --git a/lib/ansible/modules/windows/win_service.py b/lib/ansible/modules/windows/win_service.py index c491da70ee7..20391f5985d 100644 --- a/lib/ansible/modules/windows/win_service.py +++ b/lib/ansible/modules/windows/win_service.py @@ -73,6 +73,7 @@ options: path: description: - The path to the executable to set for the service. + type: str version_added: '2.3' password: description: @@ -80,12 +81,14 @@ options: - This and the C(username) argument must be supplied together. - If specifying C(LocalSystem), C(NetworkService) or C(LocalService) this field must be an empty string and not null. + type: str version_added: '2.3' start_mode: description: - Set the startup type for the service. - A newly created service will default to C(auto). - C(delayed) added in Ansible 2.3 + type: str choices: [ auto, delayed, disabled, manual ] state: description: @@ -99,6 +102,7 @@ options: check the return value C(can_pause_and_continue). - You can only pause a service that is already started. - A newly created service will default to C(stopped). + type: str choices: [ absent, paused, started, stopped, restarted ] username: description: @@ -107,9 +111,8 @@ options: a local or domain account. - Set to C(LocalSystem) to use the SYSTEM account. - A newly created service will default to C(LocalSystem). + type: str version_added: '2.3' -notes: -- For non-Windows targets, use the M(service) module instead. seealso: - module: service - module: win_nssm @@ -263,7 +266,7 @@ can_pause_and_continue: description: Whether the service can be paused and unpaused. returned: success and service exists type: bool - sample: True + sample: true description: description: The description of the service. returned: success and service exists @@ -278,15 +281,15 @@ desktop_interact: description: Whether the current user is allowed to interact with the desktop. returned: success and service exists type: bool - sample: False + sample: false dependencies: description: A list of services that is depended by this service. returned: success and service exists type: list - sample: False + sample: false depended_by: description: A list of services that depend on this service. returned: success and service exists type: list - sample: False + sample: false ''' diff --git a/lib/ansible/modules/windows/win_share.py b/lib/ansible/modules/windows/win_share.py index 2f2af1b806d..0a730f7879c 100644 --- a/lib/ansible/modules/windows/win_share.py +++ b/lib/ansible/modules/windows/win_share.py @@ -25,53 +25,55 @@ options: name: description: - Share name. + type: str required: yes path: description: - Share directory. - required: yes type: path + required: yes state: description: - Specify whether to add C(present) or remove C(absent) the specified share. + type: str choices: [ absent, present ] default: present description: description: - Share description. + type: str list: description: - Specify whether to allow or deny file listing, in case user has no permission on share. Also known as Access-Based Enumeration. type: bool - default: 'no' + default: no read: description: - Specify user list that should get read access on share, separated by comma. + type: str change: description: - Specify user list that should get read and write access on share, separated by comma. + type: str full: description: - Specify user list that should get full access on share, separated by comma. + type: str deny: description: - Specify user list that should get no access, regardless of implied access on share, separated by comma. + type: str caching_mode: description: - Set the CachingMode for this share. - choices: - - BranchCache - - Documents - - Manual - - None - - Programs - - Unknown + type: str + choices: [ BranchCache, Documents, Manual, None, Programs, Unknown ] default: Manual version_added: "2.3" encrypt: description: Sets whether to encrypt the traffic to the share or not. type: bool - default: 'no' + default: no version_added: "2.4" author: - Hans-Joachim Kliemeck (@h0nIg) diff --git a/lib/ansible/modules/windows/win_shell.py b/lib/ansible/modules/windows/win_shell.py index bbb0a9da082..cbec4bd0020 100644 --- a/lib/ansible/modules/windows/win_shell.py +++ b/lib/ansible/modules/windows/win_shell.py @@ -23,6 +23,7 @@ options: description: - The C(win_shell) module takes a free form command to run. - There is no parameter actually named 'free form'. See the examples! + type: str required: yes creates: description: @@ -44,6 +45,7 @@ options: stdin: description: - Set the stdin of the command directly to the specified value. + type: str version_added: '2.5' notes: - If you want to run an executable securely and predictably, it may be @@ -53,7 +55,6 @@ notes: - WinRM will not return from a command execution until all child processes created have exited. Thus, it is not possible to use C(win_shell) to spawn long-running child or background processes. Consider creating a Windows service for managing background processes. - - For non-Windows targets, use the M(shell) module instead. seealso: - module: psexec - module: raw @@ -87,7 +88,7 @@ EXAMPLES = r''' executable: cmd register: homedir_out -- name: run multi-lined shell commands +- name: Run multi-lined shell commands win_shell: | $value = Test-Path -Path C:\temp if ($value) { @@ -95,7 +96,7 @@ EXAMPLES = r''' } New-Item -Path C:\temp -ItemType Directory -- name: retrieve the input based on stdin +- name: Retrieve the input based on stdin win_shell: '$string = [Console]::In.ReadToEnd(); Write-Output $string.Trim()' args: stdin: Input message @@ -103,47 +104,47 @@ EXAMPLES = r''' RETURN = r''' msg: - description: changed + description: Changed. returned: always type: bool - sample: True + sample: true start: - description: The command execution start time + description: The command execution start time. returned: always type: str sample: '2016-02-25 09:18:26.429568' end: - description: The command execution end time + description: The command execution end time. returned: always type: str sample: '2016-02-25 09:18:26.755339' delta: - description: The command execution delta time + description: The command execution delta time. returned: always type: str sample: '0:00:00.325771' stdout: - description: The command standard output + description: The command standard output. returned: always type: str sample: 'Clustering node rabbit@slave1 with rabbit@master ...' stderr: - description: The command standard error + description: The command standard error. returned: always type: str sample: 'ls: cannot access foo: No such file or directory' cmd: - description: The command executed by the task + description: The command executed by the task. returned: always type: str sample: 'rabbitmqctl join_cluster rabbit@master' rc: - description: The command return code (0 means success) + description: The command return code (0 means success). returned: always type: int sample: 0 stdout_lines: - description: The command standard output split in lines + description: The command standard output split in lines. returned: always type: list sample: [u'Clustering node rabbit@slave1 with rabbit@master ...'] diff --git a/lib/ansible/modules/windows/win_shortcut.py b/lib/ansible/modules/windows/win_shortcut.py index de27d4b8e66..2fe2ff42920 100644 --- a/lib/ansible/modules/windows/win_shortcut.py +++ b/lib/ansible/modules/windows/win_shortcut.py @@ -21,20 +21,23 @@ options: - Executable or URL the shortcut points to. - The executable needs to be in your PATH, or has to be an absolute path to the executable. + type: str description: description: - Description for the shortcut. - This is usually shown when hoovering the icon. + type: str dest: description: - Destination file for the shortcuting file. - File name should have a C(.lnk) or C(.url) extension. - required: yes type: path + required: yes arguments: description: - Additional arguments for the executable defined in C(src). - Was originally just C(args) but renamed in Ansible 2.8. + type: str aliases: [ args ] directory: description: @@ -52,14 +55,17 @@ options: - This is a combination of one or more modifiers and a key. - Possible modifiers are Alt, Ctrl, Shift, Ext. - Possible keys are [A-Z] and [0-9]. + type: str windowstyle: description: - Influences how the application is displayed when it is launched. + type: str choices: [ maximized, minimized, normal ] state: description: - When C(absent), removes the shortcut if it exists. - When C(present), creates or updates the shortcut. + type: str choices: [ absent, present ] default: present run_as_admin: diff --git a/lib/ansible/modules/windows/win_snmp.py b/lib/ansible/modules/windows/win_snmp.py index 317b8e20697..a52ef66a511 100644 --- a/lib/ansible/modules/windows/win_snmp.py +++ b/lib/ansible/modules/windows/win_snmp.py @@ -10,7 +10,7 @@ ANSIBLE_METADATA = { 'supported_by': 'community' } -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: win_snmp version_added: '2.8' @@ -33,13 +33,14 @@ options: empty list for either C(community_strings) or C(permitted_managers) will result in the respective lists being removed entirely. - C(remove) will remove SNMP community strings and/or SNMP managers - default: set + type: str choices: [ add, set, remove ] + default: set author: - Michael Cassaniti (@mcassaniti) ''' -EXAMPLES = ''' +EXAMPLES = r''' --- - hosts: Windows tasks: @@ -61,16 +62,16 @@ EXAMPLES = ''' action: set ''' -RETURN = ''' +RETURN = r''' community_strings: - description: The list of community strings for this machine + description: The list of community strings for this machine. type: list returned: always sample: - public - snmp-ro permitted_managers: - description: The list of permitted managers for this machine + description: The list of permitted managers for this machine. type: list returned: always sample: diff --git a/lib/ansible/modules/windows/win_stat.py b/lib/ansible/modules/windows/win_stat.py index e8a317d7998..973c1357c57 100644 --- a/lib/ansible/modules/windows/win_stat.py +++ b/lib/ansible/modules/windows/win_stat.py @@ -24,35 +24,34 @@ options: description: - The full path of the file/object to get the facts of; both forward and back slashes are accepted. - required: yes type: path + required: yes get_md5: description: - Whether to return the checksum sum of the file. Between Ansible 1.9 - and 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible + and Ansible 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible 2.3 this is back to an MD5. Will return None if host is unable to use specified algorithm. - The default of this option changed from C(yes) to C(no) in Ansible 2.5 and will be removed altogether in Ansible 2.9. - - Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an + - Use C(get_checksum=yes) with C(checksum_algorithm=md5) to return an md5 hash under the C(checksum) return value. type: bool - default: 'no' + default: no get_checksum: description: - Whether to return a checksum of the file (default sha1) type: bool - default: 'yes' + default: yes version_added: "2.1" checksum_algorithm: description: - - Algorithm to determine checksum of file. Will throw an error if - the host is unable to use specified algorithm. + - Algorithm to determine checksum of file. + - Will throw an error if the host is unable to use specified algorithm. + type: str default: sha1 choices: [ md5, sha1, sha256, sha384, sha512 ] version_added: "2.3" -notes: - - For non-Windows targets, use the M(stat) module instead. seealso: - module: stat - module: win_file @@ -106,137 +105,137 @@ changed: description: Whether anything was changed returned: always type: bool - sample: True + sample: true stat: description: dictionary containing all the stat data returned: success type: complex contains: attributes: - description: Attributes of the file at path in raw form + description: Attributes of the file at path in raw form. returned: success, path exists type: str sample: "Archive, Hidden" checksum: - description: The checksum of a file based on checksum_algorithm specified + description: The checksum of a file based on checksum_algorithm specified. returned: success, path exist, path is a file, get_checksum == True checksum_algorithm specified is supported type: str sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 creationtime: - description: The create time of the file represented in seconds since epoch + description: The create time of the file represented in seconds since epoch. returned: success, path exists type: float sample: 1477984205.15 exists: - description: If the path exists or not + description: If the path exists or not. returned: success type: bool - sample: True + sample: true extension: - description: The extension of the file at path + description: The extension of the file at path. returned: success, path exists, path is a file type: str sample: ".ps1" filename: - description: The name of the file (without path) + description: The name of the file (without path). returned: success, path exists, path is a file type: str sammple: foo.ini hlnk_targets: - description: List of other files pointing to the same file (hard links), excludes the current file + description: List of other files pointing to the same file (hard links), excludes the current file. returned: success, path exists type: list sample: - C:\temp\file.txt - C:\Windows\update.log isarchive: - description: If the path is ready for archiving or not + description: If the path is ready for archiving or not. returned: success, path exists type: bool - sample: True + sample: true isdir: - description: If the path is a directory or not + description: If the path is a directory or not. returned: success, path exists type: bool - sample: True + sample: true ishidden: - description: If the path is hidden or not + description: If the path is hidden or not. returned: success, path exists type: bool - sample: True + sample: true isjunction: - description: If the path is a junction point or not + description: If the path is a junction point or not. returned: success, path exists type: bool - sample: True + sample: true islnk: - description: If the path is a symbolic link or not + description: If the path is a symbolic link or not. returned: success, path exists type: bool - sample: True + sample: true isreadonly: - description: If the path is read only or not + description: If the path is read only or not. returned: success, path exists type: bool - sample: True + sample: true isreg: - description: If the path is a regular file + description: If the path is a regular file. returned: success, path exists type: bool - sample: True + sample: true isshared: - description: If the path is shared or not + description: If the path is shared or not. returned: success, path exists type: bool - sample: True + sample: true lastaccesstime: - description: The last access time of the file represented in seconds since epoch + description: The last access time of the file represented in seconds since epoch. returned: success, path exists type: float sample: 1477984205.15 lastwritetime: - description: The last modification time of the file represented in seconds since epoch + description: The last modification time of the file represented in seconds since epoch. returned: success, path exists type: float sample: 1477984205.15 lnk_source: - description: Target of the symlink normalized for the remote filesystem + description: Target of the symlink normalized for the remote filesystem. returned: success, path exists and the path is a symbolic link or junction point type: str sample: C:\temp\link lnk_target: - description: Target of the symlink. Note that relative paths remain relative + description: Target of the symlink. Note that relative paths remain relative. returned: success, path exists and the path is a symbolic link or junction point type: str sample: ..\link md5: - description: The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.9 + description: The MD5 checksum of a file (Between Ansible 1.9 and Ansible 2.2 this was returned as a SHA1 hash), will be removed in Ansible 2.9. returned: success, path exist, path is a file, get_md5 == True type: str sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 nlink: - description: Number of links to the file (hard links) + description: Number of links to the file (hard links). returned: success, path exists type: int sample: 1 owner: - description: The owner of the file + description: The owner of the file. returned: success, path exists type: str sample: BUILTIN\Administrators path: - description: The full absolute path to the file + description: The full absolute path to the file. returned: success, path exists, file exists type: str sample: C:\foo.ini sharename: - description: The name of share if folder is shared + description: The name of share if folder is shared. returned: success, path exists, file is a directory and isshared == True type: str sample: file-share size: - description: The size in bytes of a file or folder + description: The size in bytes of a file or folder. returned: success, path exists, file is not a link type: int sample: 1024 diff --git a/lib/ansible/modules/windows/win_tempfile.py b/lib/ansible/modules/windows/win_tempfile.py index 2fce96585d8..19d6c19166d 100644 --- a/lib/ansible/modules/windows/win_tempfile.py +++ b/lib/ansible/modules/windows/win_tempfile.py @@ -20,6 +20,7 @@ options: state: description: - Whether to create file or directory. + type: str choices: [ directory, file ] default: file path: @@ -31,13 +32,13 @@ options: prefix: description: - Prefix of file/directory name created by module. + type: str default: ansible. suffix: description: - Suffix of file/directory name created by module. + type: str default: '' -notes: - - For non-Windows targets, please use the M(tempfile) module instead. seealso: - module: tempfile author: @@ -58,7 +59,7 @@ EXAMPLES = r""" RETURN = r''' path: - description: Path to created file or directory + description: Path to created file or directory. returned: success type: str sample: C:\Users\Administrator\AppData\Local\Temp\ansible.bMlvdk diff --git a/lib/ansible/modules/windows/win_template.py b/lib/ansible/modules/windows/win_template.py index a717b582597..23e03c32794 100644 --- a/lib/ansible/modules/windows/win_template.py +++ b/lib/ansible/modules/windows/win_template.py @@ -28,46 +28,54 @@ description: template, and C(template_run_date) is the date that the template was rendered. Note that including a string that uses a date in the template will result in the template being marked 'changed' each time." + - For other platforms you can use M(template) which uses '\n' as C(newline_sequence). options: src: description: - Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path. + type: path required: yes dest: description: - Location to render the template to on the remote machine. + type: str required: yes newline_sequence: description: - Specify the newline sequence to use for templating files. + type: str choices: [ '\n', '\r', '\r\n' ] default: '\r\n' version_added: '2.4' block_start_string: description: - The string marking the beginning of a block. + type: str default: '{%' version_added: '2.4' block_end_string: description: - The string marking the end of a block. + type: str default: '%}' version_added: '2.4' variable_start_string: description: - The string marking the beginning of a print statement. + type: str default: '{{' version_added: '2.4' variable_end_string: description: - The string marking the end of a print statement. + type: str default: '}}' version_added: '2.4' trim_blocks: description: - If this is set to C(yes) the first newline after a block is removed (block, not variable tag!). type: bool - default: 'no' + default: no version_added: '2.4' force: description: @@ -76,11 +84,10 @@ options: - If C(no), the file will only be transferred if the destination does not exist. type: bool - default: 'yes' + default: yes version_added: '2.4' notes: - - For other platforms you can use M(template) which uses '\n' as C(newline_sequence). - - Templates are loaded with C(trim_blocks=True). + - Templates are loaded with C(trim_blocks=yes). - Beware fetching files from windows machines when creating templates because certain tools, such as Powershell ISE, and regedit's export facility add a Byte Order Mark as the first character of the file, which can cause tracebacks. diff --git a/lib/ansible/modules/windows/win_timezone.py b/lib/ansible/modules/windows/win_timezone.py index b913a30869b..60849657946 100644 --- a/lib/ansible/modules/windows/win_timezone.py +++ b/lib/ansible/modules/windows/win_timezone.py @@ -20,6 +20,7 @@ options: description: - Timezone to set to. - 'Example: Central Standard Time' + type: str required: yes notes: - The module will check if the provided timezone is supported on the machine. @@ -50,12 +51,12 @@ EXAMPLES = r''' RETURN = r''' previous_timezone: - description: The previous timezone if it was changed, otherwise the existing timezone + description: The previous timezone if it was changed, otherwise the existing timezone. returned: success type: str sample: Central Standard Time timezone: - description: The current timezone (possibly changed) + description: The current timezone (possibly changed). returned: success type: str sample: Central Standard Time diff --git a/lib/ansible/modules/windows/win_toast.py b/lib/ansible/modules/windows/win_toast.py index cbbbd34d3fb..355a3db1c78 100644 --- a/lib/ansible/modules/windows/win_toast.py +++ b/lib/ansible/modules/windows/win_toast.py @@ -28,11 +28,13 @@ options: group: description: - Which notification group to add the notification to. + type: str default: Powershell msg: description: - The message to appear inside the notification. - May include \n to format the message to appear within the Action Center. + type: str default: Hello, World! popup: description: @@ -42,10 +44,12 @@ options: tag: description: - The tag to add to the notification. + type: str default: Ansible title: description: - The notification title, which appears in the pop up.. + type: str default: Notification HH:mm notes: - This module must run on a windows 10 or Server 2016 host, so ensure your play targets windows hosts, or delegates to a windows host. diff --git a/lib/ansible/modules/windows/win_unzip.py b/lib/ansible/modules/windows/win_unzip.py index 4fde5c6c4d6..5830c61cd8b 100644 --- a/lib/ansible/modules/windows/win_unzip.py +++ b/lib/ansible/modules/windows/win_unzip.py @@ -27,25 +27,25 @@ options: src: description: - File to be unzipped (provide absolute path). - required: yes type: path + required: yes dest: description: - Destination of zip file (provide absolute path of directory). If it does not exist, the directory will be created. - required: yes type: path + required: yes delete_archive: description: - Remove the zip file, after unzipping. type: bool - default: 'no' + default: no aliases: [ rm ] recurse: description: - Recursively expand zipped files within the src file. - Setting to a value of C(yes) requires the PSCX module to be installed. type: bool - default: 'no' + default: no creates: description: - If this file or directory exists the specified src will not be extracted. @@ -55,7 +55,6 @@ notes: - For extracting any compression types other than .zip, the PowerShellCommunityExtensions (PSCX) Module is required. This module (in conjunction with PSCX) has the ability to recursively unzip files within the src zip file provided and also functionality for many other compression types. If the destination directory does not exist, it will be created before unzipping the file. Specifying rm parameter will force removal of the src file after extraction. -- For non-Windows targets, use the M(unarchive) module instead. seealso: - module: unarchive author: @@ -64,7 +63,7 @@ author: EXAMPLES = r''' # This unzips a library that was downloaded with win_get_url, and removes the file after extraction -# $ ansible -i hosts -m win_unzip -a "src=C:\LibraryToUnzip.zip dest=C:\Lib remove=true" all +# $ ansible -i hosts -m win_unzip -a "src=C:\LibraryToUnzip.zip dest=C:\Lib remove=yes" all - name: Unzip a bz2 (BZip) file win_unzip: @@ -105,7 +104,7 @@ removed: description: Whether the module did remove any files during task run returned: always type: bool - sample: True + sample: true src: description: The provided source path returned: always diff --git a/lib/ansible/modules/windows/win_updates.py b/lib/ansible/modules/windows/win_updates.py index c948d76421e..72ecccd3d9e 100644 --- a/lib/ansible/modules/windows/win_updates.py +++ b/lib/ansible/modules/windows/win_updates.py @@ -47,21 +47,22 @@ options: and continue to install updates after the reboot. - This can be used instead of using a M(win_reboot) task after this one and ensures all updates for that category is installed in one go. - - Async does not work when C(reboot=True). + - Async does not work when C(reboot=yes). type: bool - default: 'no' + default: no version_added: '2.5' reboot_timeout: description: - The time in seconds to wait until the host is back online from a reboot. - - This is only used if C(reboot=True) and a reboot is required. + - This is only used if C(reboot=yes) and a reboot is required. default: 1200 version_added: '2.5' state: description: - Controls whether found updates are returned as a list or actually installed. - This module also supports Ansible check mode, which has the same effect as setting state=searched + type: str choices: [ installed, searched ] default: installed log_path: @@ -91,7 +92,7 @@ options: - Can also be set to C(yes) on newer hosts where become does not work due to further privilege restrictions from the OS defaults. type: bool - default: 'no' + default: no version_added: '2.6' notes: - C(win_updates) must be run by a user with membership in the local Administrators group. @@ -172,44 +173,44 @@ EXAMPLES = r''' RETURN = r''' reboot_required: - description: True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot) + description: True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot). returned: success type: bool - sample: True + sample: true updates: - description: List of updates that were found/installed + description: List of updates that were found/installed. returned: success type: complex sample: contains: title: - description: Display name + description: Display name. returned: always type: str sample: "Security Update for Windows Server 2012 R2 (KB3004365)" kb: - description: A list of KB article IDs that apply to the update + description: A list of KB article IDs that apply to the update. returned: always type: list of strings sample: [ '3004365' ] id: - description: Internal Windows Update GUID + description: Internal Windows Update GUID. returned: always type: str (guid) sample: "fb95c1c8-de23-4089-ae29-fd3351d55421" installed: - description: Was the update successfully installed + description: Was the update successfully installed. returned: always type: bool - sample: True + sample: true categories: - description: A list of category strings for this update + description: A list of category strings for this update. returned: always type: list of strings sample: [ 'Critical Updates', 'Windows Server 2012 R2' ] failure_hresult_code: - description: The HRESULT code from a failed update + description: The HRESULT code from a failed update. returned: on install failure type: bool sample: 2147942402 @@ -223,23 +224,23 @@ filtered_updates: sample: see the updates return value contains: filtered_reason: - description: The reason why this update was filtered + description: The reason why this update was filtered. returned: always type: str sample: 'skip_hidden' found_update_count: - description: The number of updates found needing to be applied + description: The number of updates found needing to be applied. returned: success type: int sample: 3 installed_update_count: - description: The number of updates successfully installed + description: The number of updates successfully installed. returned: success type: int sample: 2 failed_update_count: - description: The number of updates that failed to install + description: The number of updates that failed to install. returned: always type: int sample: 0 diff --git a/lib/ansible/modules/windows/win_uri.py b/lib/ansible/modules/windows/win_uri.py index dcdb037fb17..b1bcbc61ef9 100644 --- a/lib/ansible/modules/windows/win_uri.py +++ b/lib/ansible/modules/windows/win_uri.py @@ -22,25 +22,31 @@ options: url: description: - Supports FTP, HTTP or HTTPS URLs in the form of (ftp|http|https)://host.domain:port/path. + type: str required: yes method: description: - The HTTP Method of the request or response. + type: str choices: [ CONNECT, DELETE, GET, HEAD, MERGE, OPTIONS, PATCH, POST, PUT, REFRESH, TRACE ] default: GET content_type: description: - Sets the "Content-Type" header. + type: str body: description: - The body of the HTTP request/response to the web service. + type: raw user: description: - Username to use for authentication. + type: str version_added: '2.4' password: description: - Password to use for authentication. + type: str version_added: '2.4' force_basic_auth: description: @@ -50,7 +56,7 @@ options: - This option forces the sending of the Basic authentication header upon the initial request. type: bool - default: 'no' + default: no version_added: '2.5' dest: description: @@ -61,6 +67,7 @@ options: description: - Extra headers to set on the request, see the examples for more details on how to set this. + type: dict creates: description: - A filename, when it already exists, this step will be skipped. @@ -78,7 +85,7 @@ options: "application/json", then the JSON is additionally loaded into a key called C(json) in the dictionary results. type: bool - default: 'no' + default: no version_added: '2.4' status_code: description: @@ -105,6 +112,7 @@ options: - C(none) will not follow any redirects. - C(safe) will follow only "safe" redirects, where "safe" means that the client is only doing a C(GET) or C(HEAD) on the URI to which it is being redirected. + type: str choices: [ all, none, safe ] default: safe version_added: '2.4' @@ -124,7 +132,7 @@ options: set to C(no) used on personally controlled sites using self-signed certificates. type: bool - default: 'yes' + default: yes version_added: '2.4' client_cert: description: @@ -139,9 +147,8 @@ options: description: - The password for the client certificate (.pfx) file that is used for a secure web request. + type: str version_added: '2.5' -notes: -- For non-Windows targets, use the M(uri) module instead. seealso: - module: uri - module: win_get_url @@ -178,12 +185,12 @@ EXAMPLES = r''' RETURN = r''' elapsed: - description: The number of seconds that elapsed while performing the download + description: The number of seconds that elapsed while performing the download. returned: always type: float sample: 23.2 url: - description: The Target URL + description: The Target URL. returned: always type: str sample: https://www.ansible.com @@ -208,7 +215,7 @@ content_length: type: int sample: 54447 json: - description: The json structure returned under content as a dictionary + description: The json structure returned under content as a dictionary. returned: success and Content-Type is "application/json" or "application/javascript" and return_content is True type: dict sample: {"this-is-dependent": "on the actual return content"} diff --git a/lib/ansible/modules/windows/win_user.py b/lib/ansible/modules/windows/win_user.py index 05c2d583139..6b3e7efcfc1 100644 --- a/lib/ansible/modules/windows/win_user.py +++ b/lib/ansible/modules/windows/win_user.py @@ -23,22 +23,27 @@ options: name: description: - Name of the user to create, remove or modify. + type: str required: yes fullname: description: - Full name of the user. + type: str version_added: "1.9" description: description: - Description of the user. + type: str version_added: "1.9" password: description: - Optionally set the user's password to this (plain text) value. + type: str update_password: description: - C(always) will update passwords if they differ. C(on_create) will only set the password for newly created users. + type: str choices: [ always, on_create ] default: always version_added: "1.9" @@ -74,9 +79,9 @@ options: groups: description: - Adds or removes the user from this comma-separated lis of groups, - depending on the value of I(groups_action). When I(groups_action) is - C(replace) and I(groups) is set to the empty string ('groups='), the - user is removed from all groups. + depending on the value of I(groups_action). + - When I(groups_action) is C(replace) and I(groups) is set to the empty + string ('groups='), the user is removed from all groups. version_added: "1.9" groups_action: description: @@ -85,6 +90,7 @@ options: - If C(replace), the user is added as a member of each group in I(groups) and removed from any other groups. - If C(remove), the user is removed from each group in I(groups). + type: str choices: [ add, replace, remove ] default: replace version_added: "1.9" @@ -94,10 +100,9 @@ options: - When C(present), creates or updates the user account. - When C(query) (new in 1.9), retrieves the user account details without making any changes. + type: str choices: [ absent, present, query ] default: present -notes: - - For non-Windows targets, use the M(user) module instead. seealso: - module: user - module: win_domain_membership diff --git a/lib/ansible/modules/windows/win_user_right.py b/lib/ansible/modules/windows/win_user_right.py index 6a4484ff77a..90d8bd3276e 100644 --- a/lib/ansible/modules/windows/win_user_right.py +++ b/lib/ansible/modules/windows/win_user_right.py @@ -25,6 +25,7 @@ options: - The name of the User Right as shown by the C(Constant Name) value from U(https://technet.microsoft.com/en-us/library/dd349804.aspx). - The module will return an error if the right is invalid. + type: str required: yes users: description: @@ -34,13 +35,14 @@ options: - For local users/groups it can be in the form user-group, .\user-group, SERVERNAME\user-group where SERVERNAME is the name of the remote server. - You can also add special local accounts like SYSTEM and others. - required: yes type: list + required: yes action: description: - C(add) will add the users/groups to the existing right. - C(remove) will remove the users/groups from the existing right. - C(set) will replace the users/groups of the existing right. + type: str default: set choices: [ add, remove, set ] notes: @@ -56,7 +58,7 @@ author: EXAMPLES = r''' --- -- name: replace the entries of Deny log on locally +- name: Replace the entries of Deny log on locally win_user_right: name: SeDenyInteractiveLogonRight users: @@ -64,7 +66,7 @@ EXAMPLES = r''' - Users action: set -- name: add account to Log on as a service +- name: Add account to Log on as a service win_user_right: name: SeServiceLogonRight users: @@ -72,7 +74,7 @@ EXAMPLES = r''' - '{{ansible_hostname}}\local-user' action: add -- name: remove accounts who can create Symbolic links +- name: Remove accounts who can create Symbolic links win_user_right: name: SeCreateSymbolicLinkPrivilege users: diff --git a/lib/ansible/modules/windows/win_wait_for.py b/lib/ansible/modules/windows/win_wait_for.py index 6df6b74b99b..4379dffb7f2 100644 --- a/lib/ansible/modules/windows/win_wait_for.py +++ b/lib/ansible/modules/windows/win_wait_for.py @@ -48,6 +48,7 @@ options: - A resolvable hostname or IP address to wait for. - If C(state=drained) then it will only check for connections on the IP specified, you can use '0.0.0.0' to use all host IPs. + type: str default: '127.0.0.1' path: description: @@ -67,6 +68,7 @@ options: matches. - If C(state) is absent then it will wait until the regex does not match. - Defaults to a multiline regex. + type: str sleep: description: - Number of seconds to sleep between checks. @@ -80,8 +82,9 @@ options: - When checking for a file or a search string C(present) or C(started) will ensure that the file or string is present, C(absent) will check that the file or search string is absent or removed. - default: started + type: str choices: [ absent, drained, present, started, stopped ] + default: started timeout: description: - The maximum number of seconds to wait for. @@ -95,40 +98,40 @@ author: ''' EXAMPLES = r''' -- name: wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds +- name: Wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds win_wait_for: port: 8000 delay: 10 -- name: wait 150 seconds for port 8000 of any IP to close active connections +- name: Wait 150 seconds for port 8000 of any IP to close active connections win_wait_for: host: 0.0.0.0 port: 8000 state: drained timeout: 150 -- name: wait for port 8000 of any IP to close active connection, ignoring certain hosts +- name: Wait for port 8000 of any IP to close active connection, ignoring certain hosts win_wait_for: host: 0.0.0.0 port: 8000 state: drained exclude_hosts: ['10.2.1.2', '10.2.1.3'] -- name: wait for file C:\temp\log.txt to exist before continuing +- name: Wait for file C:\temp\log.txt to exist before continuing win_wait_for: path: C:\temp\log.txt -- name: wait until process complete is in the file before continuing +- name: Wait until process complete is in the file before continuing win_wait_for: path: C:\temp\log.txt search_regex: process complete -- name: wait until file if removed +- name: Wait until file is removed win_wait_for: path: C:\temp\log.txt state: absent -- name: wait until port 1234 is offline but try every 10 seconds +- name: Wait until port 1234 is offline but try every 10 seconds win_wait_for: port: 1234 state: absent diff --git a/lib/ansible/modules/windows/win_wait_for_process.py b/lib/ansible/modules/windows/win_wait_for_process.py index 53055a38119..8d1883de12c 100644 --- a/lib/ansible/modules/windows/win_wait_for_process.py +++ b/lib/ansible/modules/windows/win_wait_for_process.py @@ -112,22 +112,22 @@ elapsed: type: float sample: 3.14159265 matched_processes: - description: List of matched processes (either stopped or started) + description: List of matched processes (either stopped or started). returned: always type: complex contains: name: - description: The name of the matched process + description: The name of the matched process. returned: always type: str sample: svchost owner: - description: The owner of the matched process + description: The owner of the matched process. returned: when supported by PowerShell type: str sample: NT AUTHORITY\SYSTEM pid: - description: The PID of the matched process + description: The PID of the matched process. returned: always type: int sample: 7908 diff --git a/lib/ansible/modules/windows/win_wakeonlan.py b/lib/ansible/modules/windows/win_wakeonlan.py index 78ac14f827f..60439624af8 100644 --- a/lib/ansible/modules/windows/win_wakeonlan.py +++ b/lib/ansible/modules/windows/win_wakeonlan.py @@ -15,14 +15,17 @@ version_added: '2.4' short_description: Send a magic Wake-on-LAN (WoL) broadcast packet description: - The C(win_wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets. +- For non-Windows targets, use the M(wakeonlan) module instead. options: mac: description: - MAC address to send Wake-on-LAN broadcast packet for. + type: str required: yes broadcast: description: - Network broadcast address to use for broadcasting magic Wake-on-LAN packet. + type: str default: 255.255.255.255 port: description: diff --git a/lib/ansible/modules/windows/win_webpicmd.py b/lib/ansible/modules/windows/win_webpicmd.py index 7a5a6ef2503..fc0663b304d 100644 --- a/lib/ansible/modules/windows/win_webpicmd.py +++ b/lib/ansible/modules/windows/win_webpicmd.py @@ -27,6 +27,7 @@ options: name: description: - Name of the package to be installed. + type: str required: yes seealso: - module: win_package @@ -35,7 +36,7 @@ author: ''' EXAMPLES = r''' - # Install URLRewrite2. +- name: Install URLRewrite2. win_webpicmd: name: URLRewrite2 ''' diff --git a/lib/ansible/modules/windows/win_whoami.py b/lib/ansible/modules/windows/win_whoami.py index e81ff6107f5..9327043649b 100644 --- a/lib/ansible/modules/windows/win_whoami.py +++ b/lib/ansible/modules/windows/win_whoami.py @@ -33,7 +33,7 @@ author: ''' EXAMPLES = r''' -- name: get whoami information +- name: Get whoami information win_whoami: ''' diff --git a/lib/ansible/modules/windows/win_xml.py b/lib/ansible/modules/windows/win_xml.py index 40396a07ba0..6af8dee0d46 100644 --- a/lib/ansible/modules/windows/win_xml.py +++ b/lib/ansible/modules/windows/win_xml.py @@ -18,52 +18,55 @@ version_added: "2.7" short_description: Add XML fragment to an XML parent description: - Adds XML fragments formatted as strings to existing XML on remote servers. + - For non-Windows targets, use the M(xml) module instead. options: path: description: - The path of remote servers XML. + type: str required: true aliases: [ dest, file ] fragment: description: - The string representation of the XML fragment to be added. + type: str required: true aliases: [ xmlstring ] xpath: description: - The node of the remote server XML where the fragment will go. + type: str required: true backup: description: - Whether to backup the remote server's XML before applying the change. type: bool - default: 'no' + default: no type: description: - The type of XML you are working with. + type: str required: yes default: element - choices: - - element - - attribute - - text + choices: [ attribute, element, text ] attribute: description: - - The attribute name if the type is 'attribute'. Required if C(type=attribute). - + - The attribute name if the type is 'attribute'. + - Required if C(type=attribute). + type: str author: - Richard Levenberg (@richardcs) ''' EXAMPLES = r''' -# Apply our filter to Tomcat web.xml -- win_xml: +- name: Apply our filter to Tomcat web.xml + win_xml: path: C:\apache-tomcat\webapps\myapp\WEB-INF\web.xml fragment: 'MyFiltercom.example.MyFilter' xpath: '/*' -# Apply sslEnabledProtocols to Tomcat's server.xml -- win_xml: +- name: Apply sslEnabledProtocols to Tomcat's server.xml + win_xml: path: C:\Tomcat\conf\server.xml xpath: '//Server/Service[@name="Catalina"]/Connector[@port="9443"]' attribute: 'sslEnabledProtocols' @@ -73,17 +76,17 @@ EXAMPLES = r''' RETURN = r''' msg: - description: what was done + description: What was done. returned: always type: str sample: "xml added" err: - description: xml comparison exceptions + description: XML comparison exceptions. returned: always, for type element and -vvv or more type: list sample: attribute mismatch for actual=string backup: - description: name of the backup file, if created + description: Name of the backup file, if created. returned: changed type: str sample: C:\config.xml.19700101-000000