Documentation

script - Runs a local script on a remote node after transferring it

Synopsis

  • The script module takes the script name followed by a list of space-delimited arguments.
  • The local script at path will be transferred to the remote node and then executed.
  • The given script will be processed through the shell environment on the remote node.
  • This module does not require python on the remote system, much like the raw module.
  • This module is also supported for Windows targets.

Parameters

Parameter Choices/Defaults Comments
chdir
(added in 2.4)
cd into this directory on the remote node before running the script
creates
(added in 1.5)
a filename, when it already exists, this step will not be run.
decrypt
bool

(added in 2.4)
    Choices:
  • no
  • yes
Default:
Yes
This option controls the autodecryption of source files using vault.
executable
(added in 2.6)
Name or path of a executable to invoke the script with
free_form
required
Path to the local script file followed by optional arguments. There is no parameter actually named 'free form'; see the examples!
removes
(added in 1.5)
a filename, when it does not exist, this step will not be run.

Notes

Note

  • It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
  • The ssh connection plugin will force pseudo-tty allocation via -tt when scripts are executed. pseudo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
  • This module is also supported for Windows targets.
  • If the path to the local script contains spaces, it needs to be quoted.

Examples

# Example from Ansible Playbooks
- script: /some/local/script.sh --some-arguments 1234

# Run a script that creates a file, but only if the file is not yet created
- script: /some/local/create_file.sh --some-arguments 1234
  args:
    creates: /the/created/file.txt

# Run a script that removes a file, but only if the file is not yet removed
- script: /some/local/remove_file.sh --some-arguments 1234
  args:
    removes: /the/removed/file.txt

# Run a script using a executable in a non-system path
- script: /some/local/script
  args:
    executable: /some/remote/executable

# Run a script using a executable in a system path
- script: /some/local/script.py
  args:
    executable: python3

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Ansible Core Team
  • Michael DeHaan

Hint

If you notice any issues in this documentation you can edit this document to improve it.