ansible/library/commands/shell

73 lines
2.5 KiB
Text
Raw Normal View History

# There is actually 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".
2012-09-29 20:40:06 +02:00
DOCUMENTATION = '''
---
module: shell
short_description: Execute commands in nodes.
description:
- The M(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
2012-10-05 14:59:49 +02:00
the command through a shell (C(/bin/sh)) on the remote node.
version_added: "0.2"
2012-09-29 20:40:06 +02:00
options:
free_form:
2012-09-29 20:40:06 +02:00
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
2012-09-29 20:40:06 +02:00
default: null
creates:
description:
- a filename, when it already exists, this step will B(not) be run.
required: no
default: null
removes:
description:
- a filename, when it does not exist, this step will B(not) be run.
version_added: "0.8"
required: no
2012-09-29 20:40:06 +02:00
default: null
chdir:
description:
2012-11-21 18:49:30 +01:00
- cd into this directory before running the command
2012-09-29 20:40:06 +02:00
required: false
default: null
2012-11-21 18:49:30 +01:00
version_added: "0.6"
executable:
description:
- change the shell used to execute the command. Should be an absolute path to the executable.
required: false
default: null
version_added: "0.9"
2012-09-29 20:40:06 +02:00
notes:
2012-11-21 18:49:30 +01:00
- If you want to execute a command securely and predictably, it may be
2012-10-01 09:18:54 +02:00
better to use the M(command) module instead. Best practices when writing
playbooks will follow the trend of using M(command) unless M(shell) is
explicitly required. When running ad-hoc commands, use your best
judgement.
2014-07-19 00:23:48 +02:00
- 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.
2012-09-29 20:40:06 +02:00
requirements: [ ]
author: Michael DeHaan
2012-10-01 09:18:54 +02:00
'''
EXAMPLES = '''
# Execute the command in remote shell; stdout goes to the specified
2014-06-24 13:40:19 +02:00
# file on the remote.
- shell: somescript.sh >> somelog.txt
2014-06-24 13:40:19 +02:00
# Change the working directory to somedir/ before executing the command.
- shell: somescript.sh >> somelog.txt chdir=somedir/
# You can also use the 'args' form to provide the options. This command
# will change the working directory to somedir/ and will only run when
# somedir/somelog.txt doesn't exist.
- shell: somescript.sh >> somelog.txt
args:
chdir: somedir/
creates: somelog.txt
'''