ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-08-23 06:21:43 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Windows: Add missing parameter types and doc fixes (#50232)

Browse source 
* 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 <dag@wieers.com>

* Update lib/ansible/modules/windows/win_credential.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/windows/win_domain_computer.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/windows/win_domain_user.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/windows/win_environment.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/windows/win_psexec.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/windows/win_uri.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/windows/win_wait_for.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Ensure docstrings are raw strings
This commit is contained in:
Dag Wieers 2019-01-03 17:50:44 +01:00 • committed by Alicia Cozine
commit d863027159
92 changed files with 982 additions and 716 deletions
Download patch file Download diff file Expand all files Collapse all files

9
lib/ansible/modules/windows/win_acl.py
View file

@ -22,20 +22,24 @@ options:
path: path:
description: description:
- The path to the file or directory. - The path to the file or directory.
type: str
required: yes required: yes
user: user:
description: description:
- User or Group to add specified rights to act on src file/folder or - User or Group to add specified rights to act on src file/folder or
registry key. registry key.
type: str
required: yes required: yes
state: state:
description: description:
- Specify whether to add C(present) or remove C(absent) the specified access rule. - Specify whether to add C(present) or remove C(absent) the specified access rule.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
type: type:
description: description:
- Specify whether to allow or deny the rights specified. - Specify whether to allow or deny the rights specified.
type: str
required: yes required: yes
choices: [ allow, deny ] choices: [ allow, deny ]
rights: rights:
@ -46,6 +50,7 @@ options:
FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx). 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 - 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). RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
type: str
required: yes required: yes
inherit: inherit:
description: description:
@ -55,12 +60,14 @@ options:
- For more information on the choices see MSDN InheritanceFlags enumeration - For more information on the choices see MSDN InheritanceFlags enumeration
at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx).
- Defaults to C(ContainerInherit, ObjectInherit) for Directories. - Defaults to C(ContainerInherit, ObjectInherit) for Directories.
type: str
choices: [ ContainerInherit, ObjectInherit ] choices: [ ContainerInherit, ObjectInherit ]
propagation: propagation:
description: description:
- Propagation flag on the ACL rules. - Propagation flag on the ACL rules.
- For more information on the choices see MSDN PropagationFlags enumeration - For more information on the choices see MSDN PropagationFlags enumeration
at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx). at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx).
type: str
choices: [ InheritOnly, None, NoPropagateInherit ] choices: [ InheritOnly, None, NoPropagateInherit ]
default: "None" default: "None"
notes: notes:
@ -92,7 +99,7 @@ EXAMPLES = r'''
inherit: ContainerInherit, ObjectInherit inherit: ContainerInherit, ObjectInherit
propagation: 'None' propagation: 'None'
- name: set registry key right - name: Set registry key right
win_acl: win_acl:
path: HKCU:\Bovine\Key path: HKCU:\Bovine\Key
user: BUILTIN\Users user: BUILTIN\Users

13
lib/ansible/modules/windows/win_acl_inheritance.py
View file

@ -26,17 +26,18 @@ options:
type: path type: path
state: state:
description: 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 ] choices: [ absent, present ]
default: absent default: absent
reorganize: reorganize:
description: description:
- For P(state) = I(absent), indicates if the inherited ACE's should be copied from the parent directory. This is necessary - For P(state) = I(absent), indicates if the inherited ACE's should be copied from the parent directory.
(in combination with removal) for a simple ACL instead of using multiple ACE deny entries. 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 - For P(state) = I(present), indicates if the inherited ACE's should be deduplicated compared to the parent directory.
of the ACL structure. This removes complexity of the ACL structure.
type: bool type: bool
default: 'no' default: no
seealso: seealso:
- module: win_acl - module: win_acl
author: author:

14
lib/ansible/modules/windows/win_audit_policy_system.py
View file

@ -9,7 +9,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: win_audit_policy_system module: win_audit_policy_system
short_description: Used to make changes to the system wide Audit Policy 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. - 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. - 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). - Changing this setting causes all subcategories to be adjusted to the defined I(audit_type).
type: str
subcategory: subcategory:
description: description:
- Single string value for the subcategory you would like to adjust the policy on. - 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. - Cannot be used with I(category). You must define one or the other.
type: str
audit_type: audit_type:
description: description:
- The type of event you would like to audit for. - The type of event you would like to audit for.
- Accepts a list. See examples. - Accepts a list. See examples.
required: yes
type: list type: list
required: yes
choices: [ failure, none, success ] choices: [ failure, none, success ]
notes: notes:
- It is recommended to take a backup of the policies before adjusting them for the first time. - It is recommended to take a backup of the policies before adjusting them for the first time.
@ -43,23 +45,23 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: enable failure auditing for the subcategory "File System" - name: Enable failure auditing for the subcategory "File System"
win_audit_policy_system: win_audit_policy_system:
subcategory: File System subcategory: File System
audit_type: failure 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: win_audit_policy_system:
category: Account logon events category: Account logon events
audit_type: success, failure audit_type: success, failure
- name: disable auditing for the subcategory "File System" - name: Disable auditing for the subcategory "File System"
win_audit_policy_system: win_audit_policy_system:
subcategory: File System subcategory: File System
audit_type: none audit_type: none
''' '''
RETURN = ''' RETURN = r'''
current_audit_policy: current_audit_policy:
description: details on the policy being targetted description: details on the policy being targetted
returned: always returned: always

24
lib/ansible/modules/windows/win_audit_rule.py
View file

@ -24,13 +24,14 @@ options:
description: description:
- Path to the file, folder, or registry key. - Path to the file, folder, or registry key.
- Registry paths should be in Powershell format, beginning with an abbreviation for the root - Registry paths should be in Powershell format, beginning with an abbreviation for the root
such as, 'hklm:\software'. such as, C(HKLM:\Software).
required: yes
type: path type: path
required: yes
aliases: [ dest, destination ] aliases: [ dest, destination ]
user: user:
description: description:
- The user or group to adjust rules for. - The user or group to adjust rules for.
type: str
required: yes required: yes
rights: rights:
description: description:
@ -39,8 +40,8 @@ options:
FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx). 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 - 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). RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
required: yes
type: list type: list
required: yes
inheritance_flags: inheritance_flags:
description: description:
- Defines what objects inside of a folder or registry key will inherit the settings. - 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 - For more information on the choices see MSDN PropagationFlags enumeration
at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx). at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx).
type: list type: list
default: "ContainerInherit,ObjectInherit"
choices: [ ContainerInherit, ObjectInherit ] choices: [ ContainerInherit, ObjectInherit ]
default: ContainerInherit,ObjectInherit
propagation_flags: propagation_flags:
description: description:
- Propagation flag on the audit rules. - Propagation flag on the audit rules.
- This value is ignored when the path type is a file. - This value is ignored when the path type is a file.
- For more information on the choices see MSDN PropagationFlags enumeration - For more information on the choices see MSDN PropagationFlags enumeration
at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx). at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx).
default: "None"
choices: [ None, InherityOnly, NoPropagateInherit ] choices: [ None, InherityOnly, NoPropagateInherit ]
default: "None"
audit_flags: audit_flags:
description: description:
- Defines whether to log on failure, success, or both. - Defines whether to log on failure, success, or both.
- To log both define as comma separated list "Success, Failure". - To log both define as comma separated list "Success, Failure".
required: yes
type: list type: list
required: yes
choices: [ Failure, Success ] choices: [ Failure, Success ]
state: state:
description: description:
- Whether the rule should be C(present) or C(absent). - Whether the rule should be C(present) or C(absent).
- For absent, only I(path), I(user), and I(state) are required. - For absent, only I(path), I(user), and I(state) are required.
- Specifying C(absent) will remove all rules matching the defined I(user). - Specifying C(absent) will remove all rules matching the defined I(user).
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
seealso: seealso:
@ -79,7 +81,7 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: add filesystem audit rule for a folder - name: Add filesystem audit rule for a folder
win_audit_rule: win_audit_rule:
path: C:\inetpub\wwwroot\website path: C:\inetpub\wwwroot\website
user: BUILTIN\Users user: BUILTIN\Users
@ -87,7 +89,7 @@ EXAMPLES = r'''
audit_flags: success,failure audit_flags: success,failure
inheritance_flags: ContainerInherit,ObjectInherit inheritance_flags: ContainerInherit,ObjectInherit
- name: add filesystem audit rule for a file - name: Add filesystem audit rule for a file
win_audit_rule: win_audit_rule:
path: C:\inetpub\wwwroot\website\web.config path: C:\inetpub\wwwroot\website\web.config
user: BUILTIN\Users user: BUILTIN\Users
@ -95,20 +97,20 @@ EXAMPLES = r'''
audit_flags: success,failure audit_flags: success,failure
inheritance_flags: None inheritance_flags: None
- name: add registry audit rule - name: Add registry audit rule
win_audit_rule: win_audit_rule:
path: HKLM:\software path: HKLM:\software
user: BUILTIN\Users user: BUILTIN\Users
rights: delete rights: delete
audit_flags: 'success' audit_flags: 'success'
- name: remove filesystem audit rule - name: Remove filesystem audit rule
win_audit_rule: win_audit_rule:
path: C:\inetpub\wwwroot\website path: C:\inetpub\wwwroot\website
user: BUILTIN\Users user: BUILTIN\Users
state: absent state: absent
- name: remove registry audit rule - name: Remove registry audit rule
win_audit_rule: win_audit_rule:
path: HKLM:\software path: HKLM:\software
user: BUILTIN\Users user: BUILTIN\Users

28
lib/ansible/modules/windows/win_certificate_store.py
View file

@ -32,6 +32,7 @@ options:
specified by I(thumbprint). specified by I(thumbprint).
- When exporting a certificate, if I(path) is a directory then the module - When exporting a certificate, if I(path) is a directory then the module
will fail, otherwise the file will be replaced if needed. will fail, otherwise the file will be replaced if needed.
type: str
choices: [ absent, exported, present ] choices: [ absent, exported, present ]
default: present default: present
path: path:
@ -45,6 +46,7 @@ options:
description: description:
- The thumbprint as a hex string to either export or remove. - The thumbprint as a hex string to either export or remove.
- See the examples for how to specify the thumbprint. - See the examples for how to specify the thumbprint.
type: str
store_name: store_name:
description: description:
- The store name to use when importing a certificate or searching for a - 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(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(TrustedPeople): The X.509 certificate store for directly trusted people and resources"
- "C(TrustedPublisher): The X.509 certificate store for directly trusted publishers" - "C(TrustedPublisher): The X.509 certificate store for directly trusted publishers"
default: My type: str
choices: choices:
- AddressBook - AddressBook
- AuthRoot - AuthRoot
@ -67,6 +69,7 @@ options:
- Root - Root
- TrustedPeople - TrustedPeople
- TrustedPublisher - TrustedPublisher
default: My
store_location: store_location:
description: description:
- The store location to use when importing a certificate or searching for a - 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). 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 - If the pkcs12 file has no password set or no password should be set on
the exported file, do not set this option. the exported file, do not set this option.
type: str
key_exportable: key_exportable:
description: description:
- Whether to allow the private key to be exported. - Whether to allow the private key to be exported.
@ -87,7 +91,7 @@ options:
the certificate and the private key cannot be exported. the certificate and the private key cannot be exported.
- Used when C(state=present) only. - Used when C(state=present) only.
type: bool type: bool
default: 'yes' default: yes
key_storage: key_storage:
description: description:
- Specifies where Windows will store the private key when it is imported. - 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. - 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) - See U(https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509keystorageflags.aspx)
for more details. for more details.
type: str
choices: [ default, machine, user ] choices: [ default, machine, user ]
default: default default: default
file_type: file_type:
@ -110,6 +115,7 @@ options:
the certificate and private key unlike the other options. the certificate and private key unlike the other options.
- When C(pkcs12) is set and the private key is not exportable or accessible - When C(pkcs12) is set and the private key is not exportable or accessible
by the current user, it will throw an exception. by the current user, it will throw an exception.
type: str
choices: [ der, pem, pkcs12 ] choices: [ der, pem, pkcs12 ]
default: der default: der
notes: notes:
@ -127,12 +133,12 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: import a certificate - name: Import a certificate
win_certificate_store: win_certificate_store:
path: C:\Temp\cert.pem path: C:\Temp\cert.pem
state: present state: present
- name: import pfx certificate that is password protected - name: Import pfx certificate that is password protected
win_certificate_store: win_certificate_store:
path: C:\Temp\cert.pfx path: C:\Temp\cert.pfx
state: present state: present
@ -140,7 +146,7 @@ EXAMPLES = r'''
become: yes become: yes
become_method: runas 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: win_certificate_store:
path: C:\Temp\cert.pfx path: C:\Temp\cert.pfx
state: present state: present
@ -149,30 +155,30 @@ EXAMPLES = r'''
vars: vars:
ansible_winrm_transport: credssp ansible_winrm_transport: credssp
- name: remove a certificate based on file thumbprint - name: Remove a certificate based on file thumbprint
win_certificate_store: win_certificate_store:
path: C:\Temp\cert.pem path: C:\Temp\cert.pem
state: absent state: absent
- name: remove a certificate based on thumbprint - name: Remove a certificate based on thumbprint
win_certificate_store: win_certificate_store:
thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27 thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27
state: absent 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: win_certificate_store:
thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27 thumbprint: BD7AF104CF1872BDB518D95C9534EA941665FD27
state: absent state: absent
store_location: CurrentUser store_location: CurrentUser
store_name: TrustedPublisher store_name: TrustedPublisher
- name: export certificate as der encoded file - name: Export certificate as der encoded file
win_certificate_store: win_certificate_store:
path: C:\Temp\cert.cer path: C:\Temp\cert.cer
state: exported state: exported
file_type: der file_type: der
- name: export certificate and key as pfx encoded file - name: Export certificate and key as pfx encoded file
win_certificate_store: win_certificate_store:
path: C:\Temp\cert.pfx path: C:\Temp\cert.pfx
state: exported state: exported
@ -182,7 +188,7 @@ EXAMPLES = r'''
become_method: runas become_method: runas
become_user: SYSTEM become_user: SYSTEM
- name: import certificate be used by IIS - name: Import certificate be used by IIS
win_certificate_store: win_certificate_store:
path: C:\Temp\cert.pfx path: C:\Temp\cert.pfx
file_type: pkcs12 file_type: pkcs12

35
lib/ansible/modules/windows/win_chocolatey.py
View file

@ -30,7 +30,7 @@ options:
- Use M(win_chocolatey_feature) with the name C(allowEmptyChecksums) to - Use M(win_chocolatey_feature) with the name C(allowEmptyChecksums) to
control this option globally. control this option globally.
type: bool type: bool
default: 'no' default: no
version_added: '2.2' version_added: '2.2'
allow_multiple: allow_multiple:
description: description:
@ -46,7 +46,7 @@ options:
- If I(state) is C(latest), the latest pre-release package will be - If I(state) is C(latest), the latest pre-release package will be
installed. installed.
type: bool type: bool
default: 'no' default: no
version_added: '2.6' version_added: '2.6'
architecture: architecture:
description: description:
@ -55,9 +55,7 @@ options:
- When setting C(x86), will ensure Chocolatey installs the x86 package - When setting C(x86), will ensure Chocolatey installs the x86 package
even when on an x64 bit OS. even when on an x64 bit OS.
type: str type: str
choices: choices: [ default, x86 ]
- default
- x86
default: default default: default
version_added: '2.7' version_added: '2.7'
force: force:
@ -66,7 +64,7 @@ options:
- Using I(force) will cause Ansible to always report that a change was - Using I(force) will cause Ansible to always report that a change was
made. made.
type: bool type: bool
default: 'no' default: no
install_args: install_args:
description: description:
- Arguments to pass to the native installer. - Arguments to pass to the native installer.
@ -80,20 +78,20 @@ options:
- Use M(win_chocolatey_feature) with the name C(checksumFiles) to control - Use M(win_chocolatey_feature) with the name C(checksumFiles) to control
this option globally. this option globally.
type: bool type: bool
default: 'no' default: no
version_added: '2.2' version_added: '2.2'
ignore_dependencies: ignore_dependencies:
description: description:
- Ignore dependencies, only install/upgrade the package itself. - Ignore dependencies, only install/upgrade the package itself.
type: bool type: bool
default: 'no' default: no
version_added: '2.1' version_added: '2.1'
name: name:
description: description:
- Name of the package(s) to be installed. - Name of the package(s) to be installed.
- Set to C(all) to run the action on all the installed packages. - Set to C(all) to run the action on all the installed packages.
required: yes
type: list type: list
required: yes
package_params: package_params:
description: description:
- Parameters to pass to the package. - Parameters to pass to the package.
@ -102,8 +100,7 @@ options:
- Before Ansible 2.7, this option was just I(params). - Before Ansible 2.7, this option was just I(params).
type: str type: str
version_added: '2.1' version_added: '2.1'
aliases: aliases: [ params ]
- params
proxy_url: proxy_url:
description: description:
- Proxy URL used to install chocolatey and the package. - 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 - Do not run I(chocolateyInstall.ps1) or I(chocolateyUninstall.ps1) scripts
when installing a package. when installing a package.
type: bool type: bool
default: 'no' default: no
version_added: '2.4' version_added: '2.4'
source: source:
description: description:
@ -172,22 +169,16 @@ options:
- When C(latest), will ensure the package is installed to the latest - When C(latest), will ensure the package is installed to the latest
available version. available version.
- When C(reinstalled), will uninstall and reinstall the package. - When C(reinstalled), will uninstall and reinstall the package.
choices:
- absent
- downgrade
- latest
- present
- reinstalled
default: present
type: str type: str
choices: [ absent, downgrade, latest, present, reinstalled ]
default: present
timeout: timeout:
description: description:
- The time to allow chocolatey to finish before timing out. - The time to allow chocolatey to finish before timing out.
type: int type: int
default: 2700 default: 2700
version_added: '2.3' version_added: '2.3'
aliases: aliases: [ execution_timeout ]
- execution_timeout
validate_certs: validate_certs:
description: description:
- Used when downloading the Chocolatey install script if Chocolatey is not - 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 - This should only be used on personally controlled sites using self-signed
certificate. certificate.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.7' version_added: '2.7'
version: version:
description: description:

11
lib/ansible/modules/windows/win_chocolatey_config.py
View file

@ -23,15 +23,15 @@ options:
valid configuration settings that can be changed. valid configuration settings that can be changed.
- Any config values that contain encrypted values like a password are not - Any config values that contain encrypted values like a password are not
idempotent as the plaintext value cannot be read. idempotent as the plaintext value cannot be read.
type: str
required: yes required: yes
state: state:
description: description:
- When C(absent), it will ensure the setting is unset or blank. - 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 - When C(present), it will ensure the setting is set to the value of
I(value). I(value).
choices: type: str
- absent choices: [ absent, present ]
- present
default: present default: present
value: value:
description: description:
@ -39,6 +39,7 @@ options:
setting. setting.
- Cannot be null or an empty string, use C(state=absent) to unset a config - Cannot be null or an empty string, use C(state=absent) to unset a config
value instead. value instead.
type: str
seealso: seealso:
- module: win_chocolatey - module: win_chocolatey
- module: win_chocolatey_facts - module: win_chocolatey_facts
@ -49,13 +50,13 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: set the cache location - name: Set the cache location
win_chocolatey_config: win_chocolatey_config:
name: cacheLocation name: cacheLocation
state: present state: present
value: D:\chocolatey_temp value: D:\chocolatey_temp
- name: unset the cache location - name: Unset the cache location
win_chocolatey_config: win_chocolatey_config:
name: cacheLocation name: cacheLocation
state: absent state: absent

10
lib/ansible/modules/windows/win_chocolatey_feature.py
View file

@ -21,14 +21,14 @@ options:
- The name of the feature to manage. - The name of the feature to manage.
- Run C(choco.exe feature list) to get a list of features that can be - Run C(choco.exe feature list) to get a list of features that can be
managed. managed.
type: str
required: yes required: yes
state: state:
description: description:
- When C(disabled) then the feature will be disabled. - When C(disabled) then the feature will be disabled.
- When C(enabled) then the feature will be enabled. - When C(enabled) then the feature will be enabled.
choices: type: str
- disabled choices: [ disabled, enabled ]
- enabled
default: enabled default: enabled
seealso: seealso:
- module: win_chocolatey - module: win_chocolatey
@ -40,12 +40,12 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: disable file checksum matching - name: Disable file checksum matching
win_chocolatey_feature: win_chocolatey_feature:
name: checksumFiles name: checksumFiles
state: disabled state: disabled
- name: stop Chocolatey on the first package failure - name: Stop Chocolatey on the first package failure
win_chocolatey_feature: win_chocolatey_feature:
name: stopOnFirstPackageFailure name: stopOnFirstPackageFailure
state: enabled state: enabled

17
lib/ansible/modules/windows/win_chocolatey_source.py
View file

