salt.modules.cmdmod

A module for shelling out.

Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions.

salt.modules.cmdmod.exec_code(lang, code, cwd=None)

Pass in two strings, the first naming the executable language, aka - python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout will be returned.

CLI Example:

salt '*' cmd.exec_code ruby 'puts "cheese"'
salt.modules.cmdmod.exec_code_all(lang, code, cwd=None)

Pass in two strings, the first naming the executable language, aka - python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. All cmd artifacts (stdout, stderr, retcode, pid) will be returned.

CLI Example:

salt '*' cmd.exec_code_all ruby 'puts "cheese"'
salt.modules.cmdmod.has_exec(cmd)

Returns true if the executable is available on the minion, false otherwise

CLI Example:

salt '*' cmd.has_exec cat
salt.modules.cmdmod.powershell(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='debug', quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, encode_cmd=False, **kwargs)

Execute the passed PowerShell command and return the output as a string.

New in version 2016.3.0.

Warning

This passes the cmd argument directly to PowerShell without any further processing! Be absolutely sure that you have properly santized the command passed to this function and do not use untrusted inputs.

Note that env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

Parameters:
  • cmd (str) -- The powershell command to run.
  • cwd (str) -- The current working directory to execute the command in
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.
  • reset_system_locale (bool) -- Resets the system locale
  • ignore_retcode (bool) -- Ignore the return code
  • saltenv (str) -- The salt environment to use. Default is 'base'
  • encode_cmd (bool) -- Encode the command before executing. Use in cases where characters may be dropped or incorrectly converted when executed. Default is False.

CLI Example:

salt '*' cmd.powershell "$PSVersionTable.CLRVersion"
salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, umask=None, output_loglevel='debug', log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

Execute a shell command and return the command's return code.

Parameters:
  • cmd (str) -- The command to run. ex: 'ls -lart /home'
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

Note

env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

Return type:int
Return type:None
Returns:Return Code as an int or None if there was an exception.

CLI Example:

salt '*' cmd.retcode "file /bin/bash"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.retcode template=jinja "file {{grains.pythonpath[0]}}/python"

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.retcode "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.cmdmod.run(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='debug', log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, bg=False, encoded_cmd=False, **kwargs)

Execute the passed command and return the output as a string

Note that env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

Parameters:
  • cmd (str) -- The command to run. ex: ls -lart /home
  • cwd (str) -- The current working directory to execute the command in, defaults to /root (C:\ in windows)
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • bg (bool) -- If True, run command in background and do not await or deliver it's results
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.
  • encoded_cmd (bool) -- Specify if the supplied command is encoded. Only applies to shell 'powershell'.

Warning

This function does not process commands through a shell unless the python_shell flag is set to True. This means that any shell-specific functionality such as 'echo' or the use of pipes, redirection or &&, should either be migrated to cmd.shell or have the python_shell=True flag set here.

The use of python_shell=True means that the shell will accept _any_ input including potentially malicious commands such as 'good_command;rm -rf /'. Be absolutely certain that you have sanitized your input prior to using python_shell=True

CLI Example:

salt '*' cmd.run "ls -l | awk '/foo/{print \\$2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \\$2}'"

Specify an alternate shell with the shell parameter:

salt '*' cmd.run "Get-ChildItem C:\\ " shell='powershell'

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.run "grep f" stdin='one\\ntwo\\nthree\\nfour\\nfive\\n'

If an equal sign (=) appears in an argument to a Salt command it is interpreted as a keyword argument in the format key=val. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg:

salt '*' cmd.run cmd='sed -e s/=/:/g'
salt.modules.cmdmod.run_all(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='debug', log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, redirect_stderr=False, **kwargs)

Execute the passed command and return a dict of return data

Parameters:
  • cmd (str) -- The command to run. ex: 'ls -lart /home'
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

Note

env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

redirect_stderr
: False

If set to True, then stderr will be redirected to stdout. This is helpful for cases where obtaining both the retcode and output is desired, but it is not desired to have the output separated into both stdout and stderr.

New in version 2015.8.2.

CLI Example:

salt '*' cmd.run_all "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_all template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.run_all "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.cmdmod.run_bg(cmd, cwd=None, runas=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, umask=None, timeout=None, output_loglevel='debug', log_callback=None, reset_system_locale=True, saltenv='base', **kwargs)

Execute the passed command in the background and return it's PID

Note that env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

Parameters:
  • cmd (str) -- The command to run. ex: 'ls -lart /home'
  • cwd (str) -- The current working directory to execute the command in, defaults to /root (`C:` in windows)
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • umask (str) -- The umask (in octal) to use when running the command.
  • timeout (int) -- A timeout in seconds for the executed process to return.

