cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update command/shell docs with note about modules for rebooting(#51499)

Browse source 
(cherry picked from commit ad386290b4)
This commit is contained in:
Sam Doran 2019-02-13 13:54:36 -05:00 committed by Toshio Kuratomi
parent b7b4182bbd
commit 805c9fa712
3 changed files with 138 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
lib/ansible/modules/commands/command.py
View file

@ -68,6 +68,12 @@ notes:
check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.
- The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(shell) module instead.
- For Windows targets, use the M(win_command) module instead.
- For rebooting systems, use the M(reboot) or M(win_reboot) module.
seealso:
- module: raw
- module: script
- module: shell
- module: win_command
author:
- Ansible Core Team
- Michael DeHaan
@ -154,18 +160,18 @@ def check_command(module, commandline):
command = os.path.basename(command)
disable_suffix = "If you need to use command because {mod} is insufficient you can add" \
" warn=False to this command task or set command_warnings=False in" \
" 'warn: false' to this command task or set 'command_warnings=False' in" \
" ansible.cfg to get rid of this message."
substitutions = {'mod': None, 'cmd': command}
if command in arguments:
msg = "Consider using the {mod} module with {subcmd} rather than running {cmd}. " + disable_suffix
msg = "Consider using the {mod} module with {subcmd} rather than running '{cmd}'. " + disable_suffix
substitutions['mod'] = 'file'
substitutions['subcmd'] = arguments[command]
module.warn(msg.format(**substitutions))
if command in commands:
msg = "Consider using the {mod} module rather than running {cmd}. " + disable_suffix
msg = "Consider using the {mod} module rather than running '{cmd}'. " + disable_suffix
substitutions['mod'] = commands[command]
module.warn(msg.format(**substitutions))

9
lib/ansible/modules/commands/shell.py
View file

@ -67,8 +67,13 @@ notes:
are not supplied, the task will be skipped.
- 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,
- An alternative to using inline shell scripts with this module is to use
the M(script) module possibly together with the M(template) module.
- For rebooting systems, use the M(reboot) or M(win_reboot) module.
seealso:
- module: command
- module: raw
- module: script
use the M(script) module instead.
requirements: [ ]
author:

208
test/integration/targets/command_shell/tasks/main.yml
View file

@ -1,20 +1,7 @@
# Test code for the command and shell modules.
# (c) 2014, Richard Isaacson <richard.c.isaacson@gmail.com>
# 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/>.
# Copyright: (c) 2014, Richard Isaacson <richard.c.isaacson@gmail.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
- name: use command to execute sudo
command: sudo -h
@ -42,8 +29,8 @@
- name: assert tar warning was reported
assert:
that:
- "tar.warnings | length() == 1"
- "'Consider using the unarchive module rather than running tar' in tar.warnings[0]"
- tar.warnings | length() == 1
- '"Consider using the unarchive module rather than running ''tar''" in tar.warnings[0]'
- name: use command to execute chown
command: chown -h
@ -53,31 +40,35 @@
- name: assert chown warning was reported
assert:
that:
- "chown.warnings | length() == 1"
- "'Consider using the file module with owner rather than running chown' in chown.warnings[0]"
- chown.warnings | length() == 1
- '"Consider using the file module with owner rather than running ''chown''" in chown.warnings[0]'
- name: use command with unsupported executable arg
command: ls /dev/null executable=/bogus
command: ls /dev/null
args:
executable: /bogus
register: executable
- name: assert executable warning was reported
assert:
that:
- "executable.stdout == '/dev/null'"
- "executable.warnings | length() == 1"
- executable.stdout == '/dev/null'
- executable.warnings | length() == 1
- "'no longer supported' in executable.warnings[0]"
- name: use command with no command
command: chdir=/
command:
args:
chdir: /
register: no_command
ignore_errors: true
- name: assert executable fails with no command
assert:
that:
- "no_command.failed == true"
- "no_command.msg == 'no command given'"
- "no_command.rc == 256"
- no_command is failed
- no_command.msg == 'no command given'
- no_command.rc == 256
- name: use argv
command:
@ -104,26 +95,40 @@
- name: assert executable fails with both argv and command string
assert:
that:
- "argv_and_string_command.failed == true"
- "argv_and_string_command.msg == 'only command or argv can be given, not both'"
- "argv_and_string_command.rc == 256"
- argv_and_string_command is failed
- argv_and_string_command.msg == 'only command or argv can be given, not both'
- argv_and_string_command.rc == 256
- set_fact: output_dir_test={{output_dir}}/test_command_shell
- set_fact:
output_dir_test: "{{ output_dir }}/test_command_shell"
- name: make sure our testing sub-directory does not exist
file: path="{{ output_dir_test }}" state=absent
file:
path: "{{ output_dir_test }}"
state: absent
- name: create our testing sub-directory
file: path="{{ output_dir_test }}" state=directory
file:
path: "{{ output_dir_test }}"
state: directory
- name: prep our test script
copy: src=test.sh dest="{{ output_dir_test }}" mode=0755
copy:
src: test.sh
dest: "{{ output_dir_test }}"
mode: '0755'
- name: prep our test script
copy: src=create_afile.sh dest="{{ output_dir_test }}" mode=0755
copy:
src: create_afile.sh
dest: "{{ output_dir_test }}"
mode: '0755'
- name: prep our test script
copy: src=remove_afile.sh dest="{{ output_dir_test }}" mode=0755
copy:
src: remove_afile.sh
dest: "{{ output_dir_test }}"
mode: '0755'
- name: locate bash
shell: which bash
@ -134,22 +139,22 @@
##
- name: execute the test.sh script via command
command: "{{output_dir_test | expanduser}}/test.sh"
command: "{{ output_dir_test }}/test.sh"
register: command_result0
- name: assert that the script executed correctly
assert:
that:
- "command_result0.rc == 0"
- "command_result0.stderr == ''"
- "command_result0.stdout == 'win'"
- command_result0.rc == 0
- command_result0.stderr == ''
- command_result0.stdout == 'win'
# executable
# FIXME doesn't have the expected stdout.
#- name: execute the test.sh script with executable via command
# command: "{{output_dir_test | expanduser}}/test.sh executable={{ bash.stdout }}"
# command: "{{output_dir_test }}/test.sh executable={{ bash.stdout }}"
# register: command_result1
#
#- name: assert that the script executed correctly with command
@ -162,55 +167,69 @@
# chdir
- name: execute the test.sh script with chdir via command
command: ./test.sh chdir="{{output_dir_test | expanduser}}"
command: ./test.sh
args:
chdir: "{{ output_dir_test }}"
register: command_result2
- name: assert that the script executed correctly with chdir
assert:
that:
- "command_result2.rc == 0"
- "command_result2.stderr == ''"
- "command_result2.stdout == 'win'"
- command_result2.rc == 0
- command_result2.stderr == ''
- command_result2.stdout == 'win'
# creates
- name: verify that afile.txt is absent
file: path={{output_dir_test}}/afile.txt state=absent
file:
path: "{{ output_dir_test }}/afile.txt"
state: absent
- name: create afile.txt with create_afile.sh via command
command: "{{output_dir_test | expanduser}}/create_afile.sh {{output_dir_test | expanduser}}/afile.txt creates={{output_dir_test | expanduser}}/afile.txt"
command: "{{ output_dir_test }}/create_afile.sh {{output_dir_test }}/afile.txt"
args:
creates: "{{ output_dir_test }}/afile.txt"
- name: verify that afile.txt is present
file: path={{output_dir_test}}/afile.txt state=file
file:
path: "{{ output_dir_test }}/afile.txt"
state: file
- name: re-run previous command using creates with globbing
command: "{{output_dir_test | expanduser}}/create_afile.sh {{output_dir_test | expanduser}}/afile.txt creates={{output_dir_test | expanduser}}/afile.*"
command: "{{ output_dir_test }}/create_afile.sh {{ output_dir_test }}/afile.txt"
args:
creates: "{{ output_dir_test }}/afile.*"
register: command_result3
- name: assert that creates with globbing is working
assert:
that:
- "command_result3.changed != True"
- command_result3 is not changed
# removes
- name: remove afile.txt with remote_afile.sh via command
command: "{{output_dir_test | expanduser}}/remove_afile.sh {{output_dir_test | expanduser}}/afile.txt removes={{output_dir_test | expanduser}}/afile.txt"
command: "{{ output_dir_test }}/remove_afile.sh {{ output_dir_test }}/afile.txt"
args:
removes: "{{ output_dir_test }}/afile.txt"
- name: verify that afile.txt is absent
file: path={{output_dir_test}}/afile.txt state=absent
- name: re-run previous command using removes with globbing
command: "{{output_dir_test | expanduser}}/remove_afile.sh {{output_dir_test | expanduser}}/afile.txt removes={{output_dir_test | expanduser}}/afile.*"
command: "{{ output_dir_test }}/remove_afile.sh {{ output_dir_test }}/afile.txt"
args:
removes: "{{ output_dir_test }}/afile.*"
register: command_result4
- name: assert that removes with globbing is working
assert:
that:
- "command_result4.changed != True"
- command_result4.changed != True
- name: pass stdin to cat via command
command: "cat"
command: cat
args:
stdin: 'foobar'
register: command_result5
@ -218,10 +237,10 @@
- name: assert that stdin is passed
assert:
that:
- "command_result5.stdout == 'foobar'"
- command_result5.stdout == 'foobar'
- name: send to stdin literal multiline block
command: "{{ ansible_python_interpreter }} -c 'import hashlib, sys; print(hashlib.sha1((sys.stdin.buffer if hasattr(sys.stdin, \"buffer\") else sys.stdin).read()).hexdigest())'"
command: "{{ ansible_python.executable }} -c 'import hashlib, sys; print(hashlib.sha1((sys.stdin.buffer if hasattr(sys.stdin, \"buffer\") else sys.stdin).read()).hexdigest())'"
args:
stdin: |-
this is the first line
@ -240,23 +259,25 @@
## shell
##
- name: execute the test.sh script
shell: "{{output_dir_test | expanduser}}/test.sh"
- name: Execute the test.sh script
shell: "{{ output_dir_test }}/test.sh"
register: shell_result0
- name: assert that the script executed correctly
- name: Assert that the script executed correctly
assert:
that:
- "shell_result0.rc == 0"
- "shell_result0.stderr == ''"
- "shell_result0.stdout == 'win'"
- shell_result0 is changed
- shell_result0.cmd == '{{ output_dir_test }}/test.sh'
- shell_result0.rc == 0
- shell_result0.stderr == ''
- shell_result0.stdout == 'win'
# executable
# FIXME doesn't pass the expected stdout
#- name: execute the test.sh script
# shell: "{{output_dir_test | expanduser}}/test.sh executable={{ bash.stdout }}"
# shell: "{{output_dir_test }}/test.sh executable={{ bash.stdout }}"
# register: shell_result1
#
#- name: assert that the shell executed correctly
@ -268,34 +289,47 @@
# chdir
- name: execute the test.sh script with chdir
shell: ./test.sh chdir="{{output_dir_test | expanduser}}"
- name: Execute the test.sh script with chdir
shell: ./test.sh
args:
chdir: "{{ output_dir_test }}"
register: shell_result2
- name: assert that the shell executed correctly with chdir
- name: Assert that the shell executed correctly with chdir
assert:
that:
- "shell_result2.rc == 0"
- "shell_result2.stderr == ''"
- "shell_result2.stdout == 'win'"
- shell_result2 is changed
- shell_result2.cmd == './test.sh'
- shell_result2.rc == 0
- shell_result2.stderr == ''
- shell_result2.stdout == 'win'
# creates
- name: verify that afile.txt is absent
file: path={{output_dir_test}}/afile.txt state=absent
- name: Verify that afile.txt is absent
file:
path: "{{ output_dir_test }}/afile.txt"
state: absent
- name: execute the test.sh script with chdir
shell: "{{output_dir_test | expanduser}}/test.sh > {{output_dir_test | expanduser}}/afile.txt creates={{output_dir_test | expanduser}}/afile.txt"
- name: Execute the test.sh script with chdir
shell: "{{ output_dir_test }}/test.sh > {{ output_dir_test }}/afile.txt"
args:
chdir: "{{ output_dir_test }}"
creates: "{{ output_dir_test }}/afile.txt"
- name: verify that afile.txt is present
file: path={{output_dir_test}}/afile.txt state=file
- name: Verify that afile.txt is present
file:
path: "{{ output_dir_test }}/afile.txt"
state: file
# multiline
- name: remove test file previously created
file: path={{output_dir_test | expanduser}}/afile.txt state=absent
- name: Remove test file previously created
file:
path: "{{ output_dir_test | expanduser }}/afile.txt"
state: absent
- name: execute a shell command using a literal multiline block
- name: Execute a shell command using a literal multiline block
args:
executable: "{{ bash.stdout }}"
shell: |
@ -307,24 +341,26 @@
echo "this is a second line"
register: shell_result5
- name: assert the multiline shell command ran as expected
- name: Assert the multiline shell command ran as expected
assert:
that:
- "shell_result5.changed"
- "shell_result5.stdout == '5575bb6b71c9558db0b6fbbf2f19909eeb4e3b98\nthis is a second line'"
- shell_result5 is changed
- shell_result5.stdout == '5575bb6b71c9558db0b6fbbf2f19909eeb4e3b98\nthis is a second line'
- name: execute a shell command using a literal multiline block with arguments in it
- name: Execute a shell command using a literal multiline block with arguments in it
shell: |
executable="{{ bash.stdout }}"
creates={{output_dir_test | expanduser}}/afile.txt
echo "test"
register: shell_result6
- name: assert the multiline shell command with arguments in it run as expected
- name: Assert the multiline shell command with arguments in it run as expected
assert:
that:
- "shell_result6.changed"
- "shell_result6.stdout == 'test'"
- shell_result6.changed
- shell_result6.stdout == 'test'
- name: remove the previously created file
file: path={{output_dir_test}}/afile.txt state=absent
- name: Remove the previously created file
file:
path: "{{ output_dir_test }}/afile.txt"
state: absent