@ -21,24 +21,25 @@ options:
description: description:
- Makes the source visible to Administrators only. - Makes the source visible to Administrators only.
- Requires Chocolatey >= 0.10.8. - 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 type: bool
allow_self_service: allow_self_service:
description: description:
- Allow the source to be used with self-service - Allow the source to be used with self-service
- Requires Chocolatey >= 0.10.4. - 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 type: bool
bypass_proxy: bypass_proxy:
description: description:
- Bypass the proxy when using this source. - Bypass the proxy when using this source.
- Requires Chocolatey >= 0.10.4. - 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 type: bool
certificate: certificate:
description: description:
- The path to a .pfx file to use for X509 authenticated feeds. - The path to a .pfx file to use for X509 authenticated feeds.
- Requires Chocolatey >= 0.9.10. - Requires Chocolatey >= 0.9.10.
type: str
certificate_password: certificate_password:
description: description:
- The password for I(certificate) if required. - The password for I(certificate) if required.
@ -97,18 +98,18 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: remove the default public source - name: Remove the default public source
win_chocolatey_source: win_chocolatey_source:
name: chocolatey name: chocolatey
state: absent state: absent
- name: add new internal source - name: Add new internal source
win_chocolatey_source: win_chocolatey_source:
name: internal repo name: internal repo
state: present state: present
source: http://chocolatey-server/chocolatey source: http://chocolatey-server/chocolatey
- name: create HTTP source with credentials - name: Create HTTP source with credentials
win_chocolatey_source: win_chocolatey_source:
name: internal repo name: internal repo
state: present state: present
@ -116,9 +117,9 @@ EXAMPLES = r'''
source_username: username source_username: username
source_password: password source_password: password
- name: disable Chocolatey source - name: Disable Chocolatey source
win_chocolatey_source: win_chocolatey_source:
name: chocoaltey name: chocolatey
state: disabled state: disabled
''' '''

5
lib/ansible/modules/windows/win_command.py
View file

@ -25,6 +25,7 @@ options:
description: description:
- The C(win_command) module takes a free form command to run. - The C(win_command) module takes a free form command to run.
- There is no parameter actually named 'free form'. See the examples! - There is no parameter actually named 'free form'. See the examples!
type: str
required: yes required: yes
creates: creates:
description: description:
@ -41,6 +42,7 @@ options:
stdin: stdin:
description: description:
- Set the stdin of the command directly to the specified value. - Set the stdin of the command directly to the specified value.
type: str
version_added: '2.5' version_added: '2.5'
notes: notes:
- If you want to run a command through a shell (say you are using C(<), - If you want to run a command through a shell (say you are using C(<),
@ -49,7 +51,6 @@ notes:
environment. 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 - 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. exist, use this.
- For non-Windows targets, use the M(command) module instead.
seealso: seealso:
- module: command - module: command
- module: psexec - module: psexec
@ -82,7 +83,7 @@ msg:
description: changed description: changed
returned: always returned: always
type: bool type: bool
sample: True sample: true
start: start:
description: The command execution start time description: The command execution start time
returned: always returned: always

33
lib/ansible/modules/windows/win_copy.py
View file

@ -21,19 +21,21 @@ options:
content: content:
description: description:
- When used instead of C(src), sets the contents of a file directly to the - 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 specified value.
formatting please switch to the template module. - This is for simple values, for anything complex or with formatting please
switch to the M(template) module.
type: str
version_added: '2.3' version_added: '2.3'
decrypt: decrypt:
description: description:
- This option controls the autodecryption of source files using vault. - This option controls the autodecryption of source files using vault.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.5' version_added: '2.5'
dest: dest:
description: description:
- Remote absolute path where the file should be copied to. If src is a - Remote absolute path where the file should be copied to.
directory, this must be a directory too. - If C(src) is a directory, this must be a directory too.
- Use \ for path separators or \\ when in "double quotes". - Use \ for path separators or \\ when in "double quotes".
- If C(dest) ends with \ then source or the contents of source will be - If C(dest) ends with \ then source or the contents of source will be
copied to the directory without renaming. 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 - If set to C(no), no checksuming of the content is performed which can
help improve performance on larger files. help improve performance on larger files.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.3' version_added: '2.3'
local_follow: local_follow:
description: description:
- This flag indicates that filesystem links in the source tree, if they - This flag indicates that filesystem links in the source tree, if they
exist, should be followed. exist, should be followed.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
remote_src: remote_src:
description: description:
- If C(no), it will search for src at originating/master machine. - 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. - If C(yes), it will go to the remote/target machine for the src.
type: bool type: bool
default: 'no' default: no
version_added: '2.3' version_added: '2.3'
src: src:
description: description:
@ -79,10 +81,9 @@ options:
end with "/", the directory itself with all contents is copied. 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 - If path is a file and dest ends with "\", the file is copied to the
folder with the same filename. folder with the same filename.
required: yes
type: path type: path
required: yes
notes: notes:
- For non-Windows targets, use the M(copy) module instead.
- Currently win_copy does not support copying symbolic links from both local to - Currently win_copy does not support copying symbolic links from both local to
remote and remote to remote. remote and remote to remote.
- It is recommended that backslashes C(\) are used instead of C(/) when dealing - It is recommended that backslashes C(\) are used instead of C(/) when dealing
@ -141,32 +142,32 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
dest: dest:
description: destination file/path description: Destination file/path.
returned: changed returned: changed
type: str type: str
sample: C:\Temp\ sample: C:\Temp\
src: 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 returned: changed
type: str type: str
sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
checksum: 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 returned: success, src is a file
type: str type: str
sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827 sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827
size: size:
description: size of the target, after execution description: Size of the target, after execution.
returned: changed, src is a file returned: changed, src is a file
type: int type: int
sample: 1220 sample: 1220
operation: 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 returned: success
type: str type: str
sample: file_copy sample: file_copy
original_basename: original_basename:
description: basename of the copied file description: Basename of the copied file.
returned: changed, src is a file returned: changed, src is a file
type: str type: str
sample: foo.txt sample: foo.txt

33
lib/ansible/modules/windows/win_credential.py
View file

@ -36,7 +36,8 @@ options:
- The key for the attribute. - The key for the attribute.
- This is not a unique identifier as multiple attributes can have the - This is not a unique identifier as multiple attributes can have the
same key. same key.
required: True type: str
required: true
data: data:
description: description:
- The value for the attribute. - The value for the attribute.
@ -48,9 +49,7 @@ options:
- If C(base64), I(data) is a base64 string that is base64 decoded to - If C(base64), I(data) is a base64 string that is base64 decoded to
bytes. bytes.
type: str type: str
choices: choices: [ base64, text ]
- base64
- text
default: text default: text
comment: comment:
description: description:
@ -66,8 +65,8 @@ options:
- See C(TargetName) in U(https://docs.microsoft.com/en-us/windows/desktop/api/wincred/ns-wincred-_credentiala) - 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. for more details on what this value can be.
- This is used with I(type) to produce a unique credential. - This is used with I(type) to produce a unique credential.
required: True
type: str type: str
required: true
persistence: persistence:
description: description:
- Defines the persistence of the credential. - 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 - 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. the same domain user when running on other hosts and not just localhost.
type: str type: str
choices: choices: [ enterprise, local ]
- enterprise
- local
default: local default: local
secret: secret:
description: description:
@ -95,9 +92,7 @@ options:
- If C(base64), I(secret) is a base64 string that is base64 decoded to - If C(base64), I(secret) is a base64 string that is base64 decoded to
bytes. bytes.
type: str type: str
choices: choices: [ base64, text ]
- base64
- text
default: text default: text
state: state:
description: description:
@ -106,9 +101,7 @@ options:
- When C(present), the credential specified by I(name) and I(type) is - When C(present), the credential specified by I(name) and I(type) is
removed. removed.
type: str type: str
choices: choices: [ absent, present ]
- absent
- present
default: present default: present
type: type:
description: description:
@ -120,13 +113,9 @@ options:
particular authentication package. particular authentication package.
- It is recommended to use a C(domain) type as only authentication - It is recommended to use a C(domain) type as only authentication
providers can access the secret. providers can access the secret.
required: True
type: str type: str
choices: required: true
- domain_password choices: [ domain_certificate, domain_password, generic_certificate, generic_password ]
- domain_certificate
- generic_password
- generic_certificate
update_secret: update_secret:
description: description:
- When C(always), the secret will always be updated if they differ. - 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 - If the secret cannot be retrieved and this is set to C(always), the
module will always result in a change. module will always result in a change.
type: str type: str
choices: choices: [ always, on_create ]
- always
- on_create
default: always default: always
username: username:
description: description:

17
lib/ansible/modules/windows/win_defrag.py
View file

@ -31,16 +31,19 @@ options:
freespace_consolidation: freespace_consolidation:
description: description:
- Perform free space consolidation on the specified volumes. - Perform free space consolidation on the specified volumes.
type: bool
default: no
priority: priority:
description: description:
- Run the operation at low or normal priority. - Run the operation at low or normal priority.
type: str
choices: [ low, normal ] choices: [ low, normal ]
default: low default: low
parallel: parallel:
description: description:
- Run the operation on each volume in parallel in the background. - Run the operation on each volume in parallel in the background.
type: bool type: bool
default: 'no' default: no
author: author:
- Dag Wieers (@dagwieers) - Dag Wieers (@dagwieers)
''' '''
@ -66,27 +69,27 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
cmd: cmd:
description: The complete command line used by the module description: The complete command line used by the module.
returned: always returned: always
type: str type: str
sample: defrag.exe /C /V sample: defrag.exe /C /V
rc: rc:
description: The return code for the command description: The return code for the command.
returned: always returned: always
type: int type: int
sample: 0 sample: 0
stdout: stdout:
description: The standard output from the command description: The standard output from the command.
returned: always returned: always
type: str type: str
sample: Success. sample: Success.
stderr: stderr:
description: The error output from the command description: The error output from the command.
returned: always returned: always
type: str type: str
sample: sample:
msg: msg:
description: Possible error message on failure description: Possible error message on failure.
returned: failed returned: failed
type: str type: str
sample: Command 'defrag.exe' not found in $env:PATH. sample: Command 'defrag.exe' not found in $env:PATH.
@ -94,5 +97,5 @@ changed:
description: Whether or not any changes were made. description: Whether or not any changes were made.
returned: always returned: always
type: bool type: bool
sample: True sample: true
''' '''

36
lib/ansible/modules/windows/win_disk_facts.py
View file

@ -41,7 +41,7 @@ EXAMPLES = r'''
disk: '{{ ansible_facts.disks|selectattr("system_disk")|first }}' disk: '{{ ansible_facts.disks|selectattr("system_disk")|first }}'
# Show disk size in Gibibytes # 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) disksize_gib: '{{ (disk.size/1024|pow(3))|round|int }} GiB' # returns "224 GiB" (value in GiB)
# Show disk size in Gigabytes # Show disk size in Gigabytes
@ -108,22 +108,22 @@ ansible_facts:
description: Read only status of the particular disk. description: Read only status of the particular disk.
returned: always returned: always
type: bool type: bool
sample: True sample: true
bootable: bootable:
description: Information whether the particular disk is a bootable disk. description: Information whether the particular disk is a bootable disk.
returned: always returned: always
type: bool type: bool
sample: False sample: false
system_disk: system_disk:
description: Information whether the particular disk is a system disk. description: Information whether the particular disk is a system disk.
returned: always returned: always
type: bool type: bool
sample: True sample: true
clustered: clustered:
description: Information whether the particular disk is clustered (part of a failover cluster). description: Information whether the particular disk is clustered (part of a failover cluster).
returned: always returned: always
type: bool type: bool
sample: False sample: false
manufacturer: manufacturer:
description: Manufacturer of the particular disk. description: Manufacturer of the particular disk.
returned: always returned: always
@ -194,7 +194,7 @@ ansible_facts:
description: Information whether the particular partition has a default drive letter or not. 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" returned: if partition_style property of the particular disk has value "GPT"
type: bool type: bool
sample: True sample: true
mbr_type: mbr_type:
description: mbr type of the particular partition. description: mbr type of the particular partition.
returned: if partition_style property of the particular disk has value "MBR" 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. description: Information whether the particular partition is an active partition or not.
returned: if partition_style property of the particular disk has value "MBR" returned: if partition_style property of the particular disk has value "MBR"
type: bool type: bool
sample: True sample: true
drive_letter: drive_letter:
description: Drive letter of the particular partition. description: Drive letter of the particular partition.
returned: if existent returned: if existent
@ -224,12 +224,12 @@ ansible_facts:
description: Information whether the particular partition is hidden or not. description: Information whether the particular partition is hidden or not.
returned: always returned: always
type: bool type: bool
sample: True sample: true
shadow_copy: shadow_copy:
description: Information whether the particular partition is a shadow copy of another partition. description: Information whether the particular partition is a shadow copy of another partition.
returned: always returned: always
type: bool type: bool
sample: False sample: false
guid: guid:
description: GUID of the particular partition. description: GUID of the particular partition.
returned: if existent returned: if existent
@ -383,7 +383,7 @@ ansible_facts:
description: Information whether the particular physical disk can be added to a storage pool. description: Information whether the particular physical disk can be added to a storage pool.
returned: always returned: always
type: bool type: bool
sample: False sample: false
cannot_pool_reason: cannot_pool_reason:
description: Information why the particular physical disk can not be added to a storage pool. description: Information why the particular physical disk can not be added to a storage pool.
returned: if can_pool property has value false 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. description: Information whether indication is enabled for the particular physical disk.
returned: always returned: always
type: bool type: bool
sample: True sample: true
partial: partial:
description: Information whether the particular physical disk is partial. description: Information whether the particular physical disk is partial.
returned: always returned: always
type: bool type: bool
sample: False sample: false
serial_number: serial_number:
description: Serial number of the particular physical disk. description: Serial number of the particular physical disk.
returned: always returned: always
@ -507,27 +507,27 @@ ansible_facts:
description: Information whether deduplication is enabled for the particular virtual disk. description: Information whether deduplication is enabled for the particular virtual disk.
returned: always returned: always
type: bool type: bool
sample: True sample: true
enclosure_aware: enclosure_aware:
description: Information whether the particular virtual disk is enclosure aware. description: Information whether the particular virtual disk is enclosure aware.
returned: always returned: always
type: bool type: bool
sample: False sample: false
manual_attach: manual_attach:
description: Information whether the particular virtual disk is manual attached. description: Information whether the particular virtual disk is manual attached.
returned: always returned: always
type: bool type: bool
sample: True sample: true
snapshot: snapshot:
description: Information whether the particular virtual disk is a snapshot. description: Information whether the particular virtual disk is a snapshot.
returned: always returned: always
type: bool type: bool
sample: False sample: false
tiered: tiered:
description: Information whether the particular virtual disk is tiered. description: Information whether the particular virtual disk is tiered.
returned: always returned: always
type: bool type: bool
sample: True sample: true
physical_sector_size: physical_sector_size:
description: Physical sector size in bytes of the particular virtual disk. description: Physical sector size in bytes of the particular virtual disk.
returned: always returned: always
@ -567,7 +567,7 @@ ansible_facts:
description: Information whether the particular virtual disk requests no single point of failure. description: Information whether the particular virtual disk requests no single point of failure.
returned: always returned: always
type: bool type: bool
sample: True sample: true
resiliency_setting_name: resiliency_setting_name:
description: Type of the physical disk redundancy of the particular virtual disk. description: Type of the physical disk redundancy of the particular virtual disk.
returned: always returned: always

37
lib/ansible/modules/windows/win_disk_image.py
View file

@ -8,41 +8,31 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
module: win_disk_image module: win_disk_image
short_description: Manage ISO/VHD/VHDX mounts on Windows hosts short_description: Manage ISO/VHD/VHDX mounts on Windows hosts
version_added: '2.3' version_added: '2.3'
description: description:
- Manages mount behavior for a specified ISO, VHD, or VHDX image on a Windows host. When C(state) is C(present), - 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 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: options:
image_path: image_path:
description: description:
- Path to an ISO, VHD, or VHDX image on the target Windows host (the file cannot reside on a network share) - 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 required: yes
state: state:
description: description:
- Whether the image should be present as a drive-letter mount or not. - Whether the image should be present as a drive-letter mount or not.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
author: author:
- Matt Davis (@nitzmahone) - 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''' EXAMPLES = r'''
# Run installer from mounted ISO, then unmount # Run installer from mounted ISO, then unmount
- name: Ensure an ISO is mounted - name: Ensure an ISO is mounted
@ -51,14 +41,27 @@ EXAMPLES = r'''
state: present state: present
register: disk_image_out register: disk_image_out
- name: Run installer from mounted iso - name: Run installer from mounted ISO
win_package: win_package:
path: '{{ disk_image_out.mount_paths[0] }}setup\setup.exe' path: '{{ disk_image_out.mount_paths[0] }}setup\setup.exe'
product_id: 35a4e767-0161-46b0-979f-e61f282fee21 product_id: 35a4e767-0161-46b0-979f-e61f282fee21
state: present state: present
- name: Unmount iso - name: Unmount ISO
win_disk_image: win_disk_image:
image_path: C:\install.iso image_path: C:\install.iso
state: absent 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:\' ]
'''

6
lib/ansible/modules/windows/win_dns_client.py
View file

@ -19,12 +19,14 @@ options:
adapter_names: adapter_names:
description: description:
- Adapter name or list of adapter names for which to manage DNS settings ('*' is supported as a wildcard value). - 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 required: yes
ipv4_addresses: ipv4_addresses:
description: description:
- Single or ordered list of DNS server IPv4 addresses to configure for lookup. An empty list will configure the adapter to use the - 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. DHCP-assigned values on connections where DHCP is enabled, or disable DNS lookup on statically-configured connections.
type: str
required: yes required: yes
notes: 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 - 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: [] ipv4_addresses: []
''' '''
RETURN = ''' RETURN = r'''
''' '''

4
lib/ansible/modules/windows/win_domain.py
View file

@ -20,8 +20,8 @@ options:
dns_domain_name: dns_domain_name:
description: description:
- The DNS name of the domain which should exist and be reachable or reside on the target Windows host. - The DNS name of the domain which should exist and be reachable or reside on the target Windows host.
required: yes
type: str type: str
required: yes
domain_netbios_name: domain_netbios_name:
description: description:
- The NetBIOS name for the root domain in the new forest. - The NetBIOS name for the root domain in the new forest.
@ -32,8 +32,8 @@ options:
safe_mode_password: safe_mode_password:
description: description:
- Safe mode password for the domain controller. - Safe mode password for the domain controller.
required: yes
type: str type: str
required: yes
database_path: database_path:
description: description:
- The path to a directory on a fixed disk of the Windows host where the - The path to a directory on a fixed disk of the Windows host where the

61
lib/ansible/modules/windows/win_domain_computer.py
View file