Warning

This function does not process commands through a shell unless the python_shell flag is set to True. This means that any shell-specific functionality such as 'echo' or the use of pipes, redirection or &&, should either be migrated to cmd.shell or have the python_shell=True flag set here.

The use of python_shell=True means that the shell will accept _any_ input including potentially malicious commands such as 'good_command;rm -rf /'. Be absolutely certain that you have sanitized your input prior to using python_shell=True

CLI Example:

salt '*' cmd.run_bg "fstrim-all"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_bg template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \\$2}'"

Specify an alternate shell with the shell parameter:

salt '*' cmd.run_bg "Get-ChildItem C:\\ " shell='powershell'

If an equal sign (=) appears in an argument to a Salt command it is interpreted as a keyword argument in the format key=val. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg:

salt '*' cmd.run_bg cmd='ls -lR / | sed -e s/=/:/g > /tmp/dontwait'
salt.modules.cmdmod.run_chroot(root, cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='quiet', log_callback=None, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, bg=False, **kwargs)

New in version 2014.7.0.

This function runs cmd.run_all wrapped within a chroot, with dev and proc mounted in the chroot

root:
Path to the root of the jail to use.
cmd:
The command to run. ex: 'ls -lart /home'
cwd
The current working directory to execute the command in, defaults to /root
stdin
A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
runas
User to run script as.
shell
Shell to execute under. Defaults to the system default shell.
python_shell
If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
env

A list of environment variables to be set prior to execution. Example:

salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

Warning

The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

One can still use the existing $PATH by using a bit of Jinja:

{% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
clean_env:
Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
template
If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
rstrip
Strip all whitespace off the end of output before it is returned.
umask
The umask (in octal) to use when running the command.
output_loglevel
Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
timeout
A timeout in seconds for the executed process to return.
use_vt
Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

CLI Example:

salt '*' cmd.run_chroot /var/lib/lxc/container_name/rootfs 'sh /tmp/bootstrap.sh'
salt.modules.cmdmod.run_stderr(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='debug', log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

Execute a command and only return the standard error

Parameters:
  • cmd (str) -- The command to run. ex: 'ls -lart /home'
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

Note

env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

CLI Example:

salt '*' cmd.run_stderr "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_stderr template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.run_stderr "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='debug', log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

Execute a command, and only return the standard out

Parameters:
  • cmd (str) -- The command to run. ex: 'ls -lart /home'
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

Note

env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

CLI Example:

salt '*' cmd.run_stdout "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_stdout template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.run_stdout "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, template=None, umask=None, output_loglevel='debug', log_callback=None, quiet=False, timeout=None, reset_system_locale=True, saltenv='base', use_vt=False, bg=False, **kwargs)

Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an HTTP/FTP server.

The script will be executed directly, so it can be written in any available programming language.

Parameters:
  • source (str) -- The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs
  • args (str) -- String of command line args to pass to the script. Only used if no args are specified as part of the name argument. To pass a string containing spaces in YAML, you will need to doubly-quote it: "arg1 'arg two' arg3"
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • bg (bool) -- If True, run script in background and do not await or deliver it's results
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG)regardless, unless quiet is used for this value.
  • quiet (bool) -- The command will be executed quietly, meaning no log entries of the actual command or its return data. This is deprecated as of the 2014.1.0 release, and is being replaced with output_loglevel: quiet.
  • timeout (int) -- If the command has not terminated after timeout seconds, send the subprocess sigterm, and if sigterm is ignored, follow up with sigkill
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

CLI Example:

salt '*' cmd.script salt://scripts/runme.sh
salt '*' cmd.script salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
salt '*' cmd.script salt://scripts/windows_task.ps1 args=' -Input c:\tmp\infile.txt' shell='powershell'

salt '*' cmd.script salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.cmdmod.script_retcode(source, args=None, cwd=None, stdin=None, runas=None, shell='/bin/sh', python_shell=None, env=None, template='jinja', umask=None, timeout=None, reset_system_locale=True, saltenv='base', output_loglevel='debug', log_callback=None, use_vt=False, **kwargs)

Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an HTTP/FTP server.

The script will be executed directly, so it can be written in any available programming language.

The script can also be formatted as a template, the default is jinja.

Only evaluate the script return code and do not block for terminal output

