add win_shell/win_command modules + docs (#4827)

2025-07-24 13:50:22 -07:00 · 2016-09-15 08:42:10 -07:00 · 2016-09-15 08:42:10 -07:00 · 6daa34e1c5
commit 6daa34e1c5
parent 6733d1c72c
4 changed files with 482 additions and 0 deletions
--- a/lib/ansible/modules/windows/win_command.py
+++ b/lib/ansible/modules/windows/win_command.py
@ -0,0 +1,121 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2016, Ansible, inc
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+DOCUMENTATION = '''
+---
+module: win_command
+short_description: Executes a command on a remote Windows node
+version_added: 2.2
+description:
+     - The M(win_command) module takes the command name followed by a list of space-delimited arguments.
+     - The given command will be executed on all selected nodes. It will not be
+       processed through the shell, so variables like C($env:HOME) and operations
+       like C("<"), C(">"), C("|"), and C(";") will not work (use the M(win_shell)
+       module if you need these features).
+options:
+  free_form:
+    description:
+      - the win_command module takes a free form command to run.  There is no parameter actually named 'free form'.
+        See the examples!
+    required: true
+  creates:
+    description:
+      - a path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
+  removes:
+    description:
+      - a path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be skipped.
+  chdir:
+    description:
+      - set the specified path as the current working directory before executing a command
+notes:
+    -  If you want to run a command through a shell (say you are using C(<),
+       C(>), C(|), etc), you actually want the M(win_shell) module instead. The
+       M(win_command) module is much more secure as it's not affected by the user's
+       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."
+author: 
+    - Matt Davis
+'''
+
+EXAMPLES = '''
+# Example from Ansible Playbooks.
+- win_command: whoami
+  register: whoami_out
+
+# Run the command only if the specified file does not exist.
+- win_command: wbadmin -backupTarget:c:\\backup\\ creates=c:\\backup\\
+
+# You can also use the 'args' form to provide the options. This command
+# will change the working directory to c:\\somedir\\ and will only run when
+# c:\\backup\\ doesn't exist.
+- win_command: wbadmin -backupTarget:c:\\backup\\ creates=c:\\backup\\
+  args:
+    chdir: c:\\somedir\\
+    creates: c:\\backup\\
+'''
+
+RETURN = '''
+msg:
+    description: changed
+    returned: always
+    type: boolean
+    sample: True
+start:
+    description: The command execution start time
+    returned: always
+    type: string
+    sample: '2016-02-25 09:18:26.429568'
+end:
+    description: The command execution end time
+    returned: always
+    type: string
+    sample: '2016-02-25 09:18:26.755339'
+delta:
+    description: The command execution delta time
+    returned: always
+    type: string
+    sample: '0:00:00.325771'
+stdout:
+    description: The command standard output
+    returned: always
+    type: string
+    sample: 'Clustering node rabbit@slave1 with rabbit@master ...'
+stderr:
+    description: The command standard error
+    returned: always
+    type: string
+    sample: 'ls: cannot access foo: No such file or directory'
+cmd:
+    description: The command executed by the task
+    returned: always
+    type: string
+    sample: 'rabbitmqctl join_cluster rabbit@master'
+rc:
+    description: The command return code (0 means success)
+    returned: always
+    type: int
+    sample: 0
+stdout_lines:
+    description: The command standard output split in lines
+    returned: always
+    type: list of strings
+    sample: [u'Clustering node rabbit@slave1 with rabbit@master ...']
+'''