@ -4,13 +4,11 @@
# Copyright: (c) 2017, AMTEGA - Xunta de Galicia # 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) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
ANSIBLE_METADATA = {'metadata_version': '1.1', ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = r'''
DOCUMENTATION = '''
--- ---
module: win_domain_computer module: win_domain_computer
short_description: Manage computers in Active Directory short_description: Manage computers in Active Directory
@ -22,49 +20,55 @@ version_added: '2.6'
options: options:
name: name:
description: description:
- Specifies the name of the object. This parameter sets the Name property - Specifies the name of the object.
of the Active Directory object. The LDAP display name (ldapDisplayName) - This parameter sets the Name property of the Active Directory object.
of this property is name. - The LDAP display name (ldapDisplayName) of this property is name.
type: str
required: true required: true
sam_account_name: sam_account_name:
description: description:
- Specifies the Security Account Manager (SAM) account name of the - Specifies the Security Account Manager (SAM) account name of the
computer. It maximum is 256 characters, 15 is advised for older computer.
operating systems compatibility. The LDAP display name - It maximum is 256 characters, 15 is advised for older
(ldapDisplayName) for this property is sAMAccountName. If ommitted the operating systems compatibility.
value is the same as C(name). - The LDAP display name (ldapDisplayName) for this property is sAMAccountName.
Note. All computer SAMAccountNames needs to end with a $. - If ommitted the value is the same as C(name).
- Note that all computer SAMAccountNames need to end with a $.
type: str
enabled: enabled:
description: description:
- Specifies if an account is enabled. An enabled account requires a - Specifies if an account is enabled.
password. This parameter sets the Enabled property for an account - An enabled account requires a password.
object. This parameter also sets the ADS_UF_ACCOUNTDISABLE flag of the - 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. Active Directory User Account Control (UAC) attribute.
type: bool type: bool
default: 'yes' default: yes
ou: ou:
description: description:
- Specifies the X.500 path of the Organizational Unit (OU) or container - Specifies the X.500 path of the Organizational Unit (OU) or container
where the new object is created. Required when I(state=present). where the new object is created. Required when I(state=present).
type: str
description: description:
description: description:
- Specifies a description of the object. This parameter sets the value - Specifies a description of the object.
of the Description property for the object. The LDAP display name - This parameter sets the value of the Description property for the object.
(ldapDisplayName) for this property is description. - The LDAP display name (ldapDisplayName) for this property is description.
type: str
default: '' default: ''
dns_hostname: dns_hostname:
description: description:
- Specifies the fully qualified domain name (FQDN) of the computer. This - Specifies the fully qualified domain name (FQDN) of the computer.
parameter sets the DNSHostName property for a computer object. The LDAP - This parameter sets the DNSHostName property for a computer object.
display name for this property is dNSHostName. Required when - The LDAP display name for this property is dNSHostName.
I(state=present). - Required when I(state=present).
type: str
state: state:
description: description:
- Specified whether the computer should be C(present) or C(absent) in - Specified whether the computer should be C(present) or C(absent) in
Active Directory. Active Directory.
choices: type: str
- present choices: [ absent, present ]
- absent
default: present default: present
seealso: seealso:
- module: win_domain - module: win_domain
@ -72,10 +76,11 @@ seealso:
- module: win_domain_group - module: win_domain_group
- module: win_domain_membership - module: win_domain_membership
- module: win_domain_user - 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 - name: Add linux computer to Active Directory OU using a windows machine
win_domain_computer: win_domain_computer:
name: one_linux_server.my_org.local name: one_linux_server.my_org.local
@ -94,5 +99,5 @@ EXAMPLES = '''
delegate_to: my_windows_bridge.my_org.local delegate_to: my_windows_bridge.my_org.local
''' '''
RETURN = ''' RETURN = r'''
''' '''

30
lib/ansible/modules/windows/win_domain_controller.py
View file

@ -14,45 +14,48 @@ module: win_domain_controller
short_description: Manage domain controller/member server state for a Windows host short_description: Manage domain controller/member server state for a Windows host
version_added: '2.3' version_added: '2.3'
description: description:
- Ensure that a Windows Server 2012+ host is configured as a domain controller or demoted to member server. This module may require - Ensure that a Windows Server 2012+ host is configured as a domain controller or demoted to member server.
subsequent use of the M(win_reboot) action if changes are made. - This module may require subsequent use of the M(win_reboot) action if changes are made.
options: options:
dns_domain_name: dns_domain_name:
description: description:
- When C(state) is C(domain_controller), the DNS name of the domain for which the targeted Windows host should be a DC. - 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: domain_admin_user:
description: description:
- Username of a domain admin for the target domain (necessary to promote or demote a domain controller). - Username of a domain admin for the target domain (necessary to promote or demote a domain controller).
type: str
required: true required: true
domain_admin_password: domain_admin_password:
description: description:
- Password for the specified C(domain_admin_user). - Password for the specified C(domain_admin_user).
type: str
required: true required: true
safe_mode_password: safe_mode_password:
description: description:
- Safe mode password for the domain controller (required when C(state) is C(domain_controller)). - Safe mode password for the domain controller (required when C(state) is C(domain_controller)).
type: str
local_admin_password: local_admin_password:
description: description:
- Password to be assigned to the local C(Administrator) user (required when C(state) is C(member_server)). - Password to be assigned to the local C(Administrator) user (required when C(state) is C(member_server)).
type: str
read_only: read_only:
description: description:
- Whether to install the domain controller as a read only replica for an - Whether to install the domain controller as a read only replica for an existing domain.
existing domain.
type: bool type: bool
default: 'no' default: no
version_added: '2.5' version_added: '2.5'
site_name: site_name:
description: description:
- Specifies the name of an existing site where you can place the new - Specifies the name of an existing site where you can place the new domain controller.
domain controller.
- This option is required when I(read_only) is C(yes). - This option is required when I(read_only) is C(yes).
type: str
version_added: '2.5' version_added: '2.5'
state: state:
description: description:
- Whether the target host should be a domain controller or a member server. - Whether the target host should be a domain controller or a member server.
choices: type: str
- domain_controller choices: [ domain_controller, member_server ]
- member_server
database_path: database_path:
description: description:
- The path to a directory on a fixed disk of the Windows host where the - The path to a directory on a fixed disk of the Windows host where the
@ -77,17 +80,16 @@ author:
- Matt Davis (@nitzmahone) - Matt Davis (@nitzmahone)
''' '''
RETURN = ''' RETURN = r'''
reboot_required: reboot_required:
description: True if changes were made that require a reboot. description: True if changes were made that require a reboot.
returned: always returned: always
type: bool type: bool
sample: true sample: true
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: ensure a server is a domain controller - name: Ensure a server is a domain controller
win_domain_controller: win_domain_controller:
dns_domain_name: ansible.vagrant dns_domain_name: ansible.vagrant
domain_admin_user: testguy@ansible.vagrant domain_admin_user: testguy@ansible.vagrant
@ -109,7 +111,7 @@ EXAMPLES = r'''
state: member_server state: member_server
log_path: C:\ansible_win_domain_controller.txt 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: win_domain_controller:
dns_domain_name: ansible.vagrant dns_domain_name: ansible.vagrant
domain_admin_user: testguy@ansible.vagrant domain_admin_user: testguy@ansible.vagrant

22
lib/ansible/modules/windows/win_domain_group.py
View file

@ -23,32 +23,39 @@ options:
- This can be used to set custom attributes that are not exposed as module - This can be used to set custom attributes that are not exposed as module
parameters, e.g. C(mail). parameters, e.g. C(mail).
- See the examples on how to format this parameter. - See the examples on how to format this parameter.
type: dict
category: category:
description: description:
- The category of the group, this is the value to assign to the LDAP - The category of the group, this is the value to assign to the LDAP
C(groupType) attribute. C(groupType) attribute.
- If a new group is created then C(security) will be used by default. - If a new group is created then C(security) will be used by default.
type: str
choices: [ distribution, security ] choices: [ distribution, security ]
description: description:
description: description:
- The value to be assigned to the LDAP C(description) attribute. - The value to be assigned to the LDAP C(description) attribute.
type: str
display_name: display_name:
description: description:
- The value to assign to the LDAP C(displayName) attribute. - The value to assign to the LDAP C(displayName) attribute.
type: str
domain_username: domain_username:
description: description:
- The username to use when interacting with AD. - The username to use when interacting with AD.
- If this is not set then the user Ansible used to log in with will be - If this is not set then the user Ansible used to log in with will be
used instead. used instead.
type: str
domain_password: domain_password:
description: description:
- The password for C(username). - The password for C(username).
type: str
domain_server: domain_server:
description: description:
- Specifies the Active Directory Domain Services instance to connect to. - Specifies the Active Directory Domain Services instance to connect to.
- Can be in the form of an FQDN or NetBIOS name. - 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 - If not specified then the value is based on the domain of the computer
running PowerShell. running PowerShell.
type: str
version_added: '2.5' version_added: '2.5'
ignore_protection: ignore_protection:
description: description:
@ -57,24 +64,26 @@ options:
- The module will fail if one of these actions need to occur and this value - The module will fail if one of these actions need to occur and this value
is set to C(no). is set to C(no).
type: bool type: bool
default: 'no' default: no
managed_by: managed_by:
description: description:
- The value to be assigned to the LDAP C(managedBy) attribute. - The value to be assigned to the LDAP C(managedBy) attribute.
- This value can be in the forms C(Distinguished Name), C(objectGUID), - This value can be in the forms C(Distinguished Name), C(objectGUID),
C(objectSid) or C(sAMAccountName), see examples for more details. C(objectSid) or C(sAMAccountName), see examples for more details.
type: str
name: name:
description: description:
- The name of the group to create, modify or remove. - The name of the group to create, modify or remove.
- This value can be in the forms C(Distinguished Name), C(objectGUID), - This value can be in the forms C(Distinguished Name), C(objectGUID),
C(objectSid) or C(sAMAccountName), see examples for more details. C(objectSid) or C(sAMAccountName), see examples for more details.
type: str
required: yes required: yes
organizational_unit: organizational_unit:
description: description:
- The full LDAP path to create or move the group to. - 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 - This should be the path to the parent object to create or move the group to.
to.
- See examples for details of how this path is formed. - See examples for details of how this path is formed.
type: str
aliases: [ ou, path ] aliases: [ ou, path ]
protect: protect:
description: description:
@ -86,17 +95,18 @@ options:
description: description:
- The scope of the group. - The scope of the group.
- If C(state=present) and the group doesn't exist then this must be set. - If C(state=present) and the group doesn't exist then this must be set.
type: str
choices: [domainlocal, global, universal] choices: [domainlocal, global, universal]
state: state:
description: description:
- If C(state=present) this module will ensure the group is created and is - If C(state=present) this module will ensure the group is created and is
configured accordingly. configured accordingly.
- If C(state=absent) this module will delete the group if it exists - If C(state=absent) this module will delete the group if it exists
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
notes: notes:
- This must be run on a host that has the ActiveDirectory powershell module - This must be run on a host that has the ActiveDirectory powershell module installed.
installed.
seealso: seealso:
- module: win_domain - module: win_domain
- module: win_domain_controller - module: win_domain_controller
@ -218,7 +228,7 @@ protected_from_accidental_deletion:
description: Whether the group is protected from accidental deletion. description: Whether the group is protected from accidental deletion.
returned: group exists returned: group exists
type: bool type: bool
sample: True sample: true
sid: sid:
description: The Security ID of the group. description: The Security ID of the group.
returned: group exists returned: group exists

13
lib/ansible/modules/windows/win_domain_membership.py
View file

@ -8,7 +8,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
module: win_domain_membership module: win_domain_membership
short_description: Manage domain/workgroup membership for a Windows host short_description: Manage domain/workgroup membership for a Windows host
version_added: '2.3' version_added: '2.3'
@ -19,28 +19,35 @@ options:
dns_domain_name: dns_domain_name:
description: description:
- When C(state) is C(domain), the DNS name of the domain to which the targeted Windows host should be joined. - 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: domain_admin_user:
description: description:
- Username of a domain admin for the target domain (required to join or leave the domain). - Username of a domain admin for the target domain (required to join or leave the domain).
type: str
required: yes required: yes
domain_admin_password: domain_admin_password:
description: description:
- Password for the specified C(domain_admin_user). - Password for the specified C(domain_admin_user).
type: str
hostname: hostname:
description: description:
- The desired hostname for the Windows host. - The desired hostname for the Windows host.
type: str
domain_ou_path: domain_ou_path:
description: description:
- The desired OU path for adding the computer object. - 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. - 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" version_added: "2.4"
state: state:
description: description:
- Whether the target host should be a member of a domain or workgroup. - Whether the target host should be a member of a domain or workgroup.
type: str
choices: [ domain, workgroup ] choices: [ domain, workgroup ]
workgroup_name: workgroup_name:
description: description:
- When C(state) is C(workgroup), the name of the workgroup that the Windows host should be in. - When C(state) is C(workgroup), the name of the workgroup that the Windows host should be in.
type: str
seealso: seealso:
- module: win_domain - module: win_domain
- module: win_domain_controller - module: win_domain_controller
@ -54,7 +61,7 @@ author:
- Matt Davis (@nitzmahone) - Matt Davis (@nitzmahone)
''' '''
RETURN = ''' RETURN = r'''
reboot_required: reboot_required:
description: True if changes were made that require a reboot. description: True if changes were made that require a reboot.
returned: always returned: always
@ -62,7 +69,7 @@ reboot_required:
sample: true sample: true
''' '''
EXAMPLES = ''' EXAMPLES = r'''
# host should be a member of domain ansible.vagrant; module will ensure the hostname is mydomainclient # 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. # and will use the passed credentials to join domain if necessary.

56
lib/ansible/modules/windows/win_domain_user.py
View file

@ -21,12 +21,14 @@ options:
name: name:
description: description:
- Name of the user to create, remove or modify. - Name of the user to create, remove or modify.
type: str
required: true required: true
state: state:
description: description:
- When C(present), creates or updates the user account. When C(absent), - When C(present), creates or updates the user account.
removes the user account if it exists. When C(query), - When C(absent), removes the user account if it exists.
retrieves the user account details without making any changes. - When C(query), retrieves the user account details without making any changes.
type: str
choices: [ absent, present, query ] choices: [ absent, present, query ]
default: present default: present
enabled: enabled:
@ -34,39 +36,41 @@ options:
- C(yes) will enable the user account. - C(yes) will enable the user account.
- C(no) will disable the account. - C(no) will disable the account.
type: bool type: bool
default: 'yes' default: yes
account_locked: account_locked:
description: description:
- C(no) will unlock the user account if locked. Note that there is not a - C(no) will unlock the user account if locked.
way to lock an account as an administrator. Accounts are locked due to - Note that there is not a way to lock an account as an administrator.
user actions; as an admin, you may only unlock a locked account. If you - Accounts are locked due to user actions; as an admin, you may only unlock a locked account.
wish to administratively disable an account, set I(enabled) to C(no). - If you wish to administratively disable an account, set I(enabled) to C(no).
choices: [ 'no' ] choices: [ no ]
description: description:
description: description:
- Description of the user - Description of the user
type: str
groups: groups:
description: description:
- Adds or removes the user from this list of groups, - Adds or removes the user from this list of groups,
depending on the value of I(groups_action). To remove all but the depending on the value of I(groups_action).
Principal Group, set C(groups=<principal group name>) and - To remove all but the Principal Group, set C(groups=<principal group name>) and
I(groups_action=replace). Note that users cannot be removed from I(groups_action=replace).
their principal group (for example, "Domain Users"). - Note that users cannot be removed from their principal group (for example, "Domain Users").
type: list type: list
groups_action: groups_action:
description: description:
- If C(add), the user is added to each group in I(groups) where not - If C(add), the user is added to each group in I(groups) where not already a member.
already a member.
- If C(remove), the user is removed from each group in I(groups). - 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 - If C(replace), the user is added as a member of each group in
I(groups) and removed from any other groups. I(groups) and removed from any other groups.
type: str
choices: [ add, remove, replace ] choices: [ add, remove, replace ]
default: replace default: replace
password: password:
description: description:
- Optionally set the user's password to this (plain text) value. In order - Optionally set the user's password to this (plain text) value.
to enable an account - I(enabled) - a password must already be - To enable an account - I(enabled) - a password must already be
configured on the account, or you must provide a password here. configured on the account, or you must provide a password here.
type: str
update_password: update_password:
description: description:
- C(always) will update passwords if they differ. - 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' - Note that C(always) will always report an Ansible status of 'changed'
because we cannot determine whether the new password differs from because we cannot determine whether the new password differs from
the old password. the old password.
type: str
choices: [ always, on_create ] choices: [ always, on_create ]
default: always default: always
password_expired: password_expired:
@ -96,63 +101,77 @@ options:
firstname: firstname:
description: description:
- Configures the user's first name (given name). - Configures the user's first name (given name).
type: str
surname: surname:
description: description:
- Configures the user's last name (surname). - Configures the user's last name (surname).
type: str
company: company:
description: description:
- Configures the user's company name. - Configures the user's company name.
type: str
upn: upn:
description: description:
- Configures the User Principal Name (UPN) for the account. - Configures the User Principal Name (UPN) for the account.
- This is not required, but is best practice to configure for modern - This is not required, but is best practice to configure for modern
versions of Active Directory. versions of Active Directory.
- The format is C(<username>@<domain>). - The format is C(<username>@<domain>).
type: str
email: email:
description: description:
- Configures the user's email address. - Configures the user's email address.
- This is a record in AD and does not do anything to configure any email - This is a record in AD and does not do anything to configure any email
servers or systems. servers or systems.
type: str
street: street:
description: description:
- Configures the user's street address. - Configures the user's street address.
type: str
city: city:
description: description:
- Configures the user's city. - Configures the user's city.
type: str
state_province: state_province:
description: description:
- Configures the user's state or province. - Configures the user's state or province.
type: str
postal_code: postal_code:
description: description:
- Configures the user's postal code / zip code. - Configures the user's postal code / zip code.
type: str
country: country:
description: description:
- Configures the user's country code. - Configures the user's country code.
- Note that this is a two-character ISO 3166 code. - Note that this is a two-character ISO 3166 code.
type: str
path: path:
description: description:
- Container or OU for the new user; if you do not specify this, the - 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. 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; - 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 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. then re-add the user with the appropriate path.
type: str
attributes: attributes:
description: description:
- A dict of custom LDAP attributes to set on the user. - 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 - This can be used to set custom attributes that are not exposed as module
parameters, e.g. C(telephoneNumber). parameters, e.g. C(telephoneNumber).
- See the examples on how to format this parameter. - See the examples on how to format this parameter.
type: str
version_added: '2.5' version_added: '2.5'
domain_username: domain_username:
description: description:
- The username to use when interacting with AD. - The username to use when interacting with AD.
- If this is not set then the user Ansible used to log in with will be - 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. used instead when using CredSSP or Kerberos with credential delegation.
type: str
version_added: '2.5' version_added: '2.5'
domain_password: domain_password:
description: description:
- The password for I(username). - The password for I(username).
type: str
version_added: '2.5' version_added: '2.5'
domain_server: domain_server:
description: description:
@ -160,6 +179,7 @@ options:
- Can be in the form of an FQDN or NetBIOS name. - 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 - If not specified then the value is based on the domain of the computer
running PowerShell. running PowerShell.
type: str
version_added: '2.5' version_added: '2.5'
notes: notes:
- Works with Windows 2012R2 and newer. - Works with Windows 2012R2 and newer.

4
lib/ansible/modules/windows/win_dotnet_ngen.py
View file

@ -21,17 +21,17 @@ description:
- This happens via scheduled task, usually at some inopportune time. - 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. - 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) - 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: notes:
- There are in fact two scheduled tasks for ngen but they have no triggers so aren't a problem. - 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. - There's no way to test if they've been completed.
- The stdout is quite likely to be several megabytes. - The stdout is quite likely to be several megabytes.
author: author:
- Peter Mounce (@petemounce) - Peter Mounce (@petemounce)
options: {}
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: run ngen tasks - name: Run ngen tasks
win_dotnet_ngen: win_dotnet_ngen:
''' '''

7
lib/ansible/modules/windows/win_dsc.py
View file

@ -25,6 +25,7 @@ options:
description: description:
- The name of the DSC Resource to use. - The name of the DSC Resource to use.
- Must be accessible to PowerShell using any of the default paths. - Must be accessible to PowerShell using any of the default paths.
type: str
required: yes required: yes
module_version: module_version:
description: description:
@ -34,6 +35,7 @@ options:
containing the DSC resource. containing the DSC resource.
- If not specified, the module will follow standard PowerShell convention - If not specified, the module will follow standard PowerShell convention
and use the highest version available. and use the highest version available.
type: str
default: latest default: latest
free_form: free_form:
description: description:
@ -52,6 +54,7 @@ options:
provided but a comma separated string also work. Use a list where 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 possible as no escaping is required and it works with more complex types
list C(CimInstance[]). list C(CimInstance[]).
type: str
required: true required: true
notes: notes:
- By default there are a few builtin resources that come with PowerShell 5.0, - 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. the machine requires a reboot for the invoked changes to take effect.
returned: always returned: always
type: bool type: bool
sample: True sample: true
message: message:
description: any error message from invoking the DSC resource description: Any error message from invoking the DSC resource.
returned: error returned: error
type: str type: str
sample: Multiple DSC modules found with resource name xyz sample: Multiple DSC modules found with resource name xyz

6
lib/ansible/modules/windows/win_environment.py
View file

@ -21,25 +21,29 @@ options:
description: description:
- Set to C(present) to ensure environment variable is set. - Set to C(present) to ensure environment variable is set.
- Set to C(absent) to ensure it is removed. - Set to C(absent) to ensure it is removed.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
name: name:
description: description:
- The name of the environment variable. - The name of the environment variable.
type: str
required: yes required: yes
value: value:
description: description:
- The value to store in the environment variable. - The value to store in the environment variable.
- Must be set when C(state=present) and cannot be an empty string. - Must be set when C(state=present) and cannot be an empty string.
- Can be omitted for C(state=absent). - Can be omitted for C(state=absent).
type: str
level: level:
description: description:
- The level at which to set the environment variable. - The level at which to set the environment variable.
- Use C(machine) to set for all users. - Use C(machine) to set for all users.
- Use C(user) to set for the current user that ansible is connected as. - 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. - Use C(process) to set for the current process. Probably not that useful.
choices: [ machine, user, process ] type: str
required: yes required: yes
choices: [ machine, process, user ]
notes: notes:
- This module is best-suited for setting the entire value of an - This module is best-suited for setting the entire value of an
environment variable. For safe element-based management of environment variable. For safe element-based management of

13
lib/ansible/modules/windows/win_eventlog.py
View file

@ -24,6 +24,7 @@ options:
name: name:
description: description:
- Name of the event log to manage. - Name of the event log to manage.
type: str
required: yes required: yes
state: state:
description: description:
@ -31,6 +32,7 @@ options:
- When C(sources) is populated, state is checked for sources. - When C(sources) is populated, state is checked for sources.
- When C(sources) is not populated, state is checked for the specified log itself. - 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. - If C(state) is C(clear), event log entries are cleared for the target log.
type: str
choices: [ absent, clear, present ] choices: [ absent, clear, present ]
default: present default: present
sources: sources:
@ -56,16 +58,15 @@ options:
- The maximum size of the event log. - The maximum size of the event log.
- Value must be between 64KB and 4GB, and divisible by 64KB. - 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). - Size can be specified in KB, MB or GB (e.g. 128KB, 16MB, 2.5GB).
type: str
overflow_action: overflow_action:
description: description:
- The action for the log to take once it reaches its maximum size. - 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. - For C(DoNotOverwrite), all existing entries are kept and new entries are not retained.
choices: - For C(OverwriteAsNeeded), each new entry overwrites the oldest entry.
- OverwriteOlder - For C(OverwriteOlder), new log entries overwrite those older than the C(retention_days) value.
- OverwriteAsNeeded type: str
- DoNotOverwrite choices: [ DoNotOverwrite, OverwriteAsNeeded, OverwriteOlder ]
retention_days: retention_days:
description: description:
- The minimum number of days event entries must remain in the log. - The minimum number of days event entries must remain in the log.

42
lib/ansible/modules/windows/win_feature.py
View file

@ -12,43 +12,45 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = r''' DOCUMENTATION = r'''
--- ---
module: win_feature module: win_feature
version_added: "1.7" version_added: "1.7"
short_description: Installs and uninstalls Windows Features on Windows Server short_description: Installs and uninstalls Windows Features on Windows Server
description: description:
- Installs or uninstalls Windows Roles or Features on Windows Server. This module uses the Add/Remove-WindowsFeature Cmdlets on Windows 2008 R2 - 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. and Install/Uninstall-WindowsFeature Cmdlets on Windows 2012, which are not available on client os machines.
options: options:
name: name:
description: description:
- Names of roles or features to install as a single feature or a comma-separated list of features. - 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). - To list all available features use the PowerShell command C(Get-WindowsFeature).
required: yes
type: list type: list
required: yes
state: state:
description: description:
- State of the features or roles on the system. - State of the features or roles on the system.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
include_sub_features: include_sub_features:
description: description:
- Adds all subfeatures of the specified feature. - Adds all subfeatures of the specified feature.
type: bool type: bool
default: 'no' default: no
include_management_tools: include_management_tools:
description: description:
- Adds the corresponding management tools to the specified feature. - Adds the corresponding management tools to the specified feature.
- Not supported in Windows 2008 R2 and will be ignored. - Not supported in Windows 2008 R2 and will be ignored.
type: bool type: bool
default: 'no' default: no
source: source:
description: description:
- Specify a source to install the feature from. - Specify a source to install the feature from.
- Not supported in Windows 2008 R2 and will be ignored. - Not supported in Windows 2008 R2 and will be ignored.
- Can either be C({driveletter}:\sources\sxs) or C(\\{IP}\share\sources\sxs). - Can either be C({driveletter}:\sources\sxs) or C(\\{IP}\share\sources\sxs).
type: str
version_added: "2.1" version_added: "2.1"
seealso: seealso:
- module: win_chocolatey - module: win_chocolatey
@ -85,62 +87,62 @@ EXAMPLES = r'''
include_management_tools: yes include_management_tools: yes
register: win_feature register: win_feature
- name: reboot if installing Web-Server feature requires it - name: Reboot if installing Web-Server feature requires it
win_reboot: win_reboot:
when: win_feature.reboot_required when: win_feature.reboot_required
''' '''
RETURN = r''' RETURN = r'''
exitcode: 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 returned: always
type: str type: str
sample: Success sample: Success
feature_result: feature_result:
description: List of features that were installed or removed description: List of features that were installed or removed.
returned: success returned: success
type: complex type: complex
sample: sample:
contains: contains:
display_name: display_name:
description: Feature display name description: Feature display name.
returned: always returned: always
type: str type: str
sample: "Telnet Client" sample: "Telnet Client"
id: 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 returned: always
type: int type: int
sample: 44 sample: 44
message: 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 returned: always
type: list of strings type: list of strings
sample: [] sample: []
reboot_required: 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 returned: always
type: bool type: bool
sample: True sample: true
restart_needed: restart_needed:
description: DEPRECATED in Ansible 2.4 (refer to C(reboot_required) instead). True when the target server requires a reboot as a 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 returned: always
type: bool type: bool
sample: True sample: true
skip_reason: skip_reason:
description: The reason a feature installation or removal was skipped description: The reason a feature installation or removal was skipped.
returned: always returned: always
type: str type: str
sample: NotSkipped sample: NotSkipped
success: success:
description: If the feature installation or removal was successful description: If the feature installation or removal was successful.
returned: always returned: always
type: bool type: bool
sample: True sample: true
reboot_required: 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 returned: success
type: bool type: bool
sample: True sample: true
''' '''

3
lib/ansible/modules/windows/win_file.py
View file

@ -35,9 +35,8 @@ options:
- If C(touch), an empty file will be created if the C(path) does not - 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 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). modification times (similar to the way C(touch) works from the command line).
type: str
choices: [ absent, directory, file, touch ] choices: [ absent, directory, file, touch ]
notes:
- For non-Windows targets, use the M(file) module instead.
seealso: seealso:
- module: assemble - module: assemble
- module: copy - module: copy

20
lib/ansible/modules/windows/win_file_version.py
View file

@ -22,8 +22,8 @@ options:
description: description:
- File to get version. - File to get version.
- Always provide absolute path. - Always provide absolute path.
required: yes
type: path type: path
required: yes
seealso: seealso:
- module: win_file - module: win_file
author: author:
@ -41,37 +41,37 @@ EXAMPLES = r'''
''' '''
RETURN = r''' RETURN = r'''
win_file_version.path: path:
description: file path description: file path
returned: always returned: always
type: str type: str
win_file_version.file_version: file_version:
description: file version number. description: File version number..
returned: no error returned: no error
type: str type: str
win_file_version.product_version: product_version:
description: the version of the product this file is distributed with. description: The version of the product this file is distributed with.
returned: no error returned: no error
type: str type: str
win_file_version.file_major_part: file_major_part:
description: the major part of the version number. description: the major part of the version number.
returned: no error returned: no error
type: str type: str
win_file_version.file_minor_part: file_minor_part:
description: the minor part of the version number of the file. description: the minor part of the version number of the file.
returned: no error returned: no error
type: str type: str
win_file_version.file_build_part: file_build_part:
description: build number of the file. description: build number of the file.
returned: no error returned: no error
type: str type: str
win_file_version.file_private_part: file_private_part:
description: file private part number. description: file private part number.
returned: no error returned: no error
type: str type: str

108
lib/ansible/modules/windows/win_find.py
View file

