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.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', 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.

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.

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', timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=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.

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', timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

Execute the passed command and return a dict of return data

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.

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_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', quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=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

stdin : None

Standard input to be used for the command

New in version 2014.7.1.

output_loglevel : debug

Level at which to log the output from the command. Set to quiet to suppress logging.

New in version 2014.7.1.

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', timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

Execute a command and only return the standard error

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.

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', timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

Execute a command, and only return the standard out

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.

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', quiet=False, timeout=None, reset_system_locale=True, __env__=None, saltenv='base', 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. Arguments for the script can be specified as well.

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'

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 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, __env__=None, saltenv='base', output_loglevel='debug', 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

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', quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv='base', use_vt=False, **kwargs)

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

New in version 2015.5.0.

Warning

This passes the cmd argument directly to the shell 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.

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]'