1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2016, Ansible, inc 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7ANSIBLE_METADATA = {'metadata_version': '1.1', 8 'status': ['preview'], 9 'supported_by': 'core'} 10 11DOCUMENTATION = r''' 12--- 13module: win_command 14short_description: Executes a command on a remote Windows node 15version_added: 2.2 16description: 17 - The C(win_command) module takes the command name followed by a list of space-delimited arguments. 18 - The given command will be executed on all selected nodes. It will not be 19 processed through the shell, so variables like C($env:HOME) and operations 20 like C("<"), C(">"), C("|"), and C(";") will not work (use the M(win_shell) 21 module if you need these features). 22 - For non-Windows targets, use the M(command) module instead. 23options: 24 free_form: 25 description: 26 - The C(win_command) module takes a free form command to run. 27 - There is no parameter actually named 'free form'. See the examples! 28 type: str 29 required: yes 30 creates: 31 description: 32 - A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped. 33 type: path 34 removes: 35 description: 36 - A path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be skipped. 37 type: path 38 chdir: 39 description: 40 - Set the specified path as the current working directory before executing a command. 41 type: path 42 stdin: 43 description: 44 - Set the stdin of the command directly to the specified value. 45 type: str 46 version_added: '2.5' 47 output_encoding_override: 48 description: 49 - This option overrides the encoding of stdout/stderr output. 50 - You can use this option when you need to run a command which ignore the console's codepage. 51 - You should only need to use this option in very rare circumstances. 52 - This value can be any valid encoding C(Name) based on the output of C([System.Text.Encoding]::GetEncodings()). 53 See U(https://docs.microsoft.com/dotnet/api/system.text.encoding.getencodings). 54 type: str 55 version_added: '2.10' 56notes: 57 - If you want to run a command through a shell (say you are using C(<), 58 C(>), C(|), etc), you actually want the M(win_shell) module instead. The 59 C(win_command) module is much more secure as it's not affected by the user's 60 environment. 61 - 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 62 exist, use this. 63seealso: 64- module: command 65- module: psexec 66- module: raw 67- module: win_psexec 68- module: win_shell 69author: 70 - Matt Davis (@nitzmahone) 71''' 72 73EXAMPLES = r''' 74- name: Save the result of 'whoami' in 'whoami_out' 75 win_command: whoami 76 register: whoami_out 77 78- name: Run command that only runs if folder exists and runs from a specific folder 79 win_command: wbadmin -backupTarget:C:\backup\ 80 args: 81 chdir: C:\somedir\ 82 creates: C:\backup\ 83 84- name: Run an executable and send data to the stdin for the executable 85 win_command: powershell.exe - 86 args: 87 stdin: Write-Host test 88''' 89 90RETURN = r''' 91msg: 92 description: changed 93 returned: always 94 type: bool 95 sample: true 96start: 97 description: The command execution start time 98 returned: always 99 type: str 100 sample: '2016-02-25 09:18:26.429568' 101end: 102 description: The command execution end time 103 returned: always 104 type: str 105 sample: '2016-02-25 09:18:26.755339' 106delta: 107 description: The command execution delta time 108 returned: always 109 type: str 110 sample: '0:00:00.325771' 111stdout: 112 description: The command standard output 113 returned: always 114 type: str 115 sample: 'Clustering node rabbit@slave1 with rabbit@master ...' 116stderr: 117 description: The command standard error 118 returned: always 119 type: str 120 sample: 'ls: cannot access foo: No such file or directory' 121cmd: 122 description: The command executed by the task 123 returned: always 124 type: str 125 sample: 'rabbitmqctl join_cluster rabbit@master' 126rc: 127 description: The command return code (0 means success) 128 returned: always 129 type: int 130 sample: 0 131stdout_lines: 132 description: The command standard output split in lines 133 returned: always 134 type: list 135 sample: [u'Clustering node rabbit@slave1 with rabbit@master ...'] 136''' 137