@ -24,24 +24,30 @@ options:
age: age:
description: description:
- Select files or folders whose age is equal to or greater than - 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 the specified time.
less than the specified time. You can choose seconds, minutes, - Use a negative age to find files equal to or less than
hours, days or weeks by specifying the first letter of an of 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"). those words (e.g., "2s", "10d", 1w").
type: str
age_stamp: age_stamp:
description: description:
- Choose the file property against which we compare C(age). The - Choose the file property against which we compare C(age).
default attribute we compare with is the last modification time. - The default attribute we compare with is the last modification time.
type: str
choices: [ atime, ctime, mtime ] choices: [ atime, ctime, mtime ]
default: mtime default: mtime
checksum_algorithm: checksum_algorithm:
description: description:
- Algorithm to determine the checksum of a file. Will throw an error - Algorithm to determine the checksum of a file.
if the host is unable to use specified algorithm. - Will throw an error if the host is unable to use specified algorithm.
type: str
choices: [ md5, sha1, sha256, sha384, sha512 ] choices: [ md5, sha1, sha256, sha384, sha512 ]
default: sha1 default: sha1
file_type: file_type:
description: Type of file to search for. description: Type of file to search for.
type: str
choices: [ directory, file ] choices: [ directory, file ]
default: file default: file
follow: follow:
@ -49,47 +55,47 @@ options:
- Set this to C(yes) to follow symlinks in the path. - Set this to C(yes) to follow symlinks in the path.
- This needs to be used in conjunction with C(recurse). - This needs to be used in conjunction with C(recurse).
type: bool type: bool
default: 'no' default: no
get_checksum: get_checksum:
description: description:
- Whether to return a checksum of the file in the return info (default sha1), - Whether to return a checksum of the file in the return info (default sha1),
use C(checksum_algorithm) to change from the default. use C(checksum_algorithm) to change from the default.
type: bool type: bool
default: 'yes' default: yes
hidden: hidden:
description: Set this to include hidden files or folders. description: Set this to include hidden files or folders.
type: bool type: bool
default: 'no' default: no
paths: paths:
description: description:
- List of paths of directories to search for files or folders in. - 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 required: yes
patterns: patterns:
description: description:
- One or more (powershell or regex) patterns to compare filenames - One or more (powershell or regex) patterns to compare filenames with.
with. The type of pattern matching is controlled by C(use_regex) - The type of pattern matching is controlled by C(use_regex) option.
option. The patterns retrict the list of files or folders to be - The patterns retrict the list of files or folders to be returned based on the filenames.
returned based on the filenames. For a file to be matched it - For a file to be matched it only has to match with one pattern in a list provided.
only has to match with one pattern in a list provided. type: list
recurse: recurse:
description: description:
- Will recursively descend into the directory looking for files - Will recursively descend into the directory looking for files or folders.
or folders.
type: bool type: bool
default: 'no' default: no
size: size:
description: description:
- Select files or folders whose size is equal to or greater than - Select files or folders whose size is equal to or greater than the specified size.
the specified size. Use a negative value to find files equal to - Use a negative value to find files equal to or less than the specified size.
or less than the specified size. You can specify the size with - You can specify the size with a suffix of the byte type i.e. kilo = k, mega = m...
a suffix of the byte type i.e. kilo = k, mega = m... Size is not - Size is not evaluated for symbolic links.
evaluated for symbolic links. type: str
use_regex: use_regex:
description: description:
- Will set patterns to run as a regex check if set to C(yes). - Will set patterns to run as a regex check if set to C(yes).
type: bool type: bool
default: 'no' default: no
author: author:
- Jordan Borean (@jborean93) - Jordan Borean (@jborean93)
''' '''
@ -198,102 +204,102 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
examined: examined:
description: The number of files/folders that was checked description: The number of files/folders that was checked.
returned: always returned: always
type: int type: int
sample: 10 sample: 10
matched: matched:
description: The number of files/folders that match the criteria description: The number of files/folders that match the criteria.
returned: always returned: always
type: int type: int
sample: 2 sample: 2
files: 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 returned: success
type: complex type: complex
contains: contains:
attributes: 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 returned: success, path exists
type: str type: str
sample: "Archive, Hidden" sample: "Archive, Hidden"
checksum: 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 returned: success, path exists, path is a file, get_checksum == True
type: str type: str
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
creationtime: 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 returned: success, path exists
type: float type: float
sample: 1477984205.15 sample: 1477984205.15
extension: 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 returned: success, path exists, path is a file
type: str type: str
sample: ".ps1" sample: ".ps1"
isarchive: 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 returned: success, path exists
type: bool type: bool
sample: True sample: true
isdir: isdir:
description: if the path is a directory or not description: If the path is a directory or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
ishidden: ishidden:
description: if the path is hidden or not description: If the path is hidden or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
islnk: 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 returned: success, path exists
type: bool type: bool
sample: True sample: true
isreadonly: isreadonly:
description: if the path is read only or not description: If the path is read only or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
isshared: isshared:
description: if the path is shared or not description: If the path is shared or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
lastaccesstime: 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 returned: success, path exists
type: float type: float
sample: 1477984205.15 sample: 1477984205.15
lastwritetime: 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 returned: success, path exists
type: float type: float
sample: 1477984205.15 sample: 1477984205.15
lnk_source: 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 return: success, path exists, path is a symbolic link
type: str type: str
sample: C:\temp sample: C:\temp
owner: owner:
description: the owner of the file description: The owner of the file.
returned: success, path exists returned: success, path exists
type: str type: str
sample: BUILTIN\Administrators sample: BUILTIN\Administrators
path: path:
description: the full absolute path to the file description: The full absolute path to the file.
returned: success, path exists returned: success, path exists
type: str type: str
sample: BUILTIN\Administrators sample: BUILTIN\Administrators
sharename: 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 returned: success, path exists, path is a directory and isshared == True
type: str type: str
sample: file-share sample: file-share
size: 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 returned: success, path exists, path is not a link
type: int type: int
sample: 1024 sample: 1024

18
lib/ansible/modules/windows/win_firewall.py
View file

@ -25,17 +25,13 @@ options:
description: description:
- Specify one or more profiles to change. - Specify one or more profiles to change.
type: list type: list
choices: choices: [ Domain, Private, Public ]
- Domain default: [ Domain, Private, Public ]
- Private
- Public
default: [Domain, Private, Public]
state: state:
description: description:
- Set state of firewall for given profile. - Set state of firewall for given profile.
choices: type: str
- enabled choices: [ disabled, enabled ]
- disabled
seealso: seealso:
- module: win_firewall_rule - module: win_firewall_rule
author: author:
@ -62,17 +58,17 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
enabled: 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 returned: always
type: bool type: bool
sample: true sample: true
profiles: profiles:
description: chosen profile description: Chosen profile.
returned: always returned: always
type: str type: str
sample: Domain sample: Domain
state: state:
description: desired state of the given firewall profile(s) description: Desired state of the given firewall profile(s).
returned: always returned: always
type: list type: list
sample: enabled sample: enabled

26
lib/ansible/modules/windows/win_firewall_rule.py
View file

@ -19,55 +19,67 @@ description:
options: options:
enabled: enabled:
description: description:
- Is this firewall rule enabled or disabled. - Whether this firewall rule is enabled or disabled.
type: bool type: bool
default: 'yes' default: yes
aliases: [ enable ] aliases: [ enable ]
state: state:
description: description:
- Should this rule be added or removed. - Should this rule be added or removed.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
name: name:
description: description:
- The rules name - The rules name.
type: str
required: yes required: yes
direction: direction:
description: description:
- Is this rule for inbound or outbound traffic. - Whether this rule is for inbound or outbound traffic.
type: str
required: yes required: yes
choices: [ in, out ] choices: [ in, out ]
action: action:
description: description:
- What to do with the items this rule is for. - What to do with the items this rule is for.
type: str
required: yes required: yes
choices: [ allow, block ] choices: [ allow, block ]
description: description:
description: description:
- Description for the firewall rule. - Description for the firewall rule.
type: str
localip: localip:
description: description:
- The local ip address this rule applies to. - The local ip address this rule applies to.
type: str
default: any default: any
remoteip: remoteip:
description: description:
- The remote ip address/range this rule applies to. - The remote ip address/range this rule applies to.
type: str
default: any default: any
localport: localport:
description: description:
- The local port this rule applies to. - The local port this rule applies to.
type: str
remoteport: remoteport:
description: description:
- The remote port this rule applies to. - The remote port this rule applies to.
type: str
program: program:
description: description:
- The program this rule applies to. - The program this rule applies to.
type: str
service: service:
description: description:
- The service this rule applies to. - The service this rule applies to.
type: str
protocol: protocol:
description: description:
- The protocol this rule applies to. - The protocol this rule applies to.
type: str
default: any default: any
profiles: profiles:
description: description:
@ -78,10 +90,10 @@ options:
force: force:
description: description:
- Replace any existing rule by removing it first. - 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. - This is no longer required in Ansible 2.4 as rules no longer need replacing when being modified.
- DEPRECATED in 2.4 and will be removed in 2.9. - DEPRECATED in Ansible 2.4 and will be removed in Ansible 2.9.
type: bool type: bool
default: 'no' default: no
seealso: seealso:
- module: win_firewall - module: win_firewall
author: author:

16
lib/ansible/modules/windows/win_get_url.py
View file

@ -17,21 +17,21 @@ module: win_get_url
version_added: "1.7" version_added: "1.7"
short_description: Downloads file from HTTP, HTTPS, or FTP to node short_description: Downloads file from HTTP, HTTPS, or FTP to node
description: description:
- Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote - Downloads files from HTTP, HTTPS, or FTP to the remote server.
server I(must) have direct access to the remote resource. - The remote server I(must) have direct access to the remote resource.
- For non-Windows targets, use the M(get_url) module instead. - For non-Windows targets, use the M(get_url) module instead.
options: options:
url: url:
description: description:
- The full URL of a file to download. - The full URL of a file to download.
required: yes
type: str type: str
required: yes
dest: dest:
description: description:
- The location to save the file at the URL. - The location to save the file at the URL.
- Be sure to include a filename and extension as appropriate. - Be sure to include a filename and extension as appropriate.
required: yes
type: path type: path
required: yes
force: force:
description: description:
- If C(yes), will always download the file. If C(no), will only - 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 time of the requested resource, so for this to work, the remote web
server must support HEAD requests. server must support HEAD requests.
type: bool type: bool
default: 'yes' default: yes
version_added: "2.0" version_added: "2.0"
headers: headers:
description: description:
@ -63,7 +63,7 @@ options:
- If C(yes), will add a Basic authentication header on the initial request. - If C(yes), will add a Basic authentication header on the initial request.
- If C(no), will use Microsoft's WebClient to handle authentication. - If C(no), will use Microsoft's WebClient to handle authentication.
type: bool type: bool
default: 'no' default: no
version_added: "2.5" version_added: "2.5"
validate_certs: validate_certs:
description: description:
@ -71,7 +71,7 @@ options:
on personally controlled sites using self-signed certificates. on personally controlled sites using self-signed certificates.
- If C(skip_certificate_validation) was set, it overrides this option. - If C(skip_certificate_validation) was set, it overrides this option.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
proxy_url: proxy_url:
description: description:
@ -93,7 +93,7 @@ options:
- If C(no), it will not use a proxy, even if one is defined in an environment - If C(no), it will not use a proxy, even if one is defined in an environment
variable on the target hosts. variable on the target hosts.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
timeout: timeout:
description: description:

5
lib/ansible/modules/windows/win_group.py
View file

@ -23,17 +23,18 @@ options:
name: name:
description: description:
- Name of the group. - Name of the group.
type: str
required: yes required: yes
description: description:
description: description:
- Description of the group. - Description of the group.
type: str
state: state:
description: description:
- Create or remove the group. - Create or remove the group.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
notes:
- For non-Windows targets, please use the M(group) module instead.
seealso: seealso:
- module: group - module: group
- module: win_domain_group - module: win_domain_group

4
lib/ansible/modules/windows/win_group_membership.py
View file

@ -20,6 +20,7 @@ options:
name: name:
description: description:
- Name of the local group to manage membership on. - Name of the local group to manage membership on.
type: str
required: yes required: yes
members: members:
description: description:
@ -29,11 +30,12 @@ options:
- Accepts service users as NT AUTHORITY\username. - Accepts service users as NT AUTHORITY\username.
- Accepts all local, domain and service user types as username, - Accepts all local, domain and service user types as username,
favoring domain lookups when in a domain. favoring domain lookups when in a domain.
required: yes
type: list type: list
required: yes
state: state:
description: description:
- Desired state of the members in the group. - Desired state of the members in the group.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
seealso: seealso:

7
lib/ansible/modules/windows/win_hostname.py
View file

@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
DOCUMENTATION = r''' DOCUMENTATION = r'''
module: win_hostname module: win_hostname
version_added: "2.6" version_added: "2.6"
short_description: Manages local Windows computer name. short_description: Manages local Windows computer name
description: description:
- Manages local Windows computer name. - Manages local Windows computer name.
- A reboot is required for the computer name to take effect. - A reboot is required for the computer name to take effect.
@ -22,6 +22,7 @@ options:
name: name:
description: description:
- The hostname to set for the computer. - The hostname to set for the computer.
type: str
required: true required: true
seealso: seealso:
- module: win_dns_client - module: win_dns_client
@ -42,12 +43,12 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
old_name: 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 returned: always
type: str type: str
sample: old_hostname sample: old_hostname
reboot_required: 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 returned: always
type: bool type: bool
sample: true sample: true

17
lib/ansible/modules/windows/win_hotfix.py
View file

@ -27,6 +27,7 @@ options:
- You can get the identifier by running - You can get the identifier by running
'Get-WindowsPackage -Online -PackagePath path-to-cab-in-msu' after 'Get-WindowsPackage -Online -PackagePath path-to-cab-in-msu' after
expanding the msu file. expanding the msu file.
type: str
hotfix_kb: hotfix_kb:
description: description:
- The name of the KB the hotfix relates to, see examples for details. - 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. 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 - 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. all cases it is recommended to use C(hotfix_identifier) instead.
type: str
state: state:
description: description:
- Whether to install or uninstall the hotfix. - Whether to install or uninstall the hotfix.
- When C(present), C(source) MUST be set. - When C(present), C(source) MUST be set.
- When C(absent), C(hotfix_identifier) or C(hotfix_kb) MUST be set. - When C(absent), C(hotfix_identifier) or C(hotfix_kb) MUST be set.
type: str
default: present default: present
choices: [ absent, present ] choices: [ absent, present ]
source: source:
@ -64,14 +67,14 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: install Windows ADK with DISM for Server 2008 R2 - name: Install Windows ADK with DISM for Server 2008 R2
win_chocolatey: win_chocolatey:
name: windows-adk name: windows-adk
version: 8.100.26866.0 version: 8.100.26866.0
state: present state: present
install_args: /features OptionId.DeploymentTools 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: win_hotfix:
source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu
state: present state: present
@ -80,7 +83,7 @@ EXAMPLES = r'''
- win_reboot: - win_reboot:
when: hotfix_install.reboot_required when: hotfix_install.reboot_required
- name: install hotfix validating KB - name: Install hotfix validating KB
win_hotfix: win_hotfix:
hotfix_kb: KB3172729 hotfix_kb: KB3172729
source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu
@ -90,7 +93,7 @@ EXAMPLES = r'''
- win_reboot: - win_reboot:
when: hotfix_install.reboot_required when: hotfix_install.reboot_required
- name: install hotfix validating Identifier - name: Install hotfix validating Identifier
win_hotfix: win_hotfix:
hotfix_identifier: Package_for_KB3172729~31bf3856ad364e35~amd64~~6.3.1.0 hotfix_identifier: Package_for_KB3172729~31bf3856ad364e35~amd64~~6.3.1.0
source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu source: C:\temp\windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu
@ -100,7 +103,7 @@ EXAMPLES = r'''
- win_reboot: - win_reboot:
when: hotfix_install.reboot_required when: hotfix_install.reboot_required
- name: uninstall hotfix with Identifier - name: Uninstall hotfix with Identifier
win_hotfix: win_hotfix:
hotfix_identifier: Package_for_KB3172729~31bf3856ad364e35~amd64~~6.3.1.0 hotfix_identifier: Package_for_KB3172729~31bf3856ad364e35~amd64~~6.3.1.0
state: absent state: absent
@ -109,7 +112,7 @@ EXAMPLES = r'''
- win_reboot: - win_reboot:
when: hotfix_uninstall.reboot_required when: hotfix_uninstall.reboot_required
- name: uninstall hotfix with KB (not recommended) - name: Uninstall hotfix with KB (not recommended)
win_hotfix: win_hotfix:
hotfix_kb: KB3172729 hotfix_kb: KB3172729
state: absent state: absent
@ -135,5 +138,5 @@ reboot_required:
finalise. finalise.
returned: success returned: success
type: str type: str
sample: True sample: true
''' '''

5
lib/ansible/modules/windows/win_iis_virtualdirectory.py
View file

@ -19,23 +19,28 @@ options:
name: name:
description: description:
- The name of the virtual directory to create or remove. - The name of the virtual directory to create or remove.
type: str
required: yes required: yes
state: state:
description: description:
- Whether to add or remove the specified virtual directory. - Whether to add or remove the specified virtual directory.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
site: site:
description: description:
- The site name under which the virtual directory is created or exists. - The site name under which the virtual directory is created or exists.
type: str
required: yes required: yes
application: application:
description: description:
- The application under which the virtual directory is created or exists. - The application under which the virtual directory is created or exists.
type: str
physical_path: physical_path:
description: description:
- The physical path to the folder in which the new virtual directory is created. - The physical path to the folder in which the new virtual directory is created.
- The specified folder must already exist. - The specified folder must already exist.
type: str
seealso: seealso:
- module: win_iis_webapplication - module: win_iis_webapplication
- module: win_iis_webapppool - module: win_iis_webapppool

9
lib/ansible/modules/windows/win_iis_webapplication.py
View file

@ -19,23 +19,28 @@ options:
name: name:
description: description:
- Name of the web application. - Name of the web application.
type: str
required: yes required: yes
site: site:
description: description:
- Name of the site on which the application is created. - Name of the site on which the application is created.
type: str
required: yes required: yes
state: state:
description: description:
- State of the web application. - State of the web application.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
physical_path: physical_path:
description: description:
- The physical path on the remote host to use for the new application. - The physical path on the remote host to use for the new application.
- The specified folder must already exist. - The specified folder must already exist.
type: str
application_pool: application_pool:
description: description:
- The application pool in which the new site executes. - The application pool in which the new site executes.
type: str
seealso: seealso:
- module: win_iis_virtualdirectory - module: win_iis_virtualdirectory
- module: win_iis_webapppool - module: win_iis_webapppool
@ -56,12 +61,12 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
application_pool: application_pool:
description: The used/implemented application_pool value description: The used/implemented application_pool value.
returned: success returned: success
type: str type: str
sample: DefaultAppPool sample: DefaultAppPool
physical_path: physical_path:
description: The used/implemented physical_path value description: The used/implemented physical_path value.
returned: success returned: success
type: str type: str
sample: C:\apps\acme\api sample: C:\apps\acme\api

24
lib/ansible/modules/windows/win_iis_webapppool.py
View file

@ -39,10 +39,9 @@ options:
name: name:
description: description:
- Name of the application pool. - Name of the application pool.
type: str
required: yes required: yes
state: state:
choices: [ absent, present, restarted, started, stopped ]
default: present
description: description:
- The state of the application pool. - The state of the application pool.
- If C(absent) will ensure the app pool is removed. - If C(absent) will ensure the app pool is removed.
@ -51,6 +50,9 @@ options:
is never idempotent. is never idempotent.
- If C(started) will ensure the app pool exists and is started. - If C(started) will ensure the app pool exists and is started.
- If C(stopped) will ensure the app pool exists and is stopped. - If C(stopped) will ensure the app pool exists and is stopped.
type: str
choices: [ absent, present, restarted, started, stopped ]
default: present
seealso: seealso:
- module: win_iis_virtualdirectory - module: win_iis_virtualdirectory
- module: win_iis_webapplication - module: win_iis_webapplication
@ -62,34 +64,34 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: return information about an existing application pool - name: Return information about an existing application pool
win_iis_webapppool: win_iis_webapppool:
name: DefaultAppPool name: DefaultAppPool
state: present state: present
- name: create a new application pool in 'Started' state - name: Create a new application pool in 'Started' state
win_iis_webapppool: win_iis_webapppool:
name: AppPool name: AppPool
state: started state: started
- name: stop an application pool - name: Stop an application pool
win_iis_webapppool: win_iis_webapppool:
name: AppPool name: AppPool
state: stopped state: stopped
- name: restart an application pool (non-idempotent) - name: Restart an application pool (non-idempotent)
win_iis_webapppool: win_iis_webapppool:
name: AppPool name: AppPool
state: restart state: restart
- name: change application pool attributes using new dict style - name: Change application pool attributes using new dict style
win_iis_webapppool: win_iis_webapppool:
name: AppPool name: AppPool
attributes: attributes:
managedRuntimeVersion: v4.0 managedRuntimeVersion: v4.0
autoStart: no 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: win_iis_webapppool:
name: AnotherAppPool name: AnotherAppPool
state: started state: started
@ -99,7 +101,7 @@ EXAMPLES = r'''
# In the below example we are setting attributes in child element processModel # In the below example we are setting attributes in child element processModel
# https://www.iis.net/configreference/system.applicationhost/applicationpools/add/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: win_iis_webapppool:
name: IdentitiyAppPool name: IdentitiyAppPool
state: started state: started
@ -108,9 +110,9 @@ EXAMPLES = r'''
processModel.identityType: SpecificUser processModel.identityType: SpecificUser
processModel.userName: '{{ansible_user}}' processModel.userName: '{{ansible_user}}'
processModel.password: '{{ansible_password}}' processModel.password: '{{ansible_password}}'
processModel.loadUserProfile: True processModel.loadUserProfile: true
- name: manage a timespan attribute - name: Manage a timespan attribute
win_iis_webapppool: win_iis_webapppool:
name: TimespanAppPool name: TimespanAppPool
state: started state: started

9
lib/ansible/modules/windows/win_iis_webbinding.py
View file

@ -20,35 +20,43 @@ options:
name: name:
description: description:
- Names of web site. - Names of web site.
type: str
required: yes required: yes
aliases: [ website ] aliases: [ website ]
state: state:
description: description:
- State of the binding. - State of the binding.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
port: port:
description: description:
- The port to bind to / use for the new site. - The port to bind to / use for the new site.
type: str
default: 80 default: 80
ip: ip:
description: description:
- The IP address to bind to / use for the new site. - The IP address to bind to / use for the new site.
type: str
default: '*' default: '*'
host_header: host_header:
description: description:
- The host header to bind to / use for the new site. - 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 '*'. - If you are creating/removing a catch-all binding, omit this parameter rather than defining it as '*'.
type: str
protocol: protocol:
description: description:
- The protocol to be used for the Web binding (usually HTTP, HTTPS, or FTP). - The protocol to be used for the Web binding (usually HTTP, HTTPS, or FTP).
type: str
default: http default: http
certificate_hash: certificate_hash:
description: description:
- Certificate hash (thumbprint) for the SSL binding. The certificate hash is the unique identifier for the certificate. - Certificate hash (thumbprint) for the SSL binding. The certificate hash is the unique identifier for the certificate.
type: str
certificate_store_name: certificate_store_name:
description: description:
- Name of the certificate store where the certificate for the binding is located. - Name of the certificate store where the certificate for the binding is located.
type: str
default: my default: my
ssl_flags: ssl_flags:
description: description:
@ -56,6 +64,7 @@ options:
- Primarily used for enabling and disabling server name indication (SNI). - Primarily used for enabling and disabling server name indication (SNI).
- Set to c(0) to disable SNI. - Set to c(0) to disable SNI.
- Set to c(1) to enable SNI. - Set to c(1) to enable SNI.
type: str
version_added: "2.5" version_added: "2.5"
seealso: seealso:
- module: win_iis_virtualdirectory - module: win_iis_virtualdirectory

10
lib/ansible/modules/windows/win_iis_website.py
View file

@ -19,38 +19,48 @@ options:
name: name:
description: description:
- Names of web site. - Names of web site.
type: str
required: yes required: yes
site_id: site_id:
description: description:
- Explicitly set the IIS numeric ID for a site. - Explicitly set the IIS numeric ID for a site.
- Note that this value cannot be changed after the website has been created. - Note that this value cannot be changed after the website has been created.
type: str
version_added: "2.1" version_added: "2.1"
state: state:
description: description:
- State of the web site - State of the web site
type: str
choices: [ absent, started, stopped, restarted ] choices: [ absent, started, stopped, restarted ]
physical_path: physical_path:
description: description:
- The physical path on the remote host to use for the new site. - The physical path on the remote host to use for the new site.
- The specified folder must already exist. - The specified folder must already exist.
type: str
application_pool: application_pool:
description: description:
- The application pool in which the new site executes. - The application pool in which the new site executes.
type: str
port: port:
description: description:
- The port to bind to / use for the new site. - The port to bind to / use for the new site.
type: int
ip: ip:
description: description:
- The IP address to bind to / use for the new site. - The IP address to bind to / use for the new site.
type: str
hostname: hostname:
description: description:
- The host header to bind to / use for the new site. - The host header to bind to / use for the new site.
type: str
ssl: ssl:
description: description:
- Enables HTTPS binding on the site.. - Enables HTTPS binding on the site..
type: str
parameters: parameters:
description: description:
- Custom site Parameters from string where properties are separated by a pipe and property name/values by colon Ex. "foo:1|bar:2" - 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: seealso:
- module: win_iis_virtualdirectory - module: win_iis_virtualdirectory
- module: win_iis_webapplication - module: win_iis_webapplication

33
lib/ansible/modules/windows/win_lineinfile.py
View file

