ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-28 07:31:23 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -17,12 +17,12 @@ description:
- With the module you can retrieve and output detailed information about the attached disks of the target and
its volumes and partitions if existent.
requirements:
- Windows 8.1 / Windows 2012 (NT 6.2)
- Windows 8.1 / Windows 2012 (NT 6.2)
notes:
- In order to understand all the returned properties and values please visit the following site and open the respective MSFT class
U(https://msdn.microsoft.com/en-us/library/windows/desktop/hh830612.aspx)
author:
- Marc Tschapek (@marqelme)
- Marc Tschapek (@marqelme)
'''
EXAMPLES = r'''
@ -41,7 +41,7 @@ EXAMPLES = r'''
disk: '{{ ansible_facts.disks|selectattr("system_disk")|first }}'
# Show disk size in Gibibytes
disksize_gib_human: '{{ disk.size|filesizeformat(True) }}' # returns "223.6 GiB" (human readable)
disksize_gib_human: '{{ disk.size|filesizeformat(true) }}' # returns "223.6 GiB" (human readable)
disksize_gib: '{{ (disk.size/1024|pow(3))|round|int }} GiB' # returns "224 GiB" (value in GiB)
# Show disk size in Gigabytes
@ -108,22 +108,22 @@ ansible_facts:
description: Read only status of the particular disk.
returned: always
type: bool
sample: True
sample: true
bootable:
description: Information whether the particular disk is a bootable disk.
returned: always
type: bool
sample: False
sample: false
system_disk:
description: Information whether the particular disk is a system disk.
returned: always
type: bool
sample: True
sample: true
clustered:
description: Information whether the particular disk is clustered (part of a failover cluster).
returned: always
type: bool
sample: False
sample: false
manufacturer:
description: Manufacturer of the particular disk.
returned: always
@ -194,7 +194,7 @@ ansible_facts:
description: Information whether the particular partition has a default drive letter or not.
returned: if partition_style property of the particular disk has value "GPT"
type: bool
sample: True
sample: true
mbr_type:
description: mbr type of the particular partition.
returned: if partition_style property of the particular disk has value "MBR"
@ -204,7 +204,7 @@ ansible_facts:
description: Information whether the particular partition is an active partition or not.
returned: if partition_style property of the particular disk has value "MBR"
type: bool
sample: True
sample: true
drive_letter:
description: Drive letter of the particular partition.
returned: if existent
@ -224,12 +224,12 @@ ansible_facts:
description: Information whether the particular partition is hidden or not.
returned: always
type: bool
sample: True
sample: true
shadow_copy:
description: Information whether the particular partition is a shadow copy of another partition.
returned: always
type: bool
sample: False
sample: false
guid:
description: GUID of the particular partition.
returned: if existent
@ -383,7 +383,7 @@ ansible_facts:
description: Information whether the particular physical disk can be added to a storage pool.
returned: always
type: bool
sample: False
sample: false
cannot_pool_reason:
description: Information why the particular physical disk can not be added to a storage pool.
returned: if can_pool property has value false
@ -393,12 +393,12 @@ ansible_facts:
description: Information whether indication is enabled for the particular physical disk.
returned: always
type: bool
sample: True
sample: true
partial:
description: Information whether the particular physical disk is partial.
returned: always
type: bool
sample: False
sample: false
serial_number:
description: Serial number of the particular physical disk.
returned: always
@ -507,27 +507,27 @@ ansible_facts:
description: Information whether deduplication is enabled for the particular virtual disk.
returned: always
type: bool
sample: True
sample: true
enclosure_aware:
description: Information whether the particular virtual disk is enclosure aware.
returned: always
type: bool
sample: False
sample: false
manual_attach:
description: Information whether the particular virtual disk is manual attached.
returned: always
type: bool
sample: True
sample: true
snapshot:
description: Information whether the particular virtual disk is a snapshot.
returned: always
type: bool
sample: False
sample: false
tiered:
description: Information whether the particular virtual disk is tiered.
returned: always
type: bool
sample: True
sample: true
physical_sector_size:
description: Physical sector size in bytes of the particular virtual disk.
returned: always
@ -567,7 +567,7 @@ ansible_facts:
description: Information whether the particular virtual disk requests no single point of failure.
returned: always
type: bool
sample: True
sample: true
resiliency_setting_name:
description: Type of the physical disk redundancy of the particular virtual disk.
returned: always

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

@ -8,41 +8,31 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
module: win_disk_image
short_description: Manage ISO/VHD/VHDX mounts on Windows hosts
version_added: '2.3'
description:
- Manages mount behavior for a specified ISO, VHD, or VHDX image on a Windows host. When C(state) is C(present),
the image will be mounted under a system-assigned drive letter, which will be returned in the C(mount_path) value
of the module result. Requires Windows 8+ or Windows Server 2012+.
of the module result.
- Requires Windows 8+ or Windows Server 2012+.
options:
image_path:
description:
- Path to an ISO, VHD, or VHDX image on the target Windows host (the file cannot reside on a network share)
type: str
required: yes
state:
description:
- Whether the image should be present as a drive-letter mount or not.
type: str
choices: [ absent, present ]
default: present
author:
- Matt Davis (@nitzmahone)
'''
RETURN = r'''
mount_path:
description: filesystem path where the target image is mounted, this has been deprecated in favour of C(mount_paths)
returned: when C(state) is C(present)
type: str
sample: F:\
mount_paths:
description: a list of filesystem paths mounted from the target image
returned: when C(state) is C(present)
type: list
sample: [ 'E:\', 'F:\' ]
'''
EXAMPLES = r'''
# Run installer from mounted ISO, then unmount
- name: Ensure an ISO is mounted
@ -51,14 +41,27 @@ EXAMPLES = r'''
state: present
register: disk_image_out
- name: Run installer from mounted iso
- name: Run installer from mounted ISO
win_package:
path: '{{ disk_image_out.mount_paths[0] }}setup\setup.exe'
product_id: 35a4e767-0161-46b0-979f-e61f282fee21
state: present
- name: Unmount iso
- name: Unmount ISO
win_disk_image:
image_path: C:\install.iso
state: absent
'''
RETURN = r'''
mount_path:
description: Filesystem path where the target image is mounted, this has been deprecated in favour of C(mount_paths).
returned: when C(state) is C(present)
type: str
sample: F:\
mount_paths:
description: A list of filesystem paths mounted from the target image.
returned: when C(state) is C(present)
type: list
sample: [ 'E:\', 'F:\' ]
'''

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

@ -19,12 +19,14 @@ options:
adapter_names:
description:
- Adapter name or list of adapter names for which to manage DNS settings ('*' is supported as a wildcard value).
The adapter name used is the connection caption in the Network Control Panel or via C(Get-NetAdapter), eg C(Local Area Connection).
- The adapter name used is the connection caption in the Network Control Panel or via C(Get-NetAdapter), eg C(Local Area Connection).
type: str
required: yes
ipv4_addresses:
description:
- Single or ordered list of DNS server IPv4 addresses to configure for lookup. An empty list will configure the adapter to use the
DHCP-assigned values on connections where DHCP is enabled, or disable DNS lookup on statically-configured connections.
type: str
required: yes
notes:
- When setting an empty list of DNS server addresses on an adapter with DHCP enabled, a change will always be registered, since it is not possible to
@ -53,6 +55,6 @@ EXAMPLES = r'''
ipv4_addresses: []
'''
RETURN = '''
RETURN = r'''
'''

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

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

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

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

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

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

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

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

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

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

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 module allows you to run this task on your own schedule, so you incur the CPU hit at some more convenient and controlled time.
- U(http://blogs.msdn.com/b/dotnet/archive/2013/08/06/wondering-why-mscorsvw-exe-has-high-cpu-usage-you-can-speed-it-up.aspx)
options: {}
notes:
- There are in fact two scheduled tasks for ngen but they have no triggers so aren't a problem.
- There's no way to test if they've been completed.
- The stdout is quite likely to be several megabytes.
author:
- Peter Mounce (@petemounce)
options: {}
'''
EXAMPLES = r'''
- name: run ngen tasks
- name: Run ngen tasks
win_dotnet_ngen:
'''

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

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

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

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

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

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

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

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

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
exist, while an existing file or directory will receive updated file access and
modification times (similar to the way C(touch) works from the command line).
type: str
choices: [ absent, directory, file, touch ]
notes:
- For non-Windows targets, use the M(file) module instead.
seealso:
- module: assemble
- module: copy

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -14,7 +14,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
DOCUMENTATION = r'''
module: win_hostname
version_added: "2.6"
short_description: Manages local Windows computer name.
short_description: Manages local Windows computer name
description:
- Manages local Windows computer name.
- A reboot is required for the computer name to take effect.
@ -22,6 +22,7 @@ options:
name:
description:
- The hostname to set for the computer.
type: str
required: true
seealso:
- module: win_dns_client
@ -42,12 +43,12 @@ EXAMPLES = r'''
RETURN = r'''
old_name:
description: The original hostname that was set before it was changed
description: The original hostname that was set before it was changed.
returned: always
type: str
sample: old_hostname
reboot_required:
description: Whether a reboot is required to complete the hostname change
description: Whether a reboot is required to complete the hostname change.
returned: always
type: bool
sample: true

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -20,9 +20,9 @@ options:
description:
- The path of the file to modify.
- Note that the Windows path delimiter C(\) must be escaped as C(\\) when the line is double quoted.
- Before 2.3 this option was only usable as I(dest), I(destfile) and I(name).
required: yes
- Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name).
type: path
required: yes
aliases: [ dest, destfile, name ]
regexp:
description:
@ -32,6 +32,7 @@ options:
state:
description:
- Whether the line should be there or not.
type: str
choices: [ absent, present ]
default: present
line:
@ -40,6 +41,7 @@ options:
expanded with the C(regexp) capture groups if the regexp matches.
- Be aware that the line is processed first on the controller and thus is dependent on yaml quoting rules. Any double quoted line
will have control characters, such as '\r\n', expanded. To print such characters literally, use single or no quotes.
type: str
backrefs:
description:
- Used with C(state=present). If set, line can contain backreferences (both positional and named) that will get populated if the C(regexp)
@ -47,12 +49,13 @@ options:
doesn't match anywhere in the file, the file will be left unchanged.
- If the C(regexp) does match, the last matching line will be replaced by the expanded line parameter.
type: bool
default: 'no'
default: no
insertafter:
description:
- Used with C(state=present). If specified, the line will be inserted after the last match of specified regular expression. A special value is
available; C(EOF) for inserting the line at the end of the file.
- If specified regular expression has no matches, EOF will be used instead. May not be used with C(backrefs).
type: str
choices: [ EOF, '*regex*' ]
default: EOF
insertbefore:
@ -60,21 +63,23 @@ options:
- Used with C(state=present). If specified, the line will be inserted before the last match of specified regular expression. A value is available;
C(BOF) for inserting the line at the beginning of the file.
- If specified regular expression has no matches, the line will be inserted at the end of the file. May not be used with C(backrefs).
type: str
choices: [ BOF, '*regex*' ]
create:
description:
- Used with C(state=present). If specified, the file will be created if it does not already exist. By default it will fail if the file is missing.
type: bool
default: 'no'
default: no
backup:
description:
- Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
type: bool
default: 'no'
default: no
validate:
description:
- Validation to run before copying into place. Use %s in the command to indicate the current file to validate.
- The command is passed securely so shell features like expansion and pipes won't work.
type: str
encoding:
description:
- Specifies the encoding of the source text file to operate on (and thus what the output encoding will be). The default of C(auto) will cause
@ -83,11 +88,13 @@ options:
see U(https://msdn.microsoft.com/en-us/library/system.text.encoding%28v=vs.110%29.aspx).
- This is mostly useful with C(create=yes) if you want to create a new file with a specific encoding. If C(create=yes) is specified without a
specific encoding, the default encoding (UTF-8, no BOM) will be used.
type: str
default: auto
newline:
description:
- Specifies the line separator style to use for the modified file. This defaults to the windows line separator (C(\r\n)). Note that the indicated
line separator will be used for file output regardless of the original line separator that appears in the input file.
type: str
choices: [ unix, windows ]
default: windows
notes:
@ -100,8 +107,8 @@ author:
'''
EXAMPLES = r'''
# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
- name: insert path without converting \r\n
# Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
- name: Insert path without converting \r\n
win_lineinfile:
path: c:\file.txt
line: c:\return\new
@ -133,21 +140,21 @@ EXAMPLES = r'''
insertbefore: '^www.*80/tcp'
line: '# port for http by default'
# Create file if it doesn't exist with a specific encoding
- win_lineinfile:
- name: Create file if it doesn't exist with a specific encoding
win_lineinfile:
path: C:\Temp\utf16.txt
create: yes
encoding: utf-16
line: This is a utf-16 encoded file
# Add a line to a file and ensure the resulting file uses unix line separators
- win_lineinfile:
- name: Add a line to a file and ensure the resulting file uses unix line separators
win_lineinfile:
path: C:\Temp\testfile.txt
line: Line added to file
newline: unix
# Update a line using backrefs
- win_lineinfile:
- name: Update a line using backrefs
win_lineinfile:
path: C:\Temp\example.conf
backrefs: yes
regexp: '(^name=)'

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

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

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

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

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

@ -24,12 +24,14 @@ options:
name:
description:
- Name of the service to operate on.
type: str
required: true
state:
description:
- State of the service on the system.
- Note that NSSM actions like "pause", "continue", "rotate" do not fit the declarative style of ansible, so these should be implemented via the
ansible command module.
type: str
choices: [ absent, present, started, stopped, restarted ]
default: started
application:
@ -44,33 +46,41 @@ options:
stdout_file:
description:
- Path to receive output.
type: str
stderr_file:
description:
- Path to receive error output.
type: str
app_parameters:
description:
- A string representing a dictionary of parameters to be passed to the application when it starts.
- Use either this or C(app_parameters_free_form), not both.
type: str
app_parameters_free_form:
version_added: "2.3.0"
description:
- Single string of parameters to be passed to the service.
- Use either this or C(app_parameters), not both.
type: str
version_added: "2.3"
dependencies:
description:
- Service dependencies that has to be started to trigger startup, separated by comma.
type: list
user:
description:
- User to be used for service startup.
type: str
password:
description:
- Password to be used for service startup.
type: str
start_mode:
description:
- If C(auto) is selected, the service will start at bootup.
- C(delayed) causes a delayed but automatic start after boot (added in version 2.5).
- C(manual) means that the service will start only when another service needs it.
- C(disabled) means that the service will stay off, regardless if it is needed or not.
type: str
choices: [ auto, delayed, disabled, manual ]
default: auto
seealso:

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

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

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

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

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

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

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

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

@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: win_path
version_added: "2.3"
@ -22,6 +22,7 @@ options:
name:
description:
- Target path environment variable name.
type: str
default: PATH
elements:
description:
@ -33,14 +34,17 @@ options:
- New path elements are appended to the path, and existing path elements may be moved closer to the end to satisfy the requested ordering.
- Paths are compared in a case-insensitive fashion, and trailing backslashes are ignored for comparison purposes. However, note that trailing
backslashes in YAML require quotes.
type: list
required: yes
state:
description:
- Whether the path elements specified in C(elements) should be present or absent.
type: str
choices: [ absent, present ]
scope:
description:
- The level at which the environment variable specified by C(name) should be managed (either for the current user or global machine scope).
type: str
choices: [ machine, user ]
default: machine
notes:
@ -51,7 +55,7 @@ notes:
This means that the minority of windows applications which can have
their environment changed without restarting will not be notified and
therefore will need restarting to pick up new environment settings.
User level environment variables will require an interactive user to
- User level environment variables will require an interactive user to
log out and in again before they become available.
seealso:
- module: win_environment

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

@ -24,6 +24,7 @@ options:
description:
- Path to a pester test file or a folder where tests can be found.
- If the path is a folder, the module will consider all ps1 files as Pester tests.
type: str
required: true
version:
description:
@ -32,19 +33,6 @@ author:
- Erwan Quelin (@equelin)
'''
RETURN = r'''
pester_version:
description: Version of the pester module found on the remote host.
returned: always
type: str
sample: 4.3.1
output:
description: Results of the Pester tests.
returned: success
type: list
sample: False
'''
EXAMPLES = r'''
- name: Get facts
setup:
@ -66,3 +54,16 @@ EXAMPLES = r'''
path: C:\Pester\test01.test.ps1
version: 4.1.0
'''
RETURN = r'''
pester_version:
description: Version of the pester module found on the remote host.
returned: always
type: str
sample: 4.3.1
output:
description: Results of the Pester tests.
returned: success
type: list
sample: false
'''

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

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

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

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

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

@ -1,6 +1,6 @@
#!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)
#AnsibleRequires -CSharpUtil Ansible.Basic

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

@ -1,14 +1,14 @@
#!/usr/bin/python
# -*- 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)
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: win_product_facts
short_description: Provides Windows product information (product id, product key)
@ -25,7 +25,7 @@ EXAMPLES = r'''
win_product_facts:
'''
RETURN = '''
RETURN = r'''
ansible_facts:
description: returned facts by this module
returned: always

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

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

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

@ -22,22 +22,26 @@ options:
name:
description:
- Name of the powershell module that has to be installed.
type: str
required: yes
allow_clobber:
description:
- If C(yes) imports all commands, even if they have the same names as commands that already exists. Available only in Powershell 5.1 or higher.
type: bool
default: 'no'
default: no
repository:
description:
- Name of the custom repository to register or use.
type: str
url:
description:
- URL of the custom repository to register.
type: str
state:
description:
- If C(present) a new module is installed.
- If C(absent) a module is removed.
type: str
choices: [ absent, present ]
default: present
notes:
@ -48,7 +52,7 @@ author:
- Daniele Lazzari (@dlazz)
'''
EXAMPLES = '''
EXAMPLES = r'''
---
- name: Add a powershell module
win_psmodule:
@ -80,21 +84,21 @@ EXAMPLES = '''
state: absent
'''
RETURN = '''
RETURN = r'''
---
output:
description: a message describing the task result.
description: A message describing the task result.
returned: always
sample: "Module PowerShellCookbook installed"
type: str
nuget_changed:
description: true when Nuget package provider is installed
description: True when Nuget package provider is installed.
returned: always
type: bool
sample: True
sample: true
repository_changed:
description: true when a custom repository is installed or removed
description: True when a custom repository is installed or removed.
returned: always
type: bool
sample: True
sample: true
'''

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

@ -23,26 +23,30 @@ options:
name:
description:
- Name of the repository to work with.
type: str
required: yes
source:
description:
- Specifies the URI for discovering and installing modules from this repository.
- A URI can be a NuGet server feed (most common situation), HTTP, HTTPS, FTP or file location.
type: str
state:
description:
- If C(present) a new repository is added or updated.
- If C(absent) a repository is removed.
type: str
choices: [ absent, present ]
default: present
installation_policy:
description:
- Sets the C(InstallationPolicy) of a repository.
- Will default to C(trusted) when creating a new repository.
type: str
choices: [ trusted, untrusted ]
notes:
- The PowerShellGet module (version 1.6.0 or newer) and the NuGet package provider (version 2.8.5.201 or newer) are required.
- See the examples on how to update the NuGet package provider.
- You can't use C(win_psrepository) to re-register (add) removed PSGallery, use the command C(Register-PSRepository -Default) instead.
- You can not use C(win_psrepository) to re-register (add) removed PSGallery, use the command C(Register-PSRepository -Default) instead.
seealso:
- module: win_psmodule
author:

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

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

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

@ -13,6 +13,7 @@ module: win_reboot
short_description: Reboot a windows machine
description:
- Reboot a Windows machine, wait for it to go down, come back up, and respond to commands.
- For non-Windows targets, use the M(reboot) module instead.
version_added: '2.1'
options:
pre_reboot_delay:
@ -64,7 +65,6 @@ notes:
- If a shutdown was already scheduled on the system, C(win_reboot) will abort the scheduled shutdown and enforce its own shutdown.
- Beware that when C(win_reboot) returns, the Windows system may not have settled yet and some base services could be in limbo.
This can result in unexpected behavior. Check the examples for ways to mitigate this.
- For non-Windows targets, use the M(reboot) module instead.
seealso:
- module: reboot
author:
@ -109,7 +109,7 @@ EXAMPLES = r'''
RETURN = r'''
rebooted:
description: true if the machine was rebooted
description: True if the machine was rebooted.
returned: always
type: bool
sample: true

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

@ -23,11 +23,13 @@ description:
options:
path:
description: The full registry key path including the hive to search for.
type: str
required: yes
aliases: [ key ]
name:
description:
- The registry property name to get information for, the return json will not include the sub_keys and properties entries for the I(key) specified.
type: str
aliases: [ entry, value, property ]
seealso:
- module: win_regedit
@ -54,12 +56,12 @@ changed:
description: Whether anything was changed.
returned: always
type: bool
sample: True
sample: true
exists:
description: States whether the registry key/property exists.
returned: success and path/property exists
type: bool
sample: True
sample: true
properties:
description: A dictionary containing all the properties and their values in the registry key.
returned: success, path exists and property not specified

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

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

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

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

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

@ -28,22 +28,23 @@ options:
path:
description:
- The full path including file name to the registry file on the remote machine to be merged
required: yes
type: path
required: yes
compare_key:
description:
- The parent key to use when comparing the contents of the registry to the contents of the file. Needs to be in HKLM or HKCU part of registry.
Use a PS-Drive style path for example HKLM:\SOFTWARE not HKEY_LOCAL_MACHINE\SOFTWARE
If not supplied, or the registry key is not found, no comparison will be made, and the module will report changed.
type: str
notes:
- Organise your registry files so that they contain a single root registry
key if you want to use the compare_to functionality.
This module does not force registry settings to be in the state
- This module does not force registry settings to be in the state
described in the file. If registry settings have been modified externally
the module will merge the contents of the file but continue to report
differences on subsequent runs.
To force registry change, use M(win_regedit) with state=absent before
using M(win_regmerge).
- To force registry change, use M(win_regedit) with C(state=absent) before
using C(win_regmerge).
seealso:
- module: win_reg_stat
- module: win_regedit

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

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

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

@ -21,12 +21,14 @@ description:
options:
destination:
description:
- Destination IP address in CIDR format (ip address/prefix length)
- Destination IP address in CIDR format (ip address/prefix length).
type: str
required: yes
gateway:
description:
- The gateway used by the static route.
- If C(gateway) is not provided it will be set to C(0.0.0.0).
type: str
metric:
description:
- Metric used by the static route.
@ -36,6 +38,7 @@ options:
description:
- If C(absent), it removes a network static route.
- If C(present), it adds a network static route.
type: str
choices: [ absent, present ]
default: present
notes:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -24,35 +24,34 @@ options:
description:
- The full path of the file/object to get the facts of; both forward and
back slashes are accepted.
required: yes
type: path
required: yes
get_md5:
description:
- Whether to return the checksum sum of the file. Between Ansible 1.9
and 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible
and Ansible 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible
2.3 this is back to an MD5. Will return None if host is unable to
use specified algorithm.
- The default of this option changed from C(yes) to C(no) in Ansible 2.5
and will be removed altogether in Ansible 2.9.
- Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an
- Use C(get_checksum=yes) with C(checksum_algorithm=md5) to return an
md5 hash under the C(checksum) return value.
type: bool
default: 'no'
default: no
get_checksum:
description:
- Whether to return a checksum of the file (default sha1)
type: bool
default: 'yes'
default: yes
version_added: "2.1"
checksum_algorithm:
description:
- Algorithm to determine checksum of file. Will throw an error if
the host is unable to use specified algorithm.
- Algorithm to determine checksum of file.
- Will throw an error if the host is unable to use specified algorithm.
type: str
default: sha1
choices: [ md5, sha1, sha256, sha384, sha512 ]
version_added: "2.3"
notes:
- For non-Windows targets, use the M(stat) module instead.
seealso:
- module: stat
- module: win_file
@ -106,137 +105,137 @@ changed:
description: Whether anything was changed
returned: always
type: bool
sample: True
sample: true
stat:
description: dictionary containing all the stat data
returned: success
type: complex
contains:
attributes:
description: Attributes of the file at path in raw form
description: Attributes of the file at path in raw form.
returned: success, path exists
type: str
sample: "Archive, Hidden"
checksum:
description: The checksum of a file based on checksum_algorithm specified
description: The checksum of a file based on checksum_algorithm specified.
returned: success, path exist, path is a file, get_checksum == True
checksum_algorithm specified is supported
type: str
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
creationtime:
description: The create time of the file represented in seconds since epoch
description: The create time of the file represented in seconds since epoch.
returned: success, path exists
type: float
sample: 1477984205.15
exists:
description: If the path exists or not
description: If the path exists or not.
returned: success
type: bool
sample: True
sample: true
extension:
description: The extension of the file at path
description: The extension of the file at path.
returned: success, path exists, path is a file
type: str
sample: ".ps1"
filename:
description: The name of the file (without path)
description: The name of the file (without path).
returned: success, path exists, path is a file
type: str
sammple: foo.ini
hlnk_targets:
description: List of other files pointing to the same file (hard links), excludes the current file
description: List of other files pointing to the same file (hard links), excludes the current file.
returned: success, path exists
type: list
sample:
- C:\temp\file.txt
- C:\Windows\update.log
isarchive:
description: If the path is ready for archiving or not
description: If the path is ready for archiving or not.
returned: success, path exists
type: bool
sample: True
sample: true
isdir:
description: If the path is a directory or not
description: If the path is a directory or not.
returned: success, path exists
type: bool
sample: True
sample: true
ishidden:
description: If the path is hidden or not
description: If the path is hidden or not.
returned: success, path exists
type: bool
sample: True
sample: true
isjunction:
description: If the path is a junction point or not
description: If the path is a junction point or not.
returned: success, path exists
type: bool
sample: True
sample: true
islnk:
description: If the path is a symbolic link or not
description: If the path is a symbolic link or not.
returned: success, path exists
type: bool
sample: True
sample: true
isreadonly:
description: If the path is read only or not
description: If the path is read only or not.
returned: success, path exists
type: bool
sample: True
sample: true
isreg:
description: If the path is a regular file
description: If the path is a regular file.
returned: success, path exists
type: bool
sample: True
sample: true
isshared:
description: If the path is shared or not
description: If the path is shared or not.
returned: success, path exists
type: bool
sample: True
sample: true
lastaccesstime:
description: The last access time of the file represented in seconds since epoch
description: The last access time of the file represented in seconds since epoch.
returned: success, path exists
type: float
sample: 1477984205.15
lastwritetime:
description: The last modification time of the file represented in seconds since epoch
description: The last modification time of the file represented in seconds since epoch.
returned: success, path exists
type: float
sample: 1477984205.15
lnk_source:
description: Target of the symlink normalized for the remote filesystem
description: Target of the symlink normalized for the remote filesystem.
returned: success, path exists and the path is a symbolic link or junction point
type: str
sample: C:\temp\link
lnk_target:
description: Target of the symlink. Note that relative paths remain relative
description: Target of the symlink. Note that relative paths remain relative.
returned: success, path exists and the path is a symbolic link or junction point
type: str
sample: ..\link
md5:
description: The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.9
description: The MD5 checksum of a file (Between Ansible 1.9 and Ansible 2.2 this was returned as a SHA1 hash), will be removed in Ansible 2.9.
returned: success, path exist, path is a file, get_md5 == True
type: str
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
nlink:
description: Number of links to the file (hard links)
description: Number of links to the file (hard links).
returned: success, path exists
type: int
sample: 1
owner:
description: The owner of the file
description: The owner of the file.
returned: success, path exists
type: str
sample: BUILTIN\Administrators
path:
description: The full absolute path to the file
description: The full absolute path to the file.
returned: success, path exists, file exists
type: str
sample: C:\foo.ini
sharename:
description: The name of share if folder is shared
description: The name of share if folder is shared.
returned: success, path exists, file is a directory and isshared == True
type: str
sample: file-share
size:
description: The size in bytes of a file or folder
description: The size in bytes of a file or folder.
returned: success, path exists, file is not a link
type: int
sample: 1024

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

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

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

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

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

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

@ -28,11 +28,13 @@ options:
group:
description:
- Which notification group to add the notification to.
type: str
default: Powershell
msg:
description:
- The message to appear inside the notification.
- May include \n to format the message to appear within the Action Center.
type: str
default: Hello, World!
popup:
description:
@ -42,10 +44,12 @@ options:
tag:
description:
- The tag to add to the notification.
type: str
default: Ansible
title:
description:
- The notification title, which appears in the pop up..
type: str
default: Notification HH:mm
notes:
- This module must run on a windows 10 or Server 2016 host, so ensure your play targets windows hosts, or delegates to a windows host.

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

@ -27,25 +27,25 @@ options:
src:
description:
- File to be unzipped (provide absolute path).
required: yes
type: path
required: yes
dest:
description:
- Destination of zip file (provide absolute path of directory). If it does not exist, the directory will be created.
required: yes
type: path
required: yes
delete_archive:
description:
- Remove the zip file, after unzipping.
type: bool
default: 'no'
default: no
aliases: [ rm ]
recurse:
description:
- Recursively expand zipped files within the src file.
- Setting to a value of C(yes) requires the PSCX module to be installed.
type: bool
default: 'no'
default: no
creates:
description:
- If this file or directory exists the specified src will not be extracted.
@ -55,7 +55,6 @@ notes:
- For extracting any compression types other than .zip, the PowerShellCommunityExtensions (PSCX) Module is required. This module (in conjunction with PSCX)
has the ability to recursively unzip files within the src zip file provided and also functionality for many other compression types. If the destination
directory does not exist, it will be created before unzipping the file. Specifying rm parameter will force removal of the src file after extraction.
- For non-Windows targets, use the M(unarchive) module instead.
seealso:
- module: unarchive
author:
@ -64,7 +63,7 @@ author:
EXAMPLES = r'''
# This unzips a library that was downloaded with win_get_url, and removes the file after extraction
# $ ansible -i hosts -m win_unzip -a "src=C:\LibraryToUnzip.zip dest=C:\Lib remove=true" all
# $ ansible -i hosts -m win_unzip -a "src=C:\LibraryToUnzip.zip dest=C:\Lib remove=yes" all
- name: Unzip a bz2 (BZip) file
win_unzip:
@ -105,7 +104,7 @@ removed:
description: Whether the module did remove any files during task run
returned: always
type: bool
sample: True
sample: true
src:
description: The provided source path
returned: always

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

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

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

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

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

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

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

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.
- If C(state=drained) then it will only check for connections on the IP
specified, you can use '0.0.0.0' to use all host IPs.
type: str
default: '127.0.0.1'
path:
description:
@ -67,6 +68,7 @@ options:
matches.
- If C(state) is absent then it will wait until the regex does not match.
- Defaults to a multiline regex.
type: str
sleep:
description:
- Number of seconds to sleep between checks.
@ -80,8 +82,9 @@ options:
- When checking for a file or a search string C(present) or C(started) will
ensure that the file or string is present, C(absent) will check that the
file or search string is absent or removed.
default: started
type: str
choices: [ absent, drained, present, started, stopped ]
default: started
timeout:
description:
- The maximum number of seconds to wait for.
@ -95,40 +98,40 @@ author:
'''
EXAMPLES = r'''
- name: wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
- name: Wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
win_wait_for:
port: 8000
delay: 10
- name: wait 150 seconds for port 8000 of any IP to close active connections
- name: Wait 150 seconds for port 8000 of any IP to close active connections
win_wait_for:
host: 0.0.0.0
port: 8000
state: drained
timeout: 150
- name: wait for port 8000 of any IP to close active connection, ignoring certain hosts
- name: Wait for port 8000 of any IP to close active connection, ignoring certain hosts
win_wait_for:
host: 0.0.0.0
port: 8000
state: drained
exclude_hosts: ['10.2.1.2', '10.2.1.3']
- name: wait for file C:\temp\log.txt to exist before continuing
- name: Wait for file C:\temp\log.txt to exist before continuing
win_wait_for:
path: C:\temp\log.txt
- name: wait until process complete is in the file before continuing
- name: Wait until process complete is in the file before continuing
win_wait_for:
path: C:\temp\log.txt
search_regex: process complete
- name: wait until file if removed
- name: Wait until file is removed
win_wait_for:
path: C:\temp\log.txt
state: absent
- name: wait until port 1234 is offline but try every 10 seconds
- name: Wait until port 1234 is offline but try every 10 seconds
win_wait_for:
port: 1234
state: absent

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

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

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
description:
- The C(win_wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets.
- For non-Windows targets, use the M(wakeonlan) module instead.
options:
mac:
description:
- MAC address to send Wake-on-LAN broadcast packet for.
type: str
required: yes
broadcast:
description:
- Network broadcast address to use for broadcasting magic Wake-on-LAN packet.
type: str
default: 255.255.255.255
port:
description:

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

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

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

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