ansible/library/raw

# this is a virtual module that is entirely implemented server side

DOCUMENTATION = '''
---
module: raw
short_description: Executes a low-down and dirty SSH command
options:
  free_form:
    description:
      - the raw module takes a free form command to run
    required: true
  executable:
    description:
      - change the shell used to execute the command. Should be an absolute path to the executable.
    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 two cases. The
       first case is installing C(python-simplejson) on older (Python 2.4 and
       before) hosts that need it as a dependency to run modules, since nearly
       all core modules require it. 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 M(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.
examples:
    - description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host
      code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson"
author: Michael DeHaan
'''
Setup module no longer saves to disk, as templates are mostly useful in playbooks and this allows lots of simplifications around file pathing and removes occasional permissions conflicts depending on how things are used. 2012-07-14 17:59:12 +02:00			`# this is a virtual module that is entirely implemented server side`
First attempt at standardizing DOCUMENTATION string (new DICT) 2012-09-17 15:11:04 +02:00
			`DOCUMENTATION = '''`
			`---`
			`module: raw`
Tweak DOCUMENTATION YAML as per latest 991 2012-09-19 16:09:26 +02:00			`short_description: Executes a low-down and dirty SSH command`
Allow to change executable (shell/interpreter) when using raw This patch adds an optional 'executable=' option to the raw command line to override the default shell (/bin/sh), much like the shell module does. 2012-12-23 19:17:07 +01:00			`options:`
			`free_form:`
			`description:`
			`- the raw module takes a free form command to run`
			`required: true`
			`executable:`
			`description:`
			`- change the shell used to execute the command. Should be an absolute path to the executable.`
			`required: false`
			`version_added: "1.0"`
Tweak DOCUMENTATION YAML as per latest 991 2012-09-19 16:09:26 +02:00			`description:`
			`- Executes a low-down and dirty SSH command, not going through the module`
			`subsystem. This is useful and should only be done in two cases. The`
DOCUMENTATION strings 2012-11-21 18:49:30 +01:00			`first case is installing C(python-simplejson) on older (Python 2.4 and`
Tweak DOCUMENTATION YAML as per latest 991 2012-09-19 16:09:26 +02:00			`before) hosts that need it as a dependency to run modules, since nearly`
			`all core modules require it. 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`
Add return code and error output to raw module Since we use 'raw' heavily on equipment where 'command' and 'shell' are not (yet) working (and python may need to be installed first using raw) these improvements are necessary in order to write more complex scripts (with return code handling and separated stdout/stderr). This change includes the following changes: - exec_command() now returns the return code of the command - _low_level_exec_command() now returns a dict, including 'rc', 'stdout' and 'stderr' - all users of the above interfaces have been improved to make use of the above changes - all connection plugins have been modified to return rc and stderr - fix the newline problem (stdout and stderr would have excess newlines) In a future commit I intend to add assertions or error handling code to verify the return code in those places where it wasn't done. Since only the output was available, the return code was ignored, even though we expect them to be 0. 2012-12-23 01:44:00 +01:00			`given to M(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.`
First attempt at standardizing DOCUMENTATION string (new DICT) 2012-09-17 15:11:04 +02:00			`examples:`
Add return code and error output to raw module Since we use 'raw' heavily on equipment where 'command' and 'shell' are not (yet) working (and python may need to be installed first using raw) these improvements are necessary in order to write more complex scripts (with return code handling and separated stdout/stderr). This change includes the following changes: - exec_command() now returns the return code of the command - _low_level_exec_command() now returns a dict, including 'rc', 'stdout' and 'stderr' - all users of the above interfaces have been improved to make use of the above changes - all connection plugins have been modified to return rc and stderr - fix the newline problem (stdout and stderr would have excess newlines) In a future commit I intend to add assertions or error handling code to verify the return code in those places where it wasn't done. Since only the output was available, the return code was ignored, even though we expect them to be 0. 2012-12-23 01:44:00 +01:00			`- description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host`
			`code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson"`
Added attribution to all module DOCUMENTATION strings 2012-10-01 12:37:51 +02:00			`author: Michael DeHaan`
First attempt at standardizing DOCUMENTATION string (new DICT) 2012-09-17 15:11:04 +02:00			`'''`