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, password=None, depth=None, **kwargs)¶Execute the passed PowerShell command and return the output as a dictionary.
Other cmd.*
functions return the raw text output of the command. This
function appends | ConvertTo-JSON
to the command and then parses the
JSON into a Python dictionary. If you want the raw textual result of your
PowerShell command you should use cmd.run
with the shell=powershell
option.
For example:
salt '*' cmd.run '$PSVersionTable.CLRVersion' shell=powershell
salt '*' cmd.run 'Get-NetTCPConnection' shell=powershell
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 sanitized 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.
In addition to the normal cmd.run
parameters, this command offers the
depth
parameter to change the Windows default depth for the
ConvertTo-JSON
powershell command. The Windows default is 2. If you need
more depth, set that here.
Note
For some commands, setting the depth to a value greater than 4 greatly increases the time it takes for the command to return and in many cases returns useless data.
Parameters: |
|
||
---|---|---|---|
Returns: |
|
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, password=None, **kwargs)¶Execute a shell command and return the command's return code.
Parameters: |
|
---|
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, password=None, **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: |
|
---|
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, password=None, **kwargs)¶Execute the passed command and return a dict of return data
Parameters: |
|
---|
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.
Parameters: |
|
---|
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, ignore_retcode=False, saltenv='base', password=None, **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: |
|
---|
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
stdin
parameter. This can be useful in cases where sensitive
information must be read from standard input.: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
andFalse
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(':') }}
quiet
is used for this value.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, password=None, **kwargs)¶Execute a command and only return the standard error
Parameters: |
|
---|
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, password=None, **kwargs)¶Execute a command, and only return the standard out
Parameters: |
|
---|
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, __env__=None, saltenv='base', use_vt=False, bg=False, password=None, **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: |
|
---|
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, __env__=None, saltenv='base', output_loglevel='debug', log_callback=None, use_vt=False, password=None, **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: |
|
---|
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, password=None, **kwargs)¶Execute the passed command and return the output as a string.
New in version 2015.5.0.
Parameters: |
|
---|
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]'