@ -20,9 +20,9 @@ options:
description: description:
- The path of the file to modify. - 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. - 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). - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name).
required: yes
type: path type: path
required: yes
aliases: [ dest, destfile, name ] aliases: [ dest, destfile, name ]
regexp: regexp:
description: description:
@ -32,6 +32,7 @@ options:
state: state:
description: description:
- Whether the line should be there or not. - Whether the line should be there or not.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
line: line:
@ -40,6 +41,7 @@ options:
expanded with the C(regexp) capture groups if the regexp matches. 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 - 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. will have control characters, such as '\r\n', expanded. To print such characters literally, use single or no quotes.
type: str
backrefs: backrefs:
description: description:
- Used with C(state=present). If set, line can contain backreferences (both positional and named) that will get populated if the C(regexp) - 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. 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. - If the C(regexp) does match, the last matching line will be replaced by the expanded line parameter.
type: bool type: bool
default: 'no' default: no
insertafter: insertafter:
description: 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 - 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. 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). - If specified regular expression has no matches, EOF will be used instead. May not be used with C(backrefs).
type: str
choices: [ EOF, '*regex*' ] choices: [ EOF, '*regex*' ]
default: EOF default: EOF
insertbefore: 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; - 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. 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). - 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*' ] choices: [ BOF, '*regex*' ]
create: create:
description: 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. - 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 type: bool
default: 'no' default: no
backup: backup:
description: description:
- Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: 'no' default: no
validate: validate:
description: description:
- Validation to run before copying into place. Use %s in the command to indicate the current file to validate. - 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. - The command is passed securely so shell features like expansion and pipes won't work.
type: str
encoding: encoding:
description: 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 - 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). 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 - 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. specific encoding, the default encoding (UTF-8, no BOM) will be used.
type: str
default: auto default: auto
newline: newline:
description: 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 - 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. 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 ] choices: [ unix, windows ]
default: windows default: windows
notes: notes:
@ -100,8 +107,8 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' # Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
- name: insert path without converting \r\n - name: Insert path without converting \r\n
win_lineinfile: win_lineinfile:
path: c:\file.txt path: c:\file.txt
line: c:\return\new line: c:\return\new
@ -133,21 +140,21 @@ EXAMPLES = r'''
insertbefore: '^www.*80/tcp' insertbefore: '^www.*80/tcp'
line: '# port for http by default' line: '# port for http by default'
# Create file if it doesn't exist with a specific encoding - name: Create file if it doesn't exist with a specific encoding
- win_lineinfile: win_lineinfile:
path: C:\Temp\utf16.txt path: C:\Temp\utf16.txt
create: yes create: yes
encoding: utf-16 encoding: utf-16
line: This is a utf-16 encoded file line: This is a utf-16 encoded file
# Add a line to a file and ensure the resulting file uses unix line separators - name: Add a line to a file and ensure the resulting file uses unix line separators
- win_lineinfile: win_lineinfile:
path: C:\Temp\testfile.txt path: C:\Temp\testfile.txt
line: Line added to file line: Line added to file
newline: unix newline: unix
# Update a line using backrefs - name: Update a line using backrefs
- win_lineinfile: win_lineinfile:
path: C:\Temp\example.conf path: C:\Temp\example.conf
backrefs: yes backrefs: yes
regexp: '(^name=)' regexp: '(^name=)'

5
lib/ansible/modules/windows/win_mapped_drive.py
View file

@ -11,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = r''' DOCUMENTATION = r'''
--- ---
module: win_mapped_drive module: win_mapped_drive
@ -24,6 +23,7 @@ options:
description: description:
- The letter of the network path to map to. - The letter of the network path to map to.
- This letter must not already be in use with Windows. - This letter must not already be in use with Windows.
type: str
required: yes required: yes
password: password:
description: description:
@ -31,6 +31,7 @@ options:
connection. connection.
- This is never saved with a mapped drive, use the M(win_credential) module - This is never saved with a mapped drive, use the M(win_credential) module
to persist a username and password for a host. to persist a username and password for a host.
type: str
path: path:
description: description:
- The UNC path to map the drive to. - The UNC path to map the drive to.
@ -44,6 +45,7 @@ options:
description: description:
- If C(present) will ensure the mapped drive exists. - If C(present) will ensure the mapped drive exists.
- If C(absent) will ensure the mapped drive does not exist. - If C(absent) will ensure the mapped drive does not exist.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
username: username:
@ -55,6 +57,7 @@ options:
custom credentials and become, or CredSSP cannot be used. custom credentials and become, or CredSSP cannot be used.
- If become or CredSSP is used, any credentials saved with - If become or CredSSP is used, any credentials saved with
M(win_credential) will automatically be used instead. M(win_credential) will automatically be used instead.
type: str
notes: notes:
- You cannot use this module to access a mapped drive in another Ansible task, - 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 drives mapped with this module are only accessible when logging in

4
lib/ansible/modules/windows/win_msg.py
View file

@ -22,6 +22,7 @@ options:
to: to:
description: description:
- Who to send the message to. Can be a username, sessionname or sessionid. - Who to send the message to. Can be a username, sessionname or sessionid.
type: str
default: '*' default: '*'
display_seconds: display_seconds:
description: description:
@ -39,6 +40,7 @@ options:
description: description:
- The text of the message to be displayed. - The text of the message to be displayed.
- The message must be less than 256 characters. - The message must be less than 256 characters.
type: str
default: Hello world! default: Hello world!
notes: notes:
- This module must run on a windows host, so ensure your play targets windows - This module must run on a windows host, so ensure your play targets windows
@ -72,7 +74,7 @@ display_seconds:
type: str type: str
sample: 10 sample: 10
rc: rc:
description: The return code of the API call description: The return code of the API call.
returned: always returned: always
type: int type: int
sample: 0 sample: 0

12
lib/ansible/modules/windows/win_nssm.py
View file

@ -24,12 +24,14 @@ options:
name: name:
description: description:
- Name of the service to operate on. - Name of the service to operate on.
type: str
required: true required: true
state: state:
description: description:
- State of the service on the system. - 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 - 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. ansible command module.
type: str
choices: [ absent, present, started, stopped, restarted ] choices: [ absent, present, started, stopped, restarted ]
default: started default: started
application: application:
@ -44,33 +46,41 @@ options:
stdout_file: stdout_file:
description: description:
- Path to receive output. - Path to receive output.
type: str
stderr_file: stderr_file:
description: description:
- Path to receive error output. - Path to receive error output.
type: str
app_parameters: app_parameters:
description: description:
- A string representing a dictionary of parameters to be passed to the application when it starts. - 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. - Use either this or C(app_parameters_free_form), not both.
type: str
app_parameters_free_form: app_parameters_free_form:
version_added: "2.3.0"
description: description:
- Single string of parameters to be passed to the service. - Single string of parameters to be passed to the service.
- Use either this or C(app_parameters), not both. - Use either this or C(app_parameters), not both.
type: str
version_added: "2.3"
dependencies: dependencies:
description: description:
- Service dependencies that has to be started to trigger startup, separated by comma. - Service dependencies that has to be started to trigger startup, separated by comma.
type: list
user: user:
description: description:
- User to be used for service startup. - User to be used for service startup.
type: str
password: password:
description: description:
- Password to be used for service startup. - Password to be used for service startup.
type: str
start_mode: start_mode:
description: description:
- If C(auto) is selected, the service will start at bootup. - 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(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(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. - C(disabled) means that the service will stay off, regardless if it is needed or not.
type: str
choices: [ auto, delayed, disabled, manual ] choices: [ auto, delayed, disabled, manual ]
default: auto default: auto
seealso: seealso:

15
lib/ansible/modules/windows/win_owner.py
View file

@ -14,22 +14,23 @@ module: win_owner
version_added: "2.1" version_added: "2.1"
short_description: Set owner short_description: Set owner
description: description:
- Set owner of files or directories - Set owner of files or directories.
options: options:
path: path:
description: description:
- Path to be used for changing owner - Path to be used for changing owner.
required: yes
type: path type: path
required: yes
user: user:
description: description:
- Name to be used for changing owner - Name to be used for changing owner.
type: str
required: yes required: yes
recurse: recurse:
description: description:
- Indicates if the owner should be changed recursively - Indicates if the owner should be changed recursively.
type: bool type: bool
default: 'no' default: no
seealso: seealso:
- module: win_file - module: win_file
author: author:
@ -37,7 +38,7 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: Change owner of Path - name: Change owner of path
win_owner: win_owner:
path: C:\apache path: C:\apache
user: apache user: apache

15
lib/ansible/modules/windows/win_package.py
View file

@ -32,6 +32,7 @@ options:
module will escape the arguments as necessary, it is recommended to use a 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 string when dealing with MSI packages due to the unique escaping issues
with msiexec. with msiexec.
type: str
chdir: chdir:
description: description:
- Set the specified path as the current working directory before installing - 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 - Will check the existing of the service specified and use the result to
determine whether the package is already installed. determine whether the package is already installed.
- You can use this in conjunction with C(product_id) and other C(creates_*). - You can use this in conjunction with C(product_id) and other C(creates_*).
type: str
version_added: '2.4' version_added: '2.4'
creates_version: creates_version:
description: description:
@ -57,12 +59,13 @@ options:
use the result to determine whether the package is already installed. use the result to determine whether the package is already installed.
- C(creates_path) MUST be set and is a file. - C(creates_path) MUST be set and is a file.
- You can use this in conjunction with C(product_id) and other C(creates_*). - You can use this in conjunction with C(product_id) and other C(creates_*).
type: str
version_added: '2.4' version_added: '2.4'
expected_return_code: expected_return_code:
description: description:
- One or more return codes from the package installation that indicates - One or more return codes from the package installation that indicates
success. 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). C(3010).
- A return code of C(3010) usually means that a reboot is required, the - 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). C(reboot_required) return value is set if the return code is C(3010).
@ -71,6 +74,7 @@ options:
password: password:
description: description:
- The password for C(user_name), must be set when C(user_name) is. - The password for C(user_name), must be set when C(user_name) is.
type: str
aliases: [ user_password ] aliases: [ user_password ]
path: path:
description: description:
@ -85,6 +89,7 @@ options:
- If C(state=present) then this value MUST be set. - If C(state=present) then this value MUST be set.
- If C(state=absent) then this value does not need to be set if - If C(state=absent) then this value does not need to be set if
C(product_id) is. C(product_id) is.
type: str
product_id: product_id:
description: description:
- The product id of the installed packaged. - 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 - 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 or a network share and credential delegation is not being used. The
C(creates_*) options can be used instead but is not recommended. C(creates_*) options can be used instead but is not recommended.
type: str
aliases: [ productid ] aliases: [ productid ]
state: state:
description: description:
- Whether to install or uninstall the package. - Whether to install or uninstall the package.
- The module uses C(product_id) and whether it exists at the registry path - 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. to see whether it needs to install or uninstall the package.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
aliases: [ ensure ] aliases: [ ensure ]
@ -113,6 +120,7 @@ options:
file share. file share.
- This is only needed if the WinRM transport is over an auth method that - This is only needed if the WinRM transport is over an auth method that
does not support credential delegation like Basic or NTLM. does not support credential delegation like Basic or NTLM.
type: str
aliases: [ user_name ] aliases: [ user_name ]
validate_certs: validate_certs:
description: description:
@ -120,10 +128,9 @@ options:
used on personally controlled sites using self-signed certificates. used on personally controlled sites using self-signed certificates.
- Before Ansible 2.4 this defaulted to C(no). - Before Ansible 2.4 this defaulted to C(no).
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
notes: 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 - 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 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 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. to true if the executable return code is 3010.
returned: always returned: always
type: bool type: bool
sample: True sample: true
stdout: stdout:
description: The stdout stream of the package process. description: The stdout stream of the package process.
returned: failure during install or uninstall returned: failure during install or uninstall

10
lib/ansible/modules/windows/win_pagefile.py
View file

@ -24,6 +24,7 @@ options:
drive: drive:
description: description:
- The drive of the pagefile. - The drive of the pagefile.
type: str
initial_size: initial_size:
description: description:
- The initial size of the pagefile in megabytes. - The initial size of the pagefile in megabytes.
@ -36,12 +37,12 @@ options:
description: description:
- Override the current pagefile on the drive. - Override the current pagefile on the drive.
type: bool type: bool
default: 'yes' default: yes
system_managed: system_managed:
description: description:
- Configures current pagefile to be managed by the system. - Configures current pagefile to be managed by the system.
type: bool type: bool
default: 'no' default: no
automatic: automatic:
description: description:
- Configures AutomaticManagedPagefile for the entire system. - Configures AutomaticManagedPagefile for the entire system.
@ -50,15 +51,16 @@ options:
description: description:
- Remove all pagefiles in the system, not including automatic managed. - Remove all pagefiles in the system, not including automatic managed.
type: bool type: bool
default: 'no' default: no
test_path: test_path:
description: description:
- Use Test-Path on the drive to make sure the drive is accessible before creating the pagefile. - Use Test-Path on the drive to make sure the drive is accessible before creating the pagefile.
type: bool type: bool
default: 'yes' default: yes
state: state:
description: description:
- State of the pagefile. - State of the pagefile.
type: str
choices: [ absent, present, query ] choices: [ absent, present, query ]
default: query default: query
notes: notes:

2
lib/ansible/modules/windows/win_partition.py
View file

@ -62,8 +62,8 @@ options:
description: description:
- Sets the partition offline. - Sets the partition offline.
- Adding a mount point (such as a drive letter) will cause the partition to go online again. - Adding a mount point (such as a drive letter) will cause the partition to go online again.
required: no
type: bool type: bool
required: no
mbr_type: mbr_type:
description: description:
- Specify the partition's MBR type if the disk's partition style is MBR. - Specify the partition's MBR type if the disk's partition style is MBR.

8
lib/ansible/modules/windows/win_path.py
View file

@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: win_path module: win_path
version_added: "2.3" version_added: "2.3"
@ -22,6 +22,7 @@ options:
name: name:
description: description:
- Target path environment variable name. - Target path environment variable name.
type: str
default: PATH default: PATH
elements: elements:
description: 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. - 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 - 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. backslashes in YAML require quotes.
type: list
required: yes required: yes
state: state:
description: description:
- Whether the path elements specified in C(elements) should be present or absent. - Whether the path elements specified in C(elements) should be present or absent.
type: str
choices: [ absent, present ] choices: [ absent, present ]
scope: scope:
description: description:
- The level at which the environment variable specified by C(name) should be managed (either for the current user or global machine scope). - 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 ] choices: [ machine, user ]
default: machine default: machine
notes: notes:
@ -51,7 +55,7 @@ notes:
This means that the minority of windows applications which can have This means that the minority of windows applications which can have
their environment changed without restarting will not be notified and their environment changed without restarting will not be notified and
therefore will need restarting to pick up new environment settings. 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. log out and in again before they become available.
seealso: seealso:
- module: win_environment - module: win_environment

27
lib/ansible/modules/windows/win_pester.py
View file

@ -24,6 +24,7 @@ options:
description: description:
- Path to a pester test file or a folder where tests can be found. - 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. - If the path is a folder, the module will consider all ps1 files as Pester tests.
type: str
required: true required: true
version: version:
description: description:
@ -32,19 +33,6 @@ author:
- Erwan Quelin (@equelin) - 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''' EXAMPLES = r'''
- name: Get facts - name: Get facts
setup: setup:
@ -66,3 +54,16 @@ EXAMPLES = r'''
path: C:\Pester\test01.test.ps1 path: C:\Pester\test01.test.ps1
version: 4.1.0 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
'''

16
lib/ansible/modules/windows/win_ping.py
View file

@ -26,10 +26,8 @@ options:
description: description:
- Alternate data to return instead of 'pong'. - Alternate data to return instead of 'pong'.
- If this parameter is set to C(crash), the module will cause an exception. - If this parameter is set to C(crash), the module will cause an exception.
type: str
default: pong default: pong
notes:
- For non-Windows targets, use the M(ping) module instead.
- For Network targets, use the M(net_ping) module instead.
seealso: seealso:
- module: ping - module: ping
author: author:
@ -40,17 +38,17 @@ EXAMPLES = r'''
# Test connectivity to a windows host # Test connectivity to a windows host
# ansible winserver -m win_ping # ansible winserver -m win_ping
# Example from an Ansible Playbook - name: Example from an Ansible Playbook
- win_ping: win_ping:
# Induce an exception to see what happens - name: Induce an exception to see what happens
- win_ping: win_ping:
data: crash data: crash
''' '''
RETURN = ''' RETURN = r'''
ping: ping:
description: value provided with the data parameter description: Value provided with the data parameter.
returned: success returned: success
type: str type: str
sample: pong sample: pong

18
lib/ansible/modules/windows/win_power_plan.py
View file

@ -8,7 +8,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: win_power_plan module: win_power_plan
short_description: Changes the power plan of a Windows system short_description: Changes the power plan of a Windows system
@ -22,14 +22,16 @@ requirements:
options: options:
name: name:
description: description:
- String value that indicates the desired power plan. The power plan must already be - String value that indicates the desired power plan.
present on the system. Commonly there will be options for C(balanced) and C(high performance). - 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 required: yes
author: author:
- Noah Sparks (@nwsparks) - Noah Sparks (@nwsparks)
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Change power plan to high performance - name: Change power plan to high performance
win_power_plan: win_power_plan:
name: high performance name: high performance
@ -37,17 +39,17 @@ EXAMPLES = '''
RETURN = r''' RETURN = r'''
power_plan_name: power_plan_name:
description: Value of the intended power plan description: Value of the intended power plan.
returned: always returned: always
type: str type: str
sample: balanced sample: balanced
power_plan_enabled: power_plan_enabled:
description: State of the intended power plan description: State of the intended power plan.
returned: success returned: success
type: bool type: bool
sample: True sample: true
all_available_plans: 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 returned: always
type: dict type: dict
sample: | sample: |

2
lib/ansible/modules/windows/win_product_facts.ps1
View file

@ -1,6 +1,6 @@
#!powershell #!powershell
# Copyright: (c) 2017, Dag Wieers (dagwieers) <dag@wieers.com> # Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
#AnsibleRequires -CSharpUtil Ansible.Basic #AnsibleRequires -CSharpUtil Ansible.Basic

6
lib/ansible/modules/windows/win_product_facts.py
View file

@ -1,14 +1,14 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# Copyright: (c) 2017, Dag Wieers (dagwieers) <dag@wieers.com> # Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
ANSIBLE_METADATA = {'metadata_version': '1.1', ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: win_product_facts module: win_product_facts
short_description: Provides Windows product information (product id, product key) short_description: Provides Windows product information (product id, product key)
@ -25,7 +25,7 @@ EXAMPLES = r'''
win_product_facts: win_product_facts:
''' '''
RETURN = ''' RETURN = r'''
ansible_facts: ansible_facts:
description: returned facts by this module description: returned facts by this module
returned: always returned: always

35
lib/ansible/modules/windows/win_psexec.py
View file

@ -14,14 +14,15 @@ module: win_psexec
version_added: '2.3' version_added: '2.3'
short_description: Runs commands (remotely) as another (privileged) user short_description: Runs commands (remotely) as another (privileged) user
description: description:
- Run commands (remotely) through the PsExec service - Run commands (remotely) through the PsExec service.
- Run commands as another (domain) user (with elevated privileges) - Run commands as another (domain) user (with elevated privileges).
requirements: requirements:
- Microsoft PsExec - Microsoft PsExec
options: options:
command: command:
description: description:
- The command line to run through PsExec (limited to 260 characters). - The command line to run through PsExec (limited to 260 characters).
type: str
required: yes required: yes
executable: executable:
description: description:
@ -37,10 +38,12 @@ options:
description: description:
- The (remote) user to run the command as. - The (remote) user to run the command as.
- If not provided, the current user is used. - If not provided, the current user is used.
type: str
password: password:
description: description:
- The password for the (remote) user to run the command as. - The password for the (remote) user to run the command as.
- This is mandatory in order authenticate yourself. - This is mandatory in order authenticate yourself.
type: str
chdir: chdir:
description: description:
- Run the command from this (remote) directory. - Run the command from this (remote) directory.
@ -50,23 +53,23 @@ options:
- Do not display the startup banner and copyright message. - Do not display the startup banner and copyright message.
- This only works for specific versions of the PsExec binary. - This only works for specific versions of the PsExec binary.
type: bool type: bool
default: 'no' default: no
version_added: '2.4' version_added: '2.4'
noprofile: noprofile:
description: description:
- Run the command without loading the account's profile. - Run the command without loading the account's profile.
type: bool type: bool
default: 'no' default: no
elevated: elevated:
description: description:
- Run the command with elevated privileges. - Run the command with elevated privileges.
type: bool type: bool
default: 'no' default: no
interactive: interactive:
description: description:
- Run the program so that it interacts with the desktop on the remote system. - Run the program so that it interacts with the desktop on the remote system.
type: bool type: bool
default: 'no' default: no
session: session:
description: description:
- Specifies the session ID to use. - Specifies the session ID to use.
@ -78,22 +81,16 @@ options:
description: description:
- Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group). - Run the command as limited user (strips the Administrators group and allows only privileges assigned to the Users group).
type: bool type: bool
default: 'no' default: no
system: system:
description: description:
- Run the remote command in the System account. - Run the remote command in the System account.
type: bool type: bool
default: 'no' default: no
priority: priority:
description: description:
- Used to run the command at a different priority. - Used to run the command at a different priority.
choices: choices: [ abovenormal, background, belownormal, high, low, realtime ]
- background
- low
- belownormal
- abovenormal
- high
- realtime
timeout: timeout:
description: description:
- The connection timeout in seconds - The connection timeout in seconds
@ -103,7 +100,7 @@ options:
- Wait for the application to terminate. - Wait for the application to terminate.
- Only use for non-interactive applications. - Only use for non-interactive applications.
type: bool type: bool
default: 'yes' default: yes
notes: notes:
- More information related to Microsoft PsExec is available from - More information related to Microsoft PsExec is available from
U(https://technet.microsoft.com/en-us/sysinternals/bb897553.aspx) U(https://technet.microsoft.com/en-us/sysinternals/bb897553.aspx)
@ -153,17 +150,17 @@ cmd:
type: str type: str
sample: psexec.exe -nobanner \\remote_server -u "DOMAIN\Administrator" -p "some_password" -accepteula E:\setup.exe sample: psexec.exe -nobanner \\remote_server -u "DOMAIN\Administrator" -p "some_password" -accepteula E:\setup.exe
rc: rc:
description: The return code for the command description: The return code for the command.
returned: always returned: always
type: int type: int
sample: 0 sample: 0
stdout: stdout:
description: The standard output from the command description: The standard output from the command.
returned: always returned: always
type: str type: str
sample: Success. sample: Success.
stderr: stderr:
description: The error output from the command description: The error output from the command.
returned: always returned: always
type: str type: str
sample: Error 15 running E:\setup.exe sample: Error 15 running E:\setup.exe

20
lib/ansible/modules/windows/win_psmodule.py
View file

@ -22,22 +22,26 @@ options:
name: name:
description: description:
- Name of the powershell module that has to be installed. - Name of the powershell module that has to be installed.
type: str
required: yes required: yes
allow_clobber: allow_clobber:
description: 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. - 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 type: bool
default: 'no' default: no
repository: repository:
description: description:
- Name of the custom repository to register or use. - Name of the custom repository to register or use.
type: str
url: url:
description: description:
- URL of the custom repository to register. - URL of the custom repository to register.
type: str
state: state:
description: description:
- If C(present) a new module is installed. - If C(present) a new module is installed.
- If C(absent) a module is removed. - If C(absent) a module is removed.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
notes: notes:
@ -48,7 +52,7 @@ author:
- Daniele Lazzari (@dlazz) - Daniele Lazzari (@dlazz)
''' '''
EXAMPLES = ''' EXAMPLES = r'''
--- ---
- name: Add a powershell module - name: Add a powershell module
win_psmodule: win_psmodule:
@ -80,21 +84,21 @@ EXAMPLES = '''
state: absent state: absent
''' '''
RETURN = ''' RETURN = r'''
--- ---
output: output:
description: a message describing the task result. description: A message describing the task result.
returned: always returned: always
sample: "Module PowerShellCookbook installed" sample: "Module PowerShellCookbook installed"
type: str type: str
nuget_changed: nuget_changed:
description: true when Nuget package provider is installed description: True when Nuget package provider is installed.
returned: always returned: always
type: bool type: bool
sample: True sample: true
repository_changed: repository_changed:
description: true when a custom repository is installed or removed description: True when a custom repository is installed or removed.
returned: always returned: always
type: bool type: bool
sample: True sample: true
''' '''

6
lib/ansible/modules/windows/win_psrepository.py
View file

@ -23,26 +23,30 @@ options:
name: name:
description: description:
- Name of the repository to work with. - Name of the repository to work with.
type: str
required: yes required: yes
source: source:
description: description:
- Specifies the URI for discovering and installing modules from this repository. - 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. - A URI can be a NuGet server feed (most common situation), HTTP, HTTPS, FTP or file location.
type: str
state: state:
description: description:
- If C(present) a new repository is added or updated. - If C(present) a new repository is added or updated.
- If C(absent) a repository is removed. - If C(absent) a repository is removed.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
installation_policy: installation_policy:
description: description:
- Sets the C(InstallationPolicy) of a repository. - Sets the C(InstallationPolicy) of a repository.
- Will default to C(trusted) when creating a new repository. - Will default to C(trusted) when creating a new repository.
type: str
choices: [ trusted, untrusted ] choices: [ trusted, untrusted ]
notes: notes:
- The PowerShellGet module (version 1.6.0 or newer) and the NuGet package provider (version 2.8.5.201 or newer) are required. - 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. - 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: seealso:
- module: win_psmodule - module: win_psmodule
author: author:

9
lib/ansible/modules/windows/win_rabbitmq_plugin.py
View file

@ -19,6 +19,7 @@ options:
names: names:
description: description:
- Comma-separated list of plugin names. - Comma-separated list of plugin names.
type: str
required: yes required: yes
aliases: [ name ] aliases: [ name ]
new_only: new_only:
@ -26,15 +27,17 @@ options:
- Only enable missing plugins. - Only enable missing plugins.
- Does not disable plugins that are not in the names list. - Does not disable plugins that are not in the names list.
type: bool type: bool
default: "no" default: no
state: state:
description: description:
- Specify if plugins are to be enabled or disabled. - Specify if plugins are to be enabled or disabled.
type: str
choices: [ disabled, enabled ] choices: [ disabled, enabled ]
default: enabled default: enabled
prefix: prefix:
description: description:
- Specify a custom install prefix to a Rabbit. - Specify a custom install prefix to a Rabbit.
type: str
author: author:
- Artem Zinenko (@ar7z1) - Artem Zinenko (@ar7z1)
''' '''
@ -48,12 +51,12 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
enabled: enabled:
description: list of plugins enabled during task run description: List of plugins enabled during task run.
returned: always returned: always
type: list type: list
sample: ["rabbitmq_management"] sample: ["rabbitmq_management"]
disabled: disabled:
description: list of plugins disabled during task run description: List of plugins disabled during task run.
returned: always returned: always
type: list type: list
sample: ["rabbitmq_management"] sample: ["rabbitmq_management"]

4
lib/ansible/modules/windows/win_reboot.py
View file

@ -13,6 +13,7 @@ module: win_reboot
short_description: Reboot a windows machine short_description: Reboot a windows machine
description: description:
- Reboot a Windows machine, wait for it to go down, come back up, and respond to commands. - 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' version_added: '2.1'
options: options:
pre_reboot_delay: 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. - 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. - 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. 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: seealso:
- module: reboot - module: reboot
author: author:
@ -109,7 +109,7 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
rebooted: rebooted:
description: true if the machine was rebooted description: True if the machine was rebooted.
returned: always returned: always
type: bool type: bool
sample: true sample: true

6
lib/ansible/modules/windows/win_reg_stat.py
View file

@ -23,11 +23,13 @@ description:
options: options:
path: path:
description: The full registry key path including the hive to search for. description: The full registry key path including the hive to search for.
type: str
required: yes required: yes
aliases: [ key ] aliases: [ key ]
name: name:
description: 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. - 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 ] aliases: [ entry, value, property ]
seealso: seealso:
- module: win_regedit - module: win_regedit
@ -54,12 +56,12 @@ changed:
description: Whether anything was changed. description: Whether anything was changed.
returned: always returned: always
type: bool type: bool
sample: True sample: true
exists: exists:
description: States whether the registry key/property exists. description: States whether the registry key/property exists.
returned: success and path/property exists returned: success and path/property exists
type: bool type: bool
sample: True sample: true
properties: properties:
description: A dictionary containing all the properties and their values in the registry key. description: A dictionary containing all the properties and their values in the registry key.
returned: success, path exists and property not specified returned: success, path exists and property not specified

15
lib/ansible/modules/windows/win_regedit.py
View file

@ -28,6 +28,7 @@ options:
- Name of the registry path. - Name of the registry path.
- 'Should be in one of the following registry hives: HKCC, HKCR, HKCU, - 'Should be in one of the following registry hives: HKCC, HKCR, HKCU,
HKLM, HKU.' HKLM, HKU.'
type: str
required: yes required: yes
aliases: [ key ] aliases: [ key ]
name: name:
@ -35,6 +36,7 @@ options:
- Name of the registry entry in the above C(path) parameters. - Name of the registry entry in the above C(path) parameters.
- If not provided, or empty then the '(Default)' property for the key will - If not provided, or empty then the '(Default)' property for the key will
be used. be used.
type: str
aliases: [ entry ] aliases: [ entry ]
data: data:
description: description:
@ -51,15 +53,18 @@ options:
or a hex value. or a hex value.
- Multistring values should be passed in as a list. - Multistring values should be passed in as a list.
- See the examples for more details on how to format this data. - See the examples for more details on how to format this data.
type: str
type: type:
description: description:
- The registry value data type. - The registry value data type.
type: str
choices: [ binary, dword, expandstring, multistring, string, qword ] choices: [ binary, dword, expandstring, multistring, string, qword ]
default: string default: string
aliases: [ datatype ] aliases: [ datatype ]
state: state:
description: description:
- The state of the registry entry. - The state of the registry entry.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
delete_key: delete_key:
@ -68,7 +73,7 @@ options:
- If C(no) then it will only clear out the '(Default)' property for - If C(no) then it will only clear out the '(Default)' property for
that key. that key.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
hive: hive:
description: description:
@ -193,13 +198,13 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
data_changed: 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 returned: success
type: bool type: bool
sample: False sample: false
data_type_changed: 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 returned: success
type: bool type: bool
sample: True sample: true
''' '''

43
lib/ansible/modules/windows/win_region.py
View file

@ -23,21 +23,24 @@ options:
- The location to set for the current user, see - The location to set for the current user, see
U(https://msdn.microsoft.com/en-us/library/dd374073.aspx) U(https://msdn.microsoft.com/en-us/library/dd374073.aspx)
for a list of GeoIDs you can use and what location it relates to. 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. set.
type: str
format: format:
description: description:
- The language format to set for the current user, see - The language format to set for the current user, see
U(https://msdn.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx) 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 for a list of culture names to use.
C(location) or C(unicode_language) is not set. - This needs to be set if C(location) or C(unicode_language) is not set.
type: str
unicode_language: unicode_language:
description: description:
- The unicode language format to set for all users, see - The unicode language format to set for all users, see
U(https://msdn.microsoft.com/en-us/library/system.globalization.cultureinfo.aspx) 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 for a list of culture names to use.
C(location) or C(format) is not set. After setting this - 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. value a reboot is required for it to take effect.
type: str
copy_settings: copy_settings:
description: description:
- This will copy the current format and location values to new user - 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. If this process runs then it will always result in a
change. change.
type: bool type: bool
default: 'no' default: no
seealso: seealso:
- module: win_timezone - module: win_timezone
author: author:
@ -54,28 +57,30 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
# Set the region format to English United States - name: Set the region format to English United States
- win_region: win_region:
format: en-US format: en-US
# Set the region format to English Australia and copy settings to new profiles - name: Set the region format to English Australia and copy settings to new profiles
- win_region: win_region:
format: en-AU format: en-AU
copy_settings: yes copy_settings: yes
# Set the unicode language to English Great Britain, reboot if required - name: Set the location to United States
- win_region: 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 unicode_language: en-GB
register: result register: result
- win_reboot: - win_reboot:
when: result.restart_required when: result.restart_required
# Set the location to United States # Reboot when format, location or unicode has changed
- win_region: - name: Set format, location and unicode to English Australia and copy settings, reboot if required
location: 244
# Set format, location and unicode to English Australia and copy settings, reboot if required
- win_region: - win_region:
location: 12 location: 12
format: en-AU format: en-AU
@ -88,8 +93,8 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
restart_required: 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 returned: success
type: bool type: bool
sample: True sample: true
''' '''

9
lib/ansible/modules/windows/win_regmerge.py
View file

@ -28,22 +28,23 @@ options:
path: path:
description: description:
- The full path including file name to the registry file on the remote machine to be merged - The full path including file name to the registry file on the remote machine to be merged
required: yes
type: path type: path
required: yes
compare_key: compare_key:
description: 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. - 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 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. If not supplied, or the registry key is not found, no comparison will be made, and the module will report changed.
type: str
notes: notes:
- Organise your registry files so that they contain a single root registry - Organise your registry files so that they contain a single root registry
key if you want to use the compare_to functionality. 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 described in the file. If registry settings have been modified externally
the module will merge the contents of the file but continue to report the module will merge the contents of the file but continue to report
differences on subsequent runs. differences on subsequent runs.
To force registry change, use M(win_regedit) with state=absent before - To force registry change, use M(win_regedit) with C(state=absent) before
using M(win_regmerge). using C(win_regmerge).
seealso: seealso:
- module: win_reg_stat - module: win_reg_stat
- module: win_regedit - module: win_regedit

21
lib/ansible/modules/windows/win_robocopy.py
View file

@ -24,28 +24,31 @@ options:
src: src:
description: description:
- Source file/directory to sync. - Source file/directory to sync.
required: yes
type: path type: path
required: yes
dest: dest:
description: description:
- Destination file/directory to sync (Will receive contents of src). - Destination file/directory to sync (Will receive contents of src).
required: yes
type: path type: path
required: yes
recurse: recurse:
description: description:
- Includes all subdirectories (Toggles the C(/e) flag to RoboCopy). - Includes all subdirectories (Toggles the C(/e) flag to RoboCopy).
- If C(flags) is set, this will be ignored. - If C(flags) is set, this will be ignored.
type: bool type: bool
default: 'no' default: no
purge: purge:
description: description:
- Deletes any files/directories found in the destination that do not exist in the source. - 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 type: bool
default: 'no' default: no
flags: flags:
description: 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: 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, - 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. not from the master to the remote machine.
@ -97,7 +100,7 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
cmd: cmd:
description: The used command line description: The used command line.
returned: always returned: always
type: str type: str
sample: robocopy C:\DirectoryOne C:\DirectoryTwo /e /purge sample: robocopy C:\DirectoryOne C:\DirectoryTwo /e /purge
@ -115,12 +118,12 @@ recurse:
description: Whether or not the recurse flag was toggled. description: Whether or not the recurse flag was toggled.
returned: always returned: always
type: bool type: bool
sample: False sample: false
purge: purge:
description: Whether or not the purge flag was toggled. description: Whether or not the purge flag was toggled.
returned: always returned: always
type: bool type: bool
sample: False sample: false
flags: flags:
description: Any flags passed in by the user. description: Any flags passed in by the user.
returned: always returned: always

5
lib/ansible/modules/windows/win_route.py
View file

@ -21,12 +21,14 @@ description:
options: options:
destination: destination:
description: 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 required: yes
gateway: gateway:
description: description:
- The gateway used by the static route. - The gateway used by the static route.
- If C(gateway) is not provided it will be set to C(0.0.0.0). - If C(gateway) is not provided it will be set to C(0.0.0.0).
type: str
metric: metric:
description: description:
- Metric used by the static route. - Metric used by the static route.
@ -36,6 +38,7 @@ options:
description: description:
- If C(absent), it removes a network static route. - If C(absent), it removes a network static route.
- If C(present), it adds a network static route. - If C(present), it adds a network static route.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
notes: notes:

8
lib/ansible/modules/windows/win_say.py
View file

@ -25,6 +25,7 @@ options:
- The text to be spoken. - The text to be spoken.
- Use either C(msg) or C(msg_file). - Use either C(msg) or C(msg_file).
- Optional so that you can use this module just to play sounds. - Optional so that you can use this module just to play sounds.
type: str
msg_file: msg_file:
description: description:
- Full path to a windows format text file containing the text to be spokend. - 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. - 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. - 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). Example voice names from Windows 10 are C(Microsoft Zira Desktop) and C(Microsoft Hazel Desktop).
type: str
default: system default voice default: system default voice
speech_speed: speech_speed:
description: description:
@ -98,17 +100,17 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
message_text: message_text:
description: the text that the module attempted to speak description: The text that the module attempted to speak.
returned: success returned: success
type: str type: str
sample: "Warning, deployment commencing in 5 minutes." sample: "Warning, deployment commencing in 5 minutes."
voice: voice:
description: the voice used to speak the text. description: The voice used to speak the text.
returned: success returned: success
type: str type: str
sample: Microsoft Hazel Desktop sample: Microsoft Hazel Desktop
voice_info: 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 returned: when requested voice could not be loaded
type: str type: str
sample: Could not load voice TestVoice, using system default voice sample: Could not load voice TestVoice, using system default voice

55
lib/ansible/modules/windows/win_scheduled_task.py
View file

@ -20,6 +20,7 @@ options:
name: name:
description: description:
- The name of the scheduled task without the path. - The name of the scheduled task without the path.
type: str
required: yes required: yes
path: path:
description: description:
@ -28,11 +29,13 @@ options:
already exist. already exist.
- Will remove the folder when C(state=absent) and there are no tasks left - Will remove the folder when C(state=absent) and there are no tasks left
in the folder. in the folder.
type: str
default: \ default: \
state: state:
description: description:
- When C(state=present) will ensure the task exists. - When C(state=present) will ensure the task exists.
- When C(state=absent) will ensure the task does not exist. - When C(state=absent) will ensure the task does not exist.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
@ -52,13 +55,16 @@ options:
path: path:
description: description:
- The path to the executable for the ExecAction. - The path to the executable for the ExecAction.
type: str
required: yes required: yes
arguments: arguments:
description: description:
- An argument string to supply for the executable. - An argument string to supply for the executable.
type: str
working_directory: working_directory:
description: description:
- The working directory to run the executable from. - The working directory to run the executable from.
type: str
version_added: '2.5' version_added: '2.5'
# Trigger options # Trigger options
@ -78,6 +84,7 @@ options:
description: description:
- The trigger type, this value controls what below options are - The trigger type, this value controls what below options are
required. required.
type: str
required: yes required: yes
choices: [ boot, daily, event, idle, logon, monthlydow, monthly, registration, time, weekly, session_state_change ] choices: [ boot, daily, event, idle, logon, monthlydow, monthly, registration, time, weekly, session_state_change ]
enabled: enabled:
@ -96,15 +103,18 @@ options:
C(time), C(weekly), (session_state_change). C(time), C(weekly), (session_state_change).
- Optional for the rest of the trigger types. - Optional for the rest of the trigger types.
- This is in ISO 8601 DateTime format C(YYYY-MM-DDThh:mm:ss). - This is in ISO 8601 DateTime format C(YYYY-MM-DDThh:mm:ss).
type: str
end_boundary: end_boundary:
description: description:
- The end time for when the trigger is deactivated. - The end time for when the trigger is deactivated.
- This is in ISO 8601 DateTime format C(YYYY-MM-DDThh:mm:ss). - This is in ISO 8601 DateTime format C(YYYY-MM-DDThh:mm:ss).
type: str
execution_time_limit: execution_time_limit:
description: description:
- The maximum amount of time that the task is allowed to run for. - The maximum amount of time that the task is allowed to run for.
- Optional for all the trigger types. - 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). - Is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S).
type: str
delay: delay:
description: description:
- The time to delay the task from running once the trigger has been - 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), - Optional when C(type) is C(boot), C(event), C(logon),
C(registration), C(session_state_change). 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). - 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: random_delay:
description: description:
- The delay time that is randomly added to the start time of the - 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), - Optional when C(type) is C(daily), C(monthlydow), C(monthly),
C(time), C(weekly). 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). - Is in the ISO 8601 Duration format C(P[n]Y[n]M[n]DT[n]H[n]M[n]S).
type: str
subscription: subscription:
description: description:
- Only used and is required for C(type=event). - Only used and is required for C(type=event).
- The XML query string that identifies the event that fires the - The XML query string that identifies the event that fires the
trigger. trigger.
type: str
user_id: user_id:
description: description:
- The username that the trigger will target. - 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 - 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 group logs on, leave this as null and set C(group) to the group you
wish to trigger. wish to trigger.
type: str
days_of_week: days_of_week:
description: description:
- The days of the week for the trigger. - The days of the week for the trigger.
@ -139,6 +153,7 @@ options:
instead of mon. instead of mon.
- Required when C(type) is C(weekly), C(type=session_state_change). - Required when C(type) is C(weekly), C(type=session_state_change).
- Optional when C(type=monthlydow). - Optional when C(type=monthlydow).
type: str
days_of_month: days_of_month:
description: description:
- The days of the month from 1 to 31 for the triggers. - 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). use C(run_on_last_day_of_month).
- Can be a list or comma separated string of day numbers. - Can be a list or comma separated string of day numbers.
- Required when C(type=monthly). - Required when C(type=monthly).
type: str
weeks_of_month: weeks_of_month:
description: description:
- The weeks of the month for the trigger. - The weeks of the month for the trigger.
- Can be a list or comma separated string of the numbers 1 to 4 - Can be a list or comma separated string of the numbers 1 to 4
representing the first to 4th week of the month. representing the first to 4th week of the month.
- Optional when C(type=monthlydow). - Optional when C(type=monthlydow).
type: str
months_of_year: months_of_year:
description: description:
- The months of the year for the trigger. - The months of the year for the trigger.
- Can be a list or comma separated string of full month names e.g. - Can be a list or comma separated string of full month names e.g.
march instead of mar. march instead of mar.
- Optional when C(type) is C(monthlydow), C(monthly). - Optional when C(type) is C(monthlydow), C(monthly).
type: str
run_on_last_week_of_month: run_on_last_week_of_month:
description: description:
- Boolean value that sets whether the task runs on the last week of the - 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 - The interval of weeks to run on, e.g. C(1) means every week while
C(2) means every other week. C(2) means every other week.
- Optional when C(type=weekly). - Optional when C(type=weekly).
type: int
repetition: repetition:
description: 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 - 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: display_name:
description: description:
- The name of the user/group that is displayed in the Task Scheduler UI. - The name of the user/group that is displayed in the Task Scheduler UI.
type: str
version_added: '2.5' version_added: '2.5'
group: group:
description: description:
@ -209,6 +229,7 @@ options:
- C(group) and C(username) are exclusive to each other and cannot be set - C(group) and C(username) are exclusive to each other and cannot be set
at the same time. at the same time.
- C(logon_type) can either be not set or equal C(group). - C(logon_type) can either be not set or equal C(group).
type: str
version_added: '2.5' version_added: '2.5'
logon_type: logon_type:
description: description:
@ -223,20 +244,23 @@ options:
- C(group) means that the task will run as a group. - C(group) means that the task will run as a group.
- C(service_account) means that a service account like System, Local - C(service_account) means that a service account like System, Local
Service or Network Service will run the task. Service or Network Service will run the task.
type: str
choices: [ none, password, s4u, interactive_token, group, service_account, token_or_password ] choices: [ none, password, s4u, interactive_token, group, service_account, token_or_password ]
version_added: '2.5' version_added: '2.5'
run_level: run_level:
description: description:
- The level of user rights used to run the task. - The level of user rights used to run the task.
- If not specified the task will be created with limited rights. - If not specified the task will be created with limited rights.
type: str
choices: [ limited, highest ] choices: [ limited, highest ]
version_added: '2.4'
aliases: [ runlevel ] aliases: [ runlevel ]
version_added: '2.4'
username: username:
description: description:
- The user to run the scheduled task as. - The user to run the scheduled task as.
- Will default to the current user under an interactive token if not - Will default to the current user under an interactive token if not
specified during creation. specified during creation.
type: str
aliases: [ user ] aliases: [ user ]
password: password:
description: description:
@ -245,35 +269,41 @@ options:
excluding the builtin service accounts. excluding the builtin service accounts.
- If set, will always result in a change unless C(update_password) is set - 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. to C(no) and no othr changes are required for the service.
type: str
version_added: '2.4' version_added: '2.4'
update_password: update_password:
description: description:
- Whether to update the password even when not other changes have occured. - 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. - When C(yes) will always result in a change when executing the module.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.5' version_added: '2.5'
# RegistrationInfo options # RegistrationInfo options
author: author:
description: description:
- The author of the task. - The author of the task.
type: str
version_added: '2.5' version_added: '2.5'
date: date:
description: description:
- The date when the task was registered. - The date when the task was registered.
type: str
version_added: '2.5' version_added: '2.5'
description: description:
description: description:
- The description of the task. - The description of the task.
type: str
version_added: '2.5' version_added: '2.5'
source: source:
description: description:
- The source of the task. - The source of the task.
type: str
version_added: '2.5' version_added: '2.5'
version: version:
description: description:
- The version number of the task. - The version number of the task.
type: str
version_added: '2.5' version_added: '2.5'
# Settings options # Settings options
@ -305,6 +335,7 @@ options:
- A task expires after the end_boundary has been exceeded for all triggers - A task expires after the end_boundary has been exceeded for all triggers
associated with the task. 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). - 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' version_added: '2.5'
disallow_start_if_on_batteries: disallow_start_if_on_batteries:
description: description:
@ -322,6 +353,7 @@ options:
- The amount of time allowed to complete the task. - The amount of time allowed to complete the task.
- When not set, the time limit is infinite. - 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). - 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' version_added: '2.5'
hidden: hidden:
description: description:
@ -362,6 +394,7 @@ options:
- The maximum allowed time is 31 days. - The maximum allowed time is 31 days.
- The minimum allowed time is 1 minute. - 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). - 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' version_added: '2.5'
run_only_if_idle: run_only_if_idle:
description: description:
@ -393,7 +426,7 @@ options:
version_added: '2.5' version_added: '2.5'
notes: notes:
- In Ansible 2.4 and earlier, this could only be run on Server 2012/Windows 8 - 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 option names and structure for actions and triggers of a service follow
the C(RegisteredTask) naming standard and requirements, it would be useful to 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). 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''' 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: win_scheduled_task:
name: TaskName name: TaskName
description: open command prompt description: open command prompt
@ -421,7 +454,7 @@ EXAMPLES = r'''
state: present state: present
enabled: yes 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: win_scheduled_task:
name: TaskName2 name: TaskName2
description: Run a PowerShell script description: Run a PowerShell script
@ -434,20 +467,20 @@ EXAMPLES = r'''
run_level: highest run_level: highest
state: present 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: win_scheduled_task:
name: TaskName2 name: TaskName2
username: DOMAIN\User username: DOMAIN\User
password: Password password: Password
logon_type: 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: win_scheduled_task:
name: TaskName2 name: TaskName2
username: DOMAIN\User username: DOMAIN\User
logon_type: s4u logon_type: s4u
- name: create task with multiple triggers - name: Create task with multiple triggers
win_scheduled_task: win_scheduled_task:
name: TriggerTask name: TriggerTask
path: \Custom path: \Custom
@ -458,7 +491,7 @@ EXAMPLES = r'''
- type: monthlydow - type: monthlydow
username: SYSTEM 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: win_scheduled_task:
name: TriggerTask name: TriggerTask
path: \Custom path: \Custom
@ -468,12 +501,12 @@ EXAMPLES = r'''
password: password password: password
update_password: no update_password: no
- name: disable a task that already exists - name: Disable a task that already exists
win_scheduled_task: win_scheduled_task:
name: TaskToDisable name: TaskToDisable
enabled: no 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: win_scheduled_task:
name: RepeatedTask name: RepeatedTask
description: open command prompt description: open command prompt

38
lib/ansible/modules/windows/win_scheduled_task_stat.py
View file

@ -23,11 +23,13 @@ description:
options: options:
path: path:
description: The folder path where the task lives. description: The folder path where the task lives.
type: str
default: \ default: \
name: name:
description: description:
- The name of the scheduled task to get information for. - The name of the scheduled task to get information for.
- If C(name) is set and exists, will return information on the task itself. - If C(name) is set and exists, will return information on the task itself.
type: str
seealso: seealso:
- module: win_scheduled_task - module: win_scheduled_task
author: author:
@ -35,17 +37,17 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: get information about a folder - name: Get information about a folder
win_scheduled_task_stat: win_scheduled_task_stat:
path: \folder name path: \folder name
register: task_folder_stat 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: win_scheduled_task_stat:
name: task name name: task name
register: task_stat 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: win_scheduled_task_stat:
path: \folder name path: \folder name
name: task name name: task name
@ -70,7 +72,7 @@ folder_exists:
description: Whether the folder set at path exists. description: Whether the folder set at path exists.
returned: always returned: always
type: bool type: bool
sample: True sample: true
folder_task_count: folder_task_count:
description: The number of tasks that exist in the folder. description: The number of tasks that exist in the folder.
returned: always returned: always
@ -172,12 +174,12 @@ settings:
command of the Context menu. command of the Context menu.
returned: '' returned: ''
type: bool type: bool
sample: True sample: true
allow_hard_terminate: allow_hard_terminate:
description: Whether the task can terminated by using TerminateProcess. description: Whether the task can terminated by using TerminateProcess.
returned: '' returned: ''
type: bool type: bool
sample: True sample: true
compatibility: compatibility:
description: The compatibility level of the task description: The compatibility level of the task
returned: '' returned: ''
@ -194,18 +196,18 @@ settings:
running on battery power. running on battery power.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
disallow_start_on_remote_app_session: disallow_start_on_remote_app_session:
description: Whether the task will not be started when in a remote app description: Whether the task will not be started when in a remote app
session. session.
returned: '' returned: ''
type: bool type: bool
sample: True sample: true
enabled: enabled:
description: Whether the task is enabled. description: Whether the task is enabled.
returned: '' returned: ''
type: bool type: bool
sample: True sample: true
execution_time_limit: execution_time_limit:
description: The amount of time allowed to complete the task. description: The amount of time allowed to complete the task.
returned: '' returned: ''
@ -215,7 +217,7 @@ settings:
description: Whether the task is hidden in the UI. description: Whether the task is hidden in the UI.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
idle_settings: idle_settings:
description: The idle settings of the task. description: The idle settings of the task.
returned: '' returned: ''
@ -267,40 +269,40 @@ settings:
state. state.
returned: '' returned: ''
type: bool type: bool
sample: True sample: true
run_only_if_network_available: run_only_if_network_available:
description: Whether the task will run only when a network is available. description: Whether the task will run only when a network is available.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
start_when_available: start_when_available:
description: Whether the task can start at any time after its scheduled description: Whether the task can start at any time after its scheduled
time has passed. time has passed.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
stop_if_going_on_batteries: stop_if_going_on_batteries:
description: Whether the task will be stopped if the computer begins to description: Whether the task will be stopped if the computer begins to
run on battery power. run on battery power.
returned: '' returned: ''
type: bool type: bool
sample: True sample: true
use_unified_scheduling_engine: use_unified_scheduling_engine:
description: Whether the task will use the unifed scheduling engine. description: Whether the task will use the unifed scheduling engine.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
volatile: volatile:
description: Whether thet ask is volatile. description: Whether thet ask is volatile.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
wake_to_run: wake_to_run:
description: Whether the task will wake the computer when it is time to description: Whether the task will wake the computer when it is time to
run the task. run the task.
returned: '' returned: ''
type: bool type: bool
sample: False sample: false
state: state:
description: Details on the state of the task description: Details on the state of the task
returned: name is specified and task exists returned: name is specified and task exists
@ -336,7 +338,7 @@ task_exists:
description: Whether the task at the folder exists. description: Whether the task at the folder exists.
returned: name is specified returned: name is specified
type: bool type: bool
sample: True sample: true
triggers: triggers:
description: A list of triggers. description: A list of triggers.
returned: name is specified and task exists returned: name is specified and task exists

11
lib/ansible/modules/windows/win_security_policy.py
View file

@ -28,16 +28,19 @@ options:
'File System' 'File System'
- If wanting to edit the C(Privilege Rights) section, use the - If wanting to edit the C(Privilege Rights) section, use the
M(win_user_right) module instead. M(win_user_right) module instead.
type: str
required: yes required: yes
key: key:
description: description:
- The ini key of the section or policy name to modify. - The ini key of the section or policy name to modify.
- The module will return an error if this key is invalid. - The module will return an error if this key is invalid.
type: str
required: yes required: yes
value: value:
description: description:
- The value for the ini key or policy name. - The value for the ini key or policy name.
- If the key takes in a boolean value then 0 = False and 1 = True. - If the key takes in a boolean value then 0 = False and 1 = True.
type: str
required: yes required: yes
notes: notes:
- This module uses the SecEdit.exe tool to configure the values, more details - This module uses the SecEdit.exe tool to configure the values, more details
@ -56,25 +59,25 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: change the guest account name - name: Change the guest account name
win_security_policy: win_security_policy:
section: System Access section: System Access
key: NewGuestName key: NewGuestName
value: Guest Account value: Guest Account
- name: set the maximum password age - name: Set the maximum password age
win_security_policy: win_security_policy:
section: System Access section: System Access
key: MaximumPasswordAge key: MaximumPasswordAge
value: 15 value: 15
- name: do not store passwords using reversible encryption - name: Do not store passwords using reversible encryption
win_security_policy: win_security_policy:
section: System Access section: System Access
key: ClearTextPassword key: ClearTextPassword
value: 0 value: 0
- name: enable system events - name: Enable system events
win_security_policy: win_security_policy:
section: Event Audit section: Event Audit
key: AuditSystemEvents key: AuditSystemEvents

15
lib/ansible/modules/windows/win_service.py
View file

@ -73,6 +73,7 @@ options:
path: path:
description: description:
- The path to the executable to set for the service. - The path to the executable to set for the service.
type: str
version_added: '2.3' version_added: '2.3'
password: password:
description: description:
@ -80,12 +81,14 @@ options:
- This and the C(username) argument must be supplied together. - This and the C(username) argument must be supplied together.
- If specifying C(LocalSystem), C(NetworkService) or C(LocalService) this field - If specifying C(LocalSystem), C(NetworkService) or C(LocalService) this field
must be an empty string and not null. must be an empty string and not null.
type: str
version_added: '2.3' version_added: '2.3'
start_mode: start_mode:
description: description:
- Set the startup type for the service. - Set the startup type for the service.
- A newly created service will default to C(auto). - A newly created service will default to C(auto).
- C(delayed) added in Ansible 2.3 - C(delayed) added in Ansible 2.3
type: str
choices: [ auto, delayed, disabled, manual ] choices: [ auto, delayed, disabled, manual ]
state: state:
description: description:
@ -99,6 +102,7 @@ options:
check the return value C(can_pause_and_continue). check the return value C(can_pause_and_continue).
- You can only pause a service that is already started. - You can only pause a service that is already started.
- A newly created service will default to C(stopped). - A newly created service will default to C(stopped).
type: str
choices: [ absent, paused, started, stopped, restarted ] choices: [ absent, paused, started, stopped, restarted ]
username: username:
description: description:
@ -107,9 +111,8 @@ options:
a local or domain account. a local or domain account.
- Set to C(LocalSystem) to use the SYSTEM account. - Set to C(LocalSystem) to use the SYSTEM account.
- A newly created service will default to C(LocalSystem). - A newly created service will default to C(LocalSystem).
type: str
version_added: '2.3' version_added: '2.3'
notes:
- For non-Windows targets, use the M(service) module instead.
seealso: seealso:
- module: service - module: service
- module: win_nssm - module: win_nssm
@ -263,7 +266,7 @@ can_pause_and_continue:
description: Whether the service can be paused and unpaused. description: Whether the service can be paused and unpaused.
returned: success and service exists returned: success and service exists
type: bool type: bool
sample: True sample: true
description: description:
description: The description of the service. description: The description of the service.
returned: success and service exists returned: success and service exists
@ -278,15 +281,15 @@ desktop_interact:
description: Whether the current user is allowed to interact with the desktop. description: Whether the current user is allowed to interact with the desktop.
returned: success and service exists returned: success and service exists
type: bool type: bool
sample: False sample: false
dependencies: dependencies:
description: A list of services that is depended by this service. description: A list of services that is depended by this service.
returned: success and service exists returned: success and service exists
type: list type: list
sample: False sample: false
depended_by: depended_by:
description: A list of services that depend on this service. description: A list of services that depend on this service.
returned: success and service exists returned: success and service exists
type: list type: list
sample: False sample: false
''' '''

22
lib/ansible/modules/windows/win_share.py
View file

@ -25,53 +25,55 @@ options:
name: name:
description: description:
- Share name. - Share name.
type: str
required: yes required: yes
path: path:
description: description:
- Share directory. - Share directory.
required: yes
type: path type: path
required: yes
state: state:
description: description:
- Specify whether to add C(present) or remove C(absent) the specified share. - Specify whether to add C(present) or remove C(absent) the specified share.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
description: description:
description: description:
- Share description. - Share description.
type: str
list: list:
description: description:
- Specify whether to allow or deny file listing, in case user has no permission on share. Also known as Access-Based Enumeration. - Specify whether to allow or deny file listing, in case user has no permission on share. Also known as Access-Based Enumeration.
type: bool type: bool
default: 'no' default: no
read: read:
description: description:
- Specify user list that should get read access on share, separated by comma. - Specify user list that should get read access on share, separated by comma.
type: str
change: change:
description: description:
- Specify user list that should get read and write access on share, separated by comma. - Specify user list that should get read and write access on share, separated by comma.
type: str
full: full:
description: description:
- Specify user list that should get full access on share, separated by comma. - Specify user list that should get full access on share, separated by comma.
type: str
deny: deny:
description: description:
- Specify user list that should get no access, regardless of implied access on share, separated by comma. - Specify user list that should get no access, regardless of implied access on share, separated by comma.
type: str
caching_mode: caching_mode:
description: description:
- Set the CachingMode for this share. - Set the CachingMode for this share.
choices: type: str
- BranchCache choices: [ BranchCache, Documents, Manual, None, Programs, Unknown ]
- Documents
- Manual
- None
- Programs
- Unknown
default: Manual default: Manual
version_added: "2.3" version_added: "2.3"
encrypt: encrypt:
description: Sets whether to encrypt the traffic to the share or not. description: Sets whether to encrypt the traffic to the share or not.
type: bool type: bool
default: 'no' default: no
version_added: "2.4" version_added: "2.4"
author: author:
- Hans-Joachim Kliemeck (@h0nIg) - Hans-Joachim Kliemeck (@h0nIg)

27
lib/ansible/modules/windows/win_shell.py
View file

@ -23,6 +23,7 @@ options:
description: description:
- The C(win_shell) module takes a free form command to run. - The C(win_shell) module takes a free form command to run.
- There is no parameter actually named 'free form'. See the examples! - There is no parameter actually named 'free form'. See the examples!
type: str
required: yes required: yes
creates: creates:
description: description:
@ -44,6 +45,7 @@ options:
stdin: stdin:
description: description:
- Set the stdin of the command directly to the specified value. - Set the stdin of the command directly to the specified value.
type: str
version_added: '2.5' version_added: '2.5'
notes: notes:
- If you want to run an executable securely and predictably, it may be - 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. - 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. 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. Consider creating a Windows service for managing background processes.
- For non-Windows targets, use the M(shell) module instead.
seealso: seealso:
- module: psexec - module: psexec
- module: raw - module: raw
@ -87,7 +88,7 @@ EXAMPLES = r'''
executable: cmd executable: cmd
register: homedir_out register: homedir_out
- name: run multi-lined shell commands - name: Run multi-lined shell commands
win_shell: | win_shell: |
$value = Test-Path -Path C:\temp $value = Test-Path -Path C:\temp
if ($value) { if ($value) {
@ -95,7 +96,7 @@ EXAMPLES = r'''
} }
New-Item -Path C:\temp -ItemType Directory 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()' win_shell: '$string = [Console]::In.ReadToEnd(); Write-Output $string.Trim()'
args: args:
stdin: Input message stdin: Input message
@ -103,47 +104,47 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
msg: msg:
description: changed description: Changed.
returned: always returned: always
type: bool type: bool
sample: True sample: true
start: start:
description: The command execution start time description: The command execution start time.
returned: always returned: always
type: str type: str
sample: '2016-02-25 09:18:26.429568' sample: '2016-02-25 09:18:26.429568'
end: end:
description: The command execution end time description: The command execution end time.
returned: always returned: always
type: str type: str
sample: '2016-02-25 09:18:26.755339' sample: '2016-02-25 09:18:26.755339'
delta: delta:
description: The command execution delta time description: The command execution delta time.
returned: always returned: always
type: str type: str
sample: '0:00:00.325771' sample: '0:00:00.325771'
stdout: stdout:
description: The command standard output description: The command standard output.
returned: always returned: always
type: str type: str
sample: 'Clustering node rabbit@slave1 with rabbit@master ...' sample: 'Clustering node rabbit@slave1 with rabbit@master ...'
stderr: stderr:
description: The command standard error description: The command standard error.
returned: always returned: always
type: str type: str
sample: 'ls: cannot access foo: No such file or directory' sample: 'ls: cannot access foo: No such file or directory'
cmd: cmd:
description: The command executed by the task description: The command executed by the task.
returned: always returned: always
type: str type: str
sample: 'rabbitmqctl join_cluster rabbit@master' sample: 'rabbitmqctl join_cluster rabbit@master'
rc: rc:
description: The command return code (0 means success) description: The command return code (0 means success).
returned: always returned: always
type: int type: int
sample: 0 sample: 0
stdout_lines: stdout_lines:
description: The command standard output split in lines description: The command standard output split in lines.
returned: always returned: always
type: list type: list
sample: [u'Clustering node rabbit@slave1 with rabbit@master ...'] sample: [u'Clustering node rabbit@slave1 with rabbit@master ...']

