Add Windows example of raw command (#47153)

* Add Windows example of raw command

Perform shutdown of Windows OS using Microsoft.PowerShell.Management module

* Capitalized cmdlet, remove quotes and improve description

This commit also cleans up some of the description sections.

* Use another example as suggested by jborean93

I was happy to merge this before I noticed jborean93 objected to the example :-/

* Fix whitespace issue
This commit is contained in:
Jorgen 2018-11-30 17:12:19 +01:00 committed by Dag Wieers
parent c78c8d389f
commit 8ff13db17c

View file

@ -1,5 +1,6 @@
# this is a virtual module that is entirely implemented server side
# Copyright: Ansible Project
# This is a virtual module that is entirely implemented server side
# Copyright: (c) 2012, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
@ -11,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: raw
short_description: Executes a low-down and dirty SSH command
@ -19,25 +20,26 @@ version_added: historical
options:
free_form:
description:
- the raw module takes a free form command to run. There is no parameter actually named 'free form'; see the examples!
- The raw module takes a free form command to run. There is no parameter actually named 'free form'; see the examples!
required: true
executable:
description:
- change the shell used to execute the command. Should be an absolute path to the executable.
- when using privilege escalation (C(become)), a default shell will be assigned if one is not provided
- Change the shell used to execute the command. Should be an absolute path to the executable.
- When using privilege escalation (C(become)) a default shell will be assigned if one is not provided
as privilege escalation requires a shell.
required: false
version_added: "1.0"
description:
- Executes a low-down and dirty SSH command, not going through the module
subsystem. This is useful and should only be done in a few cases. A common
subsystem.
- This is useful and should only be done in a few cases. A common
case is installing C(python) on a system without python installed by default.
Another is speaking to any devices such as
routers that do not have any Python installed. In any other case, using
the M(shell) or M(command) module is much more appropriate. Arguments
given to C(raw) are run directly through the configured remote shell.
Standard output, error output and return code are returned when
available. There is no change handler support for this module.
the M(shell) or M(command) module is much more appropriate.
- Arguments given to C(raw) are run directly through the configured remote shell.
- Standard output, error output and return code are returned when
available.
- There is no change handler support for this module.
- This module does not require python on the remote system, much like
the M(script) module.
- This module is also supported for Windows targets.
@ -47,7 +49,7 @@ notes:
onto the machine."
- If you want to execute a command securely and predictably, it may be
better to use the M(command) or M(shell) modules instead.
- the C(environment) keyword does not work with raw normally, it requires a shell
- The C(environment) keyword does not work with raw normally, it requires a shell
which means it only works if C(executable) is set or using the module
with privilege escalation (C(become)).
- This module is also supported for Windows targets.
@ -56,7 +58,7 @@ author:
- Michael DeHaan
'''
EXAMPLES = '''
EXAMPLES = r'''
- name: Bootstrap a host without python2 installed
raw: dnf install -y python2 python2-dnf libselinux-python
@ -65,6 +67,9 @@ EXAMPLES = '''
args:
executable: /bin/bash
- name: safely use templated variables. Always use quote filter to avoid injection issues.
raw: "{{package_mgr|quote}} {{pkg_flags|quote}} install {{python|quote}}"
- name: Safely use templated variables. Always use quote filter to avoid injection issues.
raw: "{{ package_mgr|quote }} {{ pkg_flags|quote }} install {{ python|quote }}"
- name: List user accounts on a Windows system
raw: Get-WmiObject -Class Win32_UserAccount
'''