Parameters:
  • source (str) -- The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs
  • args (str) -- String of command line args to pass to the script. Only used if no args are specified as part of the name argument. To pass a string containing spaces in YAML, you will need to doubly-quote it: "arg1 'arg two' arg3"
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (str) -- Shell to execute under. Defaults to the system default shell.
  • python_shell (bool) -- If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • quiet (bool) -- The command will be executed quietly, meaning no log entries of the actual command or its return data. This is deprecated as of the 2014.1.0 release, and is being replaced with output_loglevel: quiet.
  • timeout (int) -- If the command has not terminated after timeout seconds, send the subprocess sigterm, and if sigterm is ignored, follow up with sigkill
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

CLI Example:

salt '*' cmd.script_retcode salt://scripts/runme.sh
salt '*' cmd.script_retcode salt://scripts/runme.sh 'arg1 arg2 "arg 3"'
salt '*' cmd.script_retcode salt://scripts/windows_task.ps1 args=' -Input c:\tmp\infile.txt' shell='powershell'

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.script_retcode salt://scripts/runme.sh stdin='one\ntwo\nthree\nfour\nfive\n'
salt.modules.cmdmod.shell(cmd, cwd=None, stdin=None, runas=None, shell='/bin/sh', env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel='debug', log_callback=None, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, bg=False, **kwargs)

Execute the passed command and return the output as a string.

New in version 2015.5.0.

Parameters:
  • cmd (str) -- The command to run. ex: 'ls -lart /home'
  • cwd (str) -- The current working directory to execute the command in, defaults to /root
  • stdin (str) -- A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.
  • runas (str) -- User to run script as. If running on a Windows minion you must also pass a password
  • password (str) --

    Windows only. Pass a password if you specify runas. This parameter will be ignored for other OS's

    New in version 2016.3.0.

  • shell (int) -- Shell to execute under. Defaults to the system default shell.
  • bg (bool) -- If True, run command in background and do not await or deliver it's results
  • env (list) --

    A list of environment variables to be set prior to execution.

    Example:
    salt://scripts/foo.sh:
  cmd.script:
    - env:
      - BATCH: 'yes'

    Warning

    The above illustrates a common PyYAML pitfall, that yes, no, on, off, true, and false are all loaded as boolean True and False values, and must be enclosed in quotes to be used as strings. More info on this (and other) PyYAML idiosyncrasies can be found here.

    Variables as values are not evaluated. So $PATH in the following example is a literal '$PATH':

    salt://scripts/bar.sh:
  cmd.script:
    - env: "PATH=/some/path:$PATH"

    One can still use the existing $PATH by using a bit of Jinja:

    {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}

mycommand:
  cmd.run:
    - name: ls -l /
    - env:
      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
  • clean_env (bool) -- Attempt to clean out all other shell environment variables and set only those provided in the 'env' argument to this function.
  • template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported
  • rstrip (bool) -- Strip all whitespace off the end of output before it is returned.
  • umask (str) -- The umask (in octal) to use when running the command.
  • output_loglevel (str) -- Control the loglevel at which the output from the command is logged. Note that the command being run will still be logged (loglevel: DEBUG) regardless, unless quiet is used for this value.
  • timeout (int) -- A timeout in seconds for the executed process to return.
  • use_vt (bool) -- Use VT utils (saltstack) to stream the command output more interactively to the console and the logs. This is experimental.

Warning

This passes the cmd argument directly to the shell without any further processing! Be absolutely sure that you have properly sanitized the command passed to this function and do not use untrusted inputs.

Note

env represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict.

CLI Example:

salt '*' cmd.shell "ls -l | awk '/foo/{print \$2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.shell template=jinja "ls -l /tmp/{{grains.id}} | awk '/foo/{print \$2}'"

Specify an alternate shell with the shell parameter:

salt '*' cmd.shell "Get-ChildItem C:\ " shell='powershell'

A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.:

salt '*' cmd.shell "grep f" stdin='one\ntwo\nthree\nfour\nfive\n'

If an equal sign (=) appears in an argument to a Salt command it is interpreted as a keyword argument in the format key=val. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg:

salt '*' cmd.shell cmd='sed -e s/=/:/g'
salt.modules.cmdmod.shells()

Lists the valid shells on this system via the /etc/shells file

New in version 2015.5.0.

CLI Example:

salt '*' cmd.shells
salt.modules.cmdmod.tty(device, echo=None)

Echo a string to a specific tty

CLI Example:

salt '*' cmd.tty tty0 'This is a test'
salt '*' cmd.tty pts3 'This is a test'
salt.modules.cmdmod.which(cmd)

Returns the path of an executable available on the minion, None otherwise

CLI Example:

salt '*' cmd.which cat
salt.modules.cmdmod.which_bin(cmds)

Returns the first command found in a list of commands

CLI Example:

salt '*' cmd.which_bin '[pip2, pip, pip-python]'