8
lib/ansible/modules/windows/win_shortcut.py
View file

@ -21,20 +21,23 @@ options:
- Executable or URL the shortcut points to. - Executable or URL the shortcut points to.
- The executable needs to be in your PATH, or has to be an absolute - The executable needs to be in your PATH, or has to be an absolute
path to the executable. path to the executable.
type: str
description: description:
description: description:
- Description for the shortcut. - Description for the shortcut.
- This is usually shown when hoovering the icon. - This is usually shown when hoovering the icon.
type: str
dest: dest:
description: description:
- Destination file for the shortcuting file. - Destination file for the shortcuting file.
- File name should have a C(.lnk) or C(.url) extension. - File name should have a C(.lnk) or C(.url) extension.
required: yes
type: path type: path
required: yes
arguments: arguments:
description: description:
- Additional arguments for the executable defined in C(src). - Additional arguments for the executable defined in C(src).
- Was originally just C(args) but renamed in Ansible 2.8. - Was originally just C(args) but renamed in Ansible 2.8.
type: str
aliases: [ args ] aliases: [ args ]
directory: directory:
description: description:
@ -52,14 +55,17 @@ options:
- This is a combination of one or more modifiers and a key. - This is a combination of one or more modifiers and a key.
- Possible modifiers are Alt, Ctrl, Shift, Ext. - Possible modifiers are Alt, Ctrl, Shift, Ext.
- Possible keys are [A-Z] and [0-9]. - Possible keys are [A-Z] and [0-9].
type: str
windowstyle: windowstyle:
description: description:
- Influences how the application is displayed when it is launched. - Influences how the application is displayed when it is launched.
type: str
choices: [ maximized, minimized, normal ] choices: [ maximized, minimized, normal ]
state: state:
description: description:
- When C(absent), removes the shortcut if it exists. - When C(absent), removes the shortcut if it exists.
- When C(present), creates or updates the shortcut. - When C(present), creates or updates the shortcut.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
run_as_admin: run_as_admin:

13
lib/ansible/modules/windows/win_snmp.py
View file

