diff --git a/lib/ansible/modules/commands/command.py b/lib/ansible/modules/commands/command.py index 7f4a73d630..264609dec7 100644 --- a/lib/ansible/modules/commands/command.py +++ b/lib/ansible/modules/commands/command.py @@ -3,7 +3,6 @@ # Copyright: (c) 2012, Michael DeHaan , and others # Copyright: (c) 2016, Toshio Kuratomi -# # 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 @@ -14,10 +13,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['stableinterface'], 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: command -short_description: Executes a command on a remote node +short_description: Execute commands on targets version_added: historical description: - The C(command) module takes the command name followed by a list of space-delimited arguments. @@ -29,8 +28,9 @@ description: options: free_form: description: - - The command module takes a free form command to run. There is no parameter actually named 'free form'. - See the examples! + - The command module takes a free form command to run. + - There is no actual parameter named 'free form'. + - See the examples on how to use this module. required: yes argv: description: @@ -50,14 +50,14 @@ options: version_added: "0.6" warn: description: - - If command_warnings are on in ansible.cfg, do not warn about this particular line if set to C(no). + - Enable or disable task warnings. type: bool - default: 'yes' + default: yes version_added: "1.8" stdin: - version_added: "2.4" description: - Set the stdin of the command directly to the specified value. + version_added: "2.4" notes: - If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(shell) module instead. Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to @@ -73,7 +73,7 @@ author: - Michael DeHaan ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: return motd to registered var command: cat /etc/motd register: mymotd @@ -102,7 +102,7 @@ EXAMPLES = ''' register: myoutput ''' -RETURN = ''' +RETURN = r''' cmd: description: the cmd that was run on the remote machine returned: always diff --git a/lib/ansible/modules/commands/shell.py b/lib/ansible/modules/commands/shell.py index 264f373bba..b211eb7efb 100644 --- a/lib/ansible/modules/commands/shell.py +++ b/lib/ansible/modules/commands/shell.py @@ -1,7 +1,10 @@ -# Copyright: Ansible Project +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright: (c) 2018, Ansible Project # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) -# # There is no actual shell module source, when you use 'shell' in ansible, +# There is no actual shell module source, when you use 'shell' in ansible, # it runs the 'command' module with special arguments and it behaves differently. # See the command source and the comment "#USE_SHELL". @@ -14,47 +17,49 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: shell -short_description: Execute commands in nodes. +short_description: Execute shell commands on targets description: - The C(shell) module takes the command name followed by a list of space-delimited arguments. - It is almost exactly like the M(command) module but runs + - It is almost exactly like the M(command) module but runs the command through a shell (C(/bin/sh)) on the remote node. - For Windows targets, use the M(win_shell) module instead. version_added: "0.2" options: free_form: description: - - The shell module takes a free form command to run, as a string. There's not an actual - option named "free form". See the examples! - required: true + - The shell module takes a free form command to run, as a string. + - There is no actual parameter named 'free form'. + - See the examples on how to use this module. + required: yes creates: description: - - a filename, when it already exists, this step will B(not) be run. + - A filename, when it already exists, this step will B(not) be run. removes: description: - - a filename, when it does not exist, this step will B(not) be run. + - A filename, when it does not exist, this step will B(not) be run. version_added: "0.8" chdir: description: - - cd into this directory before running the command + - Change into this directory before running the command. version_added: "0.6" executable: description: - - change the shell used to execute the command. Should be an absolute path to the executable. + - Change the shell used to execute the command. + - This expects an absolute path to the executable. version_added: "0.9" warn: description: - - if command warnings are on in ansible.cfg, do not warn about this particular line if set to no/false. + - Enable or disable task warnings. type: bool - default: 'yes' + default: yes version_added: "1.8" stdin: - version_added: "2.4" description: - Set the stdin of the command directly to the specified value. + version_added: "2.4" notes: - If you want to execute a command securely and predictably, it may be better to use the M(command) module instead. Best practices when writing @@ -68,15 +73,12 @@ notes: - To sanitize any variables passed to the shell module, you should use "{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons. - For Windows targets, use the M(win_shell) module instead. - - Rather than using here documents to create multi-line scripts inside playbooks, - use the M(script) module instead. -requirements: [ ] author: - Ansible Core Team - Michael DeHaan ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Execute the command in remote shell; stdout goes to the specified file on the remote. shell: somescript.sh >> somelog.txt @@ -107,13 +109,13 @@ EXAMPLES = ''' spawn ssh admin@{{ cimc_host }} expect "password:" - send "{{ cimc_password }}\\n" + send "{{ cimc_password }}\n" - expect "\\n{{ cimc_name }}" - send "connect host\\n" + expect "\n{{ cimc_name }}" + send "connect host\n" expect "pxeboot.n12" - send "\\n" + send "\n" exit 0 args: @@ -124,10 +126,10 @@ EXAMPLES = ''' - name: Using curl to connect to a host via SOCKS proxy (unsupported in uri). Ordinarily this would throw a warning. shell: curl --socks5 localhost:9000 http://www.ansible.com args: - warn: False + warn: no ''' -RETURN = ''' +RETURN = r''' msg: description: changed returned: always