@ -10,7 +10,7 @@ ANSIBLE_METADATA = {
'supported_by': 'community' 'supported_by': 'community'
} }
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: win_snmp module: win_snmp
version_added: '2.8' version_added: '2.8'
@ -33,13 +33,14 @@ options:
empty list for either C(community_strings) or C(permitted_managers) empty list for either C(community_strings) or C(permitted_managers)
will result in the respective lists being removed entirely. will result in the respective lists being removed entirely.
- C(remove) will remove SNMP community strings and/or SNMP managers - C(remove) will remove SNMP community strings and/or SNMP managers
default: set type: str
choices: [ add, set, remove ] choices: [ add, set, remove ]
default: set
author: author:
- Michael Cassaniti (@mcassaniti) - Michael Cassaniti (@mcassaniti)
''' '''
EXAMPLES = ''' EXAMPLES = r'''
--- ---
- hosts: Windows - hosts: Windows
tasks: tasks:
@ -61,16 +62,16 @@ EXAMPLES = '''
action: set action: set
''' '''
RETURN = ''' RETURN = r'''
community_strings: community_strings:
description: The list of community strings for this machine description: The list of community strings for this machine.
type: list type: list
returned: always returned: always
sample: sample:
- public - public
- snmp-ro - snmp-ro
permitted_managers: permitted_managers:
description: The list of permitted managers for this machine description: The list of permitted managers for this machine.
type: list type: list
returned: always returned: always
sample: sample:

87
lib/ansible/modules/windows/win_stat.py
View file

@ -24,35 +24,34 @@ options:
description: description:
- The full path of the file/object to get the facts of; both forward and - The full path of the file/object to get the facts of; both forward and
back slashes are accepted. back slashes are accepted.
required: yes
type: path type: path
required: yes
get_md5: get_md5:
description: description:
- Whether to return the checksum sum of the file. Between Ansible 1.9 - 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 2.3 this is back to an MD5. Will return None if host is unable to
use specified algorithm. use specified algorithm.
- The default of this option changed from C(yes) to C(no) in Ansible 2.5 - 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. 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. md5 hash under the C(checksum) return value.
type: bool type: bool
default: 'no' default: no
get_checksum: get_checksum:
description: description:
- Whether to return a checksum of the file (default sha1) - Whether to return a checksum of the file (default sha1)
type: bool type: bool
default: 'yes' default: yes
version_added: "2.1" version_added: "2.1"
checksum_algorithm: checksum_algorithm:
description: description:
- Algorithm to determine checksum of file. Will throw an error if - Algorithm to determine checksum of file.
the host is unable to use specified algorithm. - Will throw an error if the host is unable to use specified algorithm.
type: str
default: sha1 default: sha1
choices: [ md5, sha1, sha256, sha384, sha512 ] choices: [ md5, sha1, sha256, sha384, sha512 ]
version_added: "2.3" version_added: "2.3"
notes:
- For non-Windows targets, use the M(stat) module instead.
seealso: seealso:
- module: stat - module: stat
- module: win_file - module: win_file
@ -106,137 +105,137 @@ changed:
description: Whether anything was changed description: Whether anything was changed
returned: always returned: always
type: bool type: bool
sample: True sample: true
stat: stat:
description: dictionary containing all the stat data description: dictionary containing all the stat data
returned: success returned: success
type: complex type: complex
contains: contains:
attributes: 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 returned: success, path exists
type: str type: str
sample: "Archive, Hidden" sample: "Archive, Hidden"
checksum: 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 returned: success, path exist, path is a file, get_checksum == True
checksum_algorithm specified is supported checksum_algorithm specified is supported
type: str type: str
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
creationtime: 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 returned: success, path exists
type: float type: float
sample: 1477984205.15 sample: 1477984205.15
exists: exists:
description: If the path exists or not description: If the path exists or not.
returned: success returned: success
type: bool type: bool
sample: True sample: true
extension: 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 returned: success, path exists, path is a file
type: str type: str
sample: ".ps1" sample: ".ps1"
filename: 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 returned: success, path exists, path is a file
type: str type: str
sammple: foo.ini sammple: foo.ini
hlnk_targets: 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 returned: success, path exists
type: list type: list
sample: sample:
- C:\temp\file.txt - C:\temp\file.txt
- C:\Windows\update.log - C:\Windows\update.log
isarchive: 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 returned: success, path exists
type: bool type: bool
sample: True sample: true
isdir: isdir:
description: If the path is a directory or not description: If the path is a directory or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
ishidden: ishidden:
description: If the path is hidden or not description: If the path is hidden or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
isjunction: 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 returned: success, path exists
type: bool type: bool
sample: True sample: true
islnk: 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 returned: success, path exists
type: bool type: bool
sample: True sample: true
isreadonly: isreadonly:
description: If the path is read only or not description: If the path is read only or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
isreg: isreg:
description: If the path is a regular file description: If the path is a regular file.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
isshared: isshared:
description: If the path is shared or not description: If the path is shared or not.
returned: success, path exists returned: success, path exists
type: bool type: bool
sample: True sample: true
lastaccesstime: 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 returned: success, path exists
type: float type: float
sample: 1477984205.15 sample: 1477984205.15
lastwritetime: 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 returned: success, path exists
type: float type: float
sample: 1477984205.15 sample: 1477984205.15
lnk_source: 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 returned: success, path exists and the path is a symbolic link or junction point
type: str type: str
sample: C:\temp\link sample: C:\temp\link
lnk_target: 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 returned: success, path exists and the path is a symbolic link or junction point
type: str type: str
sample: ..\link sample: ..\link
md5: 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 returned: success, path exist, path is a file, get_md5 == True
type: str type: str
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
nlink: nlink:
description: Number of links to the file (hard links) description: Number of links to the file (hard links).
returned: success, path exists returned: success, path exists
type: int type: int
sample: 1 sample: 1
owner: owner:
description: The owner of the file description: The owner of the file.
returned: success, path exists returned: success, path exists
type: str type: str
sample: BUILTIN\Administrators sample: BUILTIN\Administrators
path: path:
description: The full absolute path to the file description: The full absolute path to the file.
returned: success, path exists, file exists returned: success, path exists, file exists
type: str type: str
sample: C:\foo.ini sample: C:\foo.ini
sharename: 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 returned: success, path exists, file is a directory and isshared == True
type: str type: str
sample: file-share sample: file-share
size: 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 returned: success, path exists, file is not a link
type: int type: int
sample: 1024 sample: 1024

7
lib/ansible/modules/windows/win_tempfile.py
View file

@ -20,6 +20,7 @@ options:
state: state:
description: description:
- Whether to create file or directory. - Whether to create file or directory.
type: str
choices: [ directory, file ] choices: [ directory, file ]
default: file default: file
path: path:
@ -31,13 +32,13 @@ options:
prefix: prefix:
description: description:
- Prefix of file/directory name created by module. - Prefix of file/directory name created by module.
type: str
default: ansible. default: ansible.
suffix: suffix:
description: description:
- Suffix of file/directory name created by module. - Suffix of file/directory name created by module.
type: str
default: '' default: ''
notes:
- For non-Windows targets, please use the M(tempfile) module instead.
seealso: seealso:
- module: tempfile - module: tempfile
author: author:
@ -58,7 +59,7 @@ EXAMPLES = r"""
RETURN = r''' RETURN = r'''
path: path:
description: Path to created file or directory description: Path to created file or directory.
returned: success returned: success
type: str type: str
sample: C:\Users\Administrator\AppData\Local\Temp\ansible.bMlvdk sample: C:\Users\Administrator\AppData\Local\Temp\ansible.bMlvdk

15
lib/ansible/modules/windows/win_template.py
View file

@ -28,46 +28,54 @@ description:
template, and C(template_run_date) is the date that the template was rendered. Note that including 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' a string that uses a date in the template will result in the template being marked 'changed'
each time." each time."
- For other platforms you can use M(template) which uses '\n' as C(newline_sequence).
options: options:
src: src:
description: description:
- Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path. - Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path.
type: path
required: yes required: yes
dest: dest:
description: description:
- Location to render the template to on the remote machine. - Location to render the template to on the remote machine.
type: str
required: yes required: yes
newline_sequence: newline_sequence:
description: description:
- Specify the newline sequence to use for templating files. - Specify the newline sequence to use for templating files.
type: str
choices: [ '\n', '\r', '\r\n' ] choices: [ '\n', '\r', '\r\n' ]
default: '\r\n' default: '\r\n'
version_added: '2.4' version_added: '2.4'
block_start_string: block_start_string:
description: description:
- The string marking the beginning of a block. - The string marking the beginning of a block.
type: str
default: '{%' default: '{%'
version_added: '2.4' version_added: '2.4'
block_end_string: block_end_string:
description: description:
- The string marking the end of a block. - The string marking the end of a block.
type: str
default: '%}' default: '%}'
version_added: '2.4' version_added: '2.4'
variable_start_string: variable_start_string:
description: description:
- The string marking the beginning of a print statement. - The string marking the beginning of a print statement.
type: str
default: '{{' default: '{{'
version_added: '2.4' version_added: '2.4'
variable_end_string: variable_end_string:
description: description:
- The string marking the end of a print statement. - The string marking the end of a print statement.
type: str
default: '}}' default: '}}'
version_added: '2.4' version_added: '2.4'
trim_blocks: trim_blocks:
description: description:
- If this is set to C(yes) the first newline after a block is removed (block, not variable tag!). - If this is set to C(yes) the first newline after a block is removed (block, not variable tag!).
type: bool type: bool
default: 'no' default: no
version_added: '2.4' version_added: '2.4'
force: force:
description: description:
@ -76,11 +84,10 @@ options:
- If C(no), the file will only be transferred if the destination does - If C(no), the file will only be transferred if the destination does
not exist. not exist.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
notes: notes:
- For other platforms you can use M(template) which uses '\n' as C(newline_sequence). - Templates are loaded with C(trim_blocks=yes).
- Templates are loaded with C(trim_blocks=True).
- Beware fetching files from windows machines when creating templates - Beware fetching files from windows machines when creating templates
because certain tools, such as Powershell ISE, and regedit's export facility 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. add a Byte Order Mark as the first character of the file, which can cause tracebacks.

5
lib/ansible/modules/windows/win_timezone.py
View file

@ -20,6 +20,7 @@ options:
description: description:
- Timezone to set to. - Timezone to set to.
- 'Example: Central Standard Time' - 'Example: Central Standard Time'
type: str
required: yes required: yes
notes: notes:
- The module will check if the provided timezone is supported on the machine. - The module will check if the provided timezone is supported on the machine.
@ -50,12 +51,12 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
previous_timezone: 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 returned: success
type: str type: str
sample: Central Standard Time sample: Central Standard Time
timezone: timezone:
description: The current timezone (possibly changed) description: The current timezone (possibly changed).
returned: success returned: success
type: str type: str
sample: Central Standard Time sample: Central Standard Time

4
lib/ansible/modules/windows/win_toast.py
View file

@ -28,11 +28,13 @@ options:
group: group:
description: description:
- Which notification group to add the notification to. - Which notification group to add the notification to.
type: str
default: Powershell default: Powershell
msg: msg:
description: description:
- The message to appear inside the notification. - The message to appear inside the notification.
- May include \n to format the message to appear within the Action Center. - May include \n to format the message to appear within the Action Center.
type: str
default: Hello, World! default: Hello, World!
popup: popup:
description: description:
@ -42,10 +44,12 @@ options:
tag: tag:
description: description:
- The tag to add to the notification. - The tag to add to the notification.
type: str
default: Ansible default: Ansible
title: title:
description: description:
- The notification title, which appears in the pop up.. - The notification title, which appears in the pop up..
type: str
default: Notification HH:mm default: Notification HH:mm
notes: 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. - 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.

13
lib/ansible/modules/windows/win_unzip.py
View file

@ -27,25 +27,25 @@ options:
src: src:
description: description:
- File to be unzipped (provide absolute path). - File to be unzipped (provide absolute path).
required: yes
type: path type: path
required: yes
dest: dest:
description: description:
- Destination of zip file (provide absolute path of directory). If it does not exist, the directory will be created. - Destination of zip file (provide absolute path of directory). If it does not exist, the directory will be created.
required: yes
type: path type: path
required: yes
delete_archive: delete_archive:
description: description:
- Remove the zip file, after unzipping. - Remove the zip file, after unzipping.
type: bool type: bool
default: 'no' default: no
aliases: [ rm ] aliases: [ rm ]
recurse: recurse:
description: description:
- Recursively expand zipped files within the src file. - Recursively expand zipped files within the src file.
- Setting to a value of C(yes) requires the PSCX module to be installed. - Setting to a value of C(yes) requires the PSCX module to be installed.
type: bool type: bool
default: 'no' default: no
creates: creates:
description: description:
- If this file or directory exists the specified src will not be extracted. - 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) - 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 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. 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: seealso:
- module: unarchive - module: unarchive
author: author:
@ -64,7 +63,7 @@ author:
EXAMPLES = r''' EXAMPLES = r'''
# This unzips a library that was downloaded with win_get_url, and removes the file after extraction # 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 - name: Unzip a bz2 (BZip) file
win_unzip: win_unzip:
@ -105,7 +104,7 @@ removed:
description: Whether the module did remove any files during task run description: Whether the module did remove any files during task run
returned: always returned: always
type: bool type: bool
sample: True sample: true
src: src:
description: The provided source path description: The provided source path
returned: always returned: always

37
lib/ansible/modules/windows/win_updates.py
View file

@ -47,21 +47,22 @@ options:
and continue to install updates after the reboot. and continue to install updates after the reboot.
- This can be used instead of using a M(win_reboot) task after this one - 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. 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 type: bool
default: 'no' default: no
version_added: '2.5' version_added: '2.5'
reboot_timeout: reboot_timeout:
description: description:
- The time in seconds to wait until the host is back online from a - The time in seconds to wait until the host is back online from a
reboot. 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 default: 1200
version_added: '2.5' version_added: '2.5'
state: state:
description: description:
- Controls whether found updates are returned as a list or actually installed. - 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 - This module also supports Ansible check mode, which has the same effect as setting state=searched
type: str
choices: [ installed, searched ] choices: [ installed, searched ]
default: installed default: installed
log_path: log_path:
@ -91,7 +92,7 @@ options:
- Can also be set to C(yes) on newer hosts where become does not work - Can also be set to C(yes) on newer hosts where become does not work
due to further privilege restrictions from the OS defaults. due to further privilege restrictions from the OS defaults.
type: bool type: bool
default: 'no' default: no
version_added: '2.6' version_added: '2.6'
notes: notes:
- C(win_updates) must be run by a user with membership in the local Administrators group. - C(win_updates) must be run by a user with membership in the local Administrators group.
@ -172,44 +173,44 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
reboot_required: 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 returned: success
type: bool type: bool
sample: True sample: true
updates: updates:
description: List of updates that were found/installed description: List of updates that were found/installed.
returned: success returned: success
type: complex type: complex
sample: sample:
contains: contains:
title: title:
description: Display name description: Display name.
returned: always returned: always
type: str type: str
sample: "Security Update for Windows Server 2012 R2 (KB3004365)" sample: "Security Update for Windows Server 2012 R2 (KB3004365)"
kb: 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 returned: always
type: list of strings type: list of strings
sample: [ '3004365' ] sample: [ '3004365' ]
id: id:
description: Internal Windows Update GUID description: Internal Windows Update GUID.
returned: always returned: always
type: str (guid) type: str (guid)
sample: "fb95c1c8-de23-4089-ae29-fd3351d55421" sample: "fb95c1c8-de23-4089-ae29-fd3351d55421"
installed: installed:
description: Was the update successfully installed description: Was the update successfully installed.
returned: always returned: always
type: bool type: bool
sample: True sample: true
categories: categories:
description: A list of category strings for this update description: A list of category strings for this update.
returned: always returned: always
type: list of strings type: list of strings
sample: [ 'Critical Updates', 'Windows Server 2012 R2' ] sample: [ 'Critical Updates', 'Windows Server 2012 R2' ]
failure_hresult_code: failure_hresult_code:
description: The HRESULT code from a failed update description: The HRESULT code from a failed update.
returned: on install failure returned: on install failure
type: bool type: bool
sample: 2147942402 sample: 2147942402
@ -223,23 +224,23 @@ filtered_updates:
sample: see the updates return value sample: see the updates return value
contains: contains:
filtered_reason: filtered_reason:
description: The reason why this update was filtered description: The reason why this update was filtered.
returned: always returned: always
type: str type: str
sample: 'skip_hidden' sample: 'skip_hidden'
found_update_count: 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 returned: success
type: int type: int
sample: 3 sample: 3
installed_update_count: installed_update_count:
description: The number of updates successfully installed description: The number of updates successfully installed.
returned: success returned: success
type: int type: int
sample: 2 sample: 2
failed_update_count: failed_update_count:
description: The number of updates that failed to install description: The number of updates that failed to install.
returned: always returned: always
type: int type: int
sample: 0 sample: 0

23
lib/ansible/modules/windows/win_uri.py
View file

@ -22,25 +22,31 @@ options:
url: url:
description: description:
- Supports FTP, HTTP or HTTPS URLs in the form of (ftp|http|https)://host.domain:port/path. - Supports FTP, HTTP or HTTPS URLs in the form of (ftp|http|https)://host.domain:port/path.
type: str
required: yes required: yes
method: method:
description: description:
- The HTTP Method of the request or response. - The HTTP Method of the request or response.
type: str
choices: [ CONNECT, DELETE, GET, HEAD, MERGE, OPTIONS, PATCH, POST, PUT, REFRESH, TRACE ] choices: [ CONNECT, DELETE, GET, HEAD, MERGE, OPTIONS, PATCH, POST, PUT, REFRESH, TRACE ]
default: GET default: GET
content_type: content_type:
description: description:
- Sets the "Content-Type" header. - Sets the "Content-Type" header.
type: str
body: body:
description: description:
- The body of the HTTP request/response to the web service. - The body of the HTTP request/response to the web service.
type: raw
user: user:
description: description:
- Username to use for authentication. - Username to use for authentication.
type: str
version_added: '2.4' version_added: '2.4'
password: password:
description: description:
- Password to use for authentication. - Password to use for authentication.
type: str
version_added: '2.4' version_added: '2.4'
force_basic_auth: force_basic_auth:
description: description:
@ -50,7 +56,7 @@ options:
- This option forces the sending of the Basic authentication header upon - This option forces the sending of the Basic authentication header upon
the initial request. the initial request.
type: bool type: bool
default: 'no' default: no
version_added: '2.5' version_added: '2.5'
dest: dest:
description: description:
@ -61,6 +67,7 @@ options:
description: description:
- Extra headers to set on the request, see the examples for more details on - Extra headers to set on the request, see the examples for more details on
how to set this. how to set this.
type: dict
creates: creates:
description: description:
- A filename, when it already exists, this step will be skipped. - 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 "application/json", then the JSON is additionally loaded into a key
called C(json) in the dictionary results. called C(json) in the dictionary results.
type: bool type: bool
default: 'no' default: no
version_added: '2.4' version_added: '2.4'
status_code: status_code:
description: description:
@ -105,6 +112,7 @@ options:
- C(none) will not follow any redirects. - C(none) will not follow any redirects.
- C(safe) will follow only "safe" redirects, where "safe" means that the client is only - 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. doing a C(GET) or C(HEAD) on the URI to which it is being redirected.
type: str
choices: [ all, none, safe ] choices: [ all, none, safe ]
default: safe default: safe
version_added: '2.4' version_added: '2.4'
@ -124,7 +132,7 @@ options:
set to C(no) used on personally controlled sites using self-signed set to C(no) used on personally controlled sites using self-signed
certificates. certificates.
type: bool type: bool
default: 'yes' default: yes
version_added: '2.4' version_added: '2.4'
client_cert: client_cert:
description: description:
@ -139,9 +147,8 @@ options:
description: description:
- The password for the client certificate (.pfx) file that is used for a - The password for the client certificate (.pfx) file that is used for a
secure web request. secure web request.
type: str
version_added: '2.5' version_added: '2.5'
notes:
- For non-Windows targets, use the M(uri) module instead.
seealso: seealso:
- module: uri - module: uri
- module: win_get_url - module: win_get_url
@ -178,12 +185,12 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
elapsed: 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 returned: always
type: float type: float
sample: 23.2 sample: 23.2
url: url:
description: The Target URL description: The Target URL.
returned: always returned: always
type: str type: str
sample: https://www.ansible.com sample: https://www.ansible.com
@ -208,7 +215,7 @@ content_length:
type: int type: int
sample: 54447 sample: 54447
json: 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 returned: success and Content-Type is "application/json" or "application/javascript" and return_content is True
type: dict type: dict
sample: {"this-is-dependent": "on the actual return content"} sample: {"this-is-dependent": "on the actual return content"}

15
lib/ansible/modules/windows/win_user.py
View file

@ -23,22 +23,27 @@ options:
name: name:
description: description:
- Name of the user to create, remove or modify. - Name of the user to create, remove or modify.
type: str
required: yes required: yes
fullname: fullname:
description: description:
- Full name of the user. - Full name of the user.
type: str
version_added: "1.9" version_added: "1.9"
description: description:
description: description:
- Description of the user. - Description of the user.
type: str
version_added: "1.9" version_added: "1.9"
password: password:
description: description:
- Optionally set the user's password to this (plain text) value. - Optionally set the user's password to this (plain text) value.
type: str
update_password: update_password:
description: description:
- C(always) will update passwords if they differ. C(on_create) will - C(always) will update passwords if they differ. C(on_create) will
only set the password for newly created users. only set the password for newly created users.
type: str
choices: [ always, on_create ] choices: [ always, on_create ]
default: always default: always
version_added: "1.9" version_added: "1.9"
@ -74,9 +79,9 @@ options:
groups: groups:
description: description:
- Adds or removes the user from this comma-separated lis of groups, - 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 depending on the value of I(groups_action).
C(replace) and I(groups) is set to the empty string ('groups='), the - When I(groups_action) is C(replace) and I(groups) is set to the empty
user is removed from all groups. string ('groups='), the user is removed from all groups.
version_added: "1.9" version_added: "1.9"
groups_action: groups_action:
description: description:
@ -85,6 +90,7 @@ options:
- If C(replace), the user is added as a member of each group in - If C(replace), the user is added as a member of each group in
I(groups) and removed from any other groups. I(groups) and removed from any other groups.
- If C(remove), the user is removed from each group in I(groups). - If C(remove), the user is removed from each group in I(groups).
type: str
choices: [ add, replace, remove ] choices: [ add, replace, remove ]
default: replace default: replace
version_added: "1.9" version_added: "1.9"
@ -94,10 +100,9 @@ options:
- When C(present), creates or updates the user account. - When C(present), creates or updates the user account.
- When C(query) (new in 1.9), retrieves the user account details - When C(query) (new in 1.9), retrieves the user account details
without making any changes. without making any changes.
type: str
choices: [ absent, present, query ] choices: [ absent, present, query ]
default: present default: present
notes:
- For non-Windows targets, use the M(user) module instead.
seealso: seealso:
- module: user - module: user
- module: win_domain_membership - module: win_domain_membership

10
lib/ansible/modules/windows/win_user_right.py
View file

@ -25,6 +25,7 @@ options:
- The name of the User Right as shown by the C(Constant Name) value from - 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). U(https://technet.microsoft.com/en-us/library/dd349804.aspx).
- The module will return an error if the right is invalid. - The module will return an error if the right is invalid.
type: str
required: yes required: yes
users: users:
description: description:
@ -34,13 +35,14 @@ options:
- For local users/groups it can be in the form user-group, .\user-group, - 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. SERVERNAME\user-group where SERVERNAME is the name of the remote server.
- You can also add special local accounts like SYSTEM and others. - You can also add special local accounts like SYSTEM and others.
required: yes
type: list type: list
required: yes
action: action:
description: description:
- C(add) will add the users/groups to the existing right. - C(add) will add the users/groups to the existing right.
- C(remove) will remove the users/groups from 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. - C(set) will replace the users/groups of the existing right.
type: str
default: set default: set
choices: [ add, remove, set ] choices: [ add, remove, set ]
notes: notes:
@ -56,7 +58,7 @@ author:
EXAMPLES = r''' EXAMPLES = r'''
--- ---
- name: replace the entries of Deny log on locally - name: Replace the entries of Deny log on locally
win_user_right: win_user_right:
name: SeDenyInteractiveLogonRight name: SeDenyInteractiveLogonRight
users: users:
@ -64,7 +66,7 @@ EXAMPLES = r'''
- Users - Users
action: set action: set
- name: add account to Log on as a service - name: Add account to Log on as a service
win_user_right: win_user_right:
name: SeServiceLogonRight name: SeServiceLogonRight
users: users:
@ -72,7 +74,7 @@ EXAMPLES = r'''
- '{{ansible_hostname}}\local-user' - '{{ansible_hostname}}\local-user'
action: add action: add
- name: remove accounts who can create Symbolic links - name: Remove accounts who can create Symbolic links
win_user_right: win_user_right:
name: SeCreateSymbolicLinkPrivilege name: SeCreateSymbolicLinkPrivilege
users: users:

19
lib/ansible/modules/windows/win_wait_for.py
View file

@ -48,6 +48,7 @@ options:
- A resolvable hostname or IP address to wait for. - A resolvable hostname or IP address to wait for.
- If C(state=drained) then it will only check for connections on the IP - 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. specified, you can use '0.0.0.0' to use all host IPs.
type: str
default: '127.0.0.1' default: '127.0.0.1'
path: path:
description: description:
@ -67,6 +68,7 @@ options:
matches. matches.
- If C(state) is absent then it will wait until the regex does not match. - If C(state) is absent then it will wait until the regex does not match.
- Defaults to a multiline regex. - Defaults to a multiline regex.
type: str
sleep: sleep:
description: description:
- Number of seconds to sleep between checks. - 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 - 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 ensure that the file or string is present, C(absent) will check that the
file or search string is absent or removed. file or search string is absent or removed.
default: started type: str
choices: [ absent, drained, present, started, stopped ] choices: [ absent, drained, present, started, stopped ]
default: started
timeout: timeout:
description: description:
- The maximum number of seconds to wait for. - The maximum number of seconds to wait for.
@ -95,40 +98,40 @@ author:
''' '''
EXAMPLES = r''' 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: win_wait_for:
port: 8000 port: 8000
delay: 10 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: win_wait_for:
host: 0.0.0.0 host: 0.0.0.0
port: 8000 port: 8000
state: drained state: drained
timeout: 150 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: win_wait_for:
host: 0.0.0.0 host: 0.0.0.0
port: 8000 port: 8000
state: drained state: drained
exclude_hosts: ['10.2.1.2', '10.2.1.3'] 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: win_wait_for:
path: C:\temp\log.txt 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: win_wait_for:
path: C:\temp\log.txt path: C:\temp\log.txt
search_regex: process complete search_regex: process complete
- name: wait until file if removed - name: Wait until file is removed
win_wait_for: win_wait_for:
path: C:\temp\log.txt path: C:\temp\log.txt
state: absent 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: win_wait_for:
port: 1234 port: 1234
state: absent state: absent

8
lib/ansible/modules/windows/win_wait_for_process.py
View file

@ -112,22 +112,22 @@ elapsed:
type: float type: float
sample: 3.14159265 sample: 3.14159265
matched_processes: matched_processes:
description: List of matched processes (either stopped or started) description: List of matched processes (either stopped or started).
returned: always returned: always
type: complex type: complex
contains: contains:
name: name:
description: The name of the matched process description: The name of the matched process.
returned: always returned: always
type: str type: str
sample: svchost sample: svchost
owner: owner:
description: The owner of the matched process description: The owner of the matched process.
returned: when supported by PowerShell returned: when supported by PowerShell
type: str type: str
sample: NT AUTHORITY\SYSTEM sample: NT AUTHORITY\SYSTEM
pid: pid:
description: The PID of the matched process description: The PID of the matched process.
returned: always returned: always
type: int type: int
sample: 7908 sample: 7908

3
lib/ansible/modules/windows/win_wakeonlan.py
View file

@ -15,14 +15,17 @@ version_added: '2.4'
short_description: Send a magic Wake-on-LAN (WoL) broadcast packet short_description: Send a magic Wake-on-LAN (WoL) broadcast packet
description: description:
- The C(win_wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets. - The C(win_wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets.
- For non-Windows targets, use the M(wakeonlan) module instead.
options: options:
mac: mac:
description: description:
- MAC address to send Wake-on-LAN broadcast packet for. - MAC address to send Wake-on-LAN broadcast packet for.
type: str
required: yes required: yes
broadcast: broadcast:
description: description:
- Network broadcast address to use for broadcasting magic Wake-on-LAN packet. - Network broadcast address to use for broadcasting magic Wake-on-LAN packet.
type: str
default: 255.255.255.255 default: 255.255.255.255
port: port:
description: description:

3
lib/ansible/modules/windows/win_webpicmd.py
View file

@ -27,6 +27,7 @@ options:
name: name:
description: description:
- Name of the package to be installed. - Name of the package to be installed.
type: str
required: yes required: yes
seealso: seealso:
- module: win_package - module: win_package
@ -35,7 +36,7 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
# Install URLRewrite2. - name: Install URLRewrite2.
win_webpicmd: win_webpicmd:
name: URLRewrite2 name: URLRewrite2
''' '''

2
lib/ansible/modules/windows/win_whoami.py
View file

@ -33,7 +33,7 @@ author:
''' '''
EXAMPLES = r''' EXAMPLES = r'''
- name: get whoami information - name: Get whoami information
win_whoami: win_whoami:
''' '''

31
lib/ansible/modules/windows/win_xml.py
View file

@ -18,52 +18,55 @@ version_added: "2.7"
short_description: Add XML fragment to an XML parent short_description: Add XML fragment to an XML parent
description: description:
- Adds XML fragments formatted as strings to existing XML on remote servers. - Adds XML fragments formatted as strings to existing XML on remote servers.
- For non-Windows targets, use the M(xml) module instead.
options: options:
path: path:
description: description:
- The path of remote servers XML. - The path of remote servers XML.
type: str
required: true required: true
aliases: [ dest, file ] aliases: [ dest, file ]
fragment: fragment:
description: description:
- The string representation of the XML fragment to be added. - The string representation of the XML fragment to be added.
type: str
required: true required: true
aliases: [ xmlstring ] aliases: [ xmlstring ]
xpath: xpath:
description: description:
- The node of the remote server XML where the fragment will go. - The node of the remote server XML where the fragment will go.
type: str
required: true required: true
backup: backup:
description: description:
- Whether to backup the remote server's XML before applying the change. - Whether to backup the remote server's XML before applying the change.
type: bool type: bool
default: 'no' default: no
type: type:
description: description:
- The type of XML you are working with. - The type of XML you are working with.
type: str
required: yes required: yes
default: element default: element
choices: choices: [ attribute, element, text ]
- element
- attribute
- text
attribute: attribute:
description: 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: author:
- Richard Levenberg (@richardcs) - Richard Levenberg (@richardcs)
''' '''
EXAMPLES = r''' EXAMPLES = r'''
# Apply our filter to Tomcat web.xml - name: Apply our filter to Tomcat web.xml
- win_xml: win_xml:
path: C:\apache-tomcat\webapps\myapp\WEB-INF\web.xml path: C:\apache-tomcat\webapps\myapp\WEB-INF\web.xml
fragment: '<filter><filter-name>MyFilter</filter-name><filter-class>com.example.MyFilter</filter-class></filter>' fragment: '<filter><filter-name>MyFilter</filter-name><filter-class>com.example.MyFilter</filter-class></filter>'
xpath: '/*' xpath: '/*'
# Apply sslEnabledProtocols to Tomcat's server.xml - name: Apply sslEnabledProtocols to Tomcat's server.xml
- win_xml: win_xml:
path: C:\Tomcat\conf\server.xml path: C:\Tomcat\conf\server.xml
xpath: '//Server/Service[@name="Catalina"]/Connector[@port="9443"]' xpath: '//Server/Service[@name="Catalina"]/Connector[@port="9443"]'
attribute: 'sslEnabledProtocols' attribute: 'sslEnabledProtocols'
@ -73,17 +76,17 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
msg: msg:
description: what was done description: What was done.
returned: always returned: always
type: str type: str
sample: "xml added" sample: "xml added"
err: err:
description: xml comparison exceptions description: XML comparison exceptions.
returned: always, for type element and -vvv or more returned: always, for type element and -vvv or more
type: list type: list
sample: attribute mismatch for actual=string sample: attribute mismatch for actual=string
backup: backup:
description: name of the backup file, if created description: Name of the backup file, if created.
returned: changed returned: changed
type: str type: str
sample: C:\config.xml.19700101-000000 sample: C:\config.xml.19700101-000000