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.
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.
All parameters from cmd.run_all
except python_shell can be used.
CLI Example:
salt '*' cmd.exec_code ruby 'puts "cheese"' salt '*' cmd.exec_code ruby 'puts "cheese"' args='["arg1", "arg2"]' env='{"FOO": "bar"}'
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.
All parameters from cmd.run_all
except python_shell can be used.
CLI Example:
salt '*' cmd.exec_code_all ruby 'puts "cheese"' salt '*' cmd.exec_code_all ruby 'puts "cheese"' args='["arg1", "arg2"]' env='{"FOO": "bar"}'
Returns true if the executable is available on the minion, false otherwise
CLI Example:
salt '*' cmd.has_exec cat
Execute the passed PowerShell command and return the output as a dictionary.
Other cmd.*
functions (besides cmd.powershell_all
) 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.
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"
Execute the passed PowerShell command and return a dictionary with a result field representing the output of the command, as well as other fields showing us what the PowerShell invocation wrote to stderr
, the process id, and the exit code of the invocation.
This function appends | ConvertTo-JSON
to the command before actually invoking powershell.
An unquoted empty string is not valid JSON, but it's very normal for the Powershell output to be exactly that. Therefore, we do not attempt to parse empty Powershell output (which would result in an exception). Instead we treat this as a special case and one of two things will happen:
force_list
parameter is True
, then the result
field of the return dictionary will be an empty list.force_list
parameter is False
, then the return dictionary will not have a result key added to it. We aren't setting result
to None
in this case, because None
is the Python representation of "null" in JSON. (We likewise can't use False
for the equivalent reason.)If Powershell's output is not an empty string and Python cannot parse its content, then a CommandExecutionError
exception will be raised.
If Powershell's output is not an empty string, Python is able to parse its content, and the type of the resulting Python object is other than list
then one of two things will happen:
force_list
parameter is True
, then the result
field will be a singleton list with the Python object as its sole member.force_list
parameter is False
, then the value of result
will be the unmodified Python object.If Powershell's output is not an empty string, Python is able to parse its content, and the type of the resulting Python object is list
, then the value of result
will be the unmodified Python object. The force_list
parameter has no effect in this case.
Note
An example of why the force_list
parameter is useful is as follows: The Powershell command dir x | Convert-ToJson
results in
By setting force_list
to True
we will always end up with a list of dictionary items, representing files, no matter how many files x contains. Conversely, if force_list
is False
, we will end up with no result
key in our return dictionary when x is an empty directory, and a dictionary object when x contains just one file.
If you want a similar function but with a raw textual result instead of a Python dictionary, you should use cmd.run_all
in combination with shell=powershell
.
The remaining fields in the return dictionary are described in more detail in the Returns
section.
Example:
salt '*' cmd.run_all '$PSVersionTable.CLRVersion' shell=powershell salt '*' cmd.run_all 'Get-NetTCPConnection' shell=powershell
New in version 2018.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.
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: |
A dictionary with the following entries:
|
Return type: |
CLI Example:
salt '*' cmd.powershell_all "$PSVersionTable.CLRVersion"
CLI Example:
salt '*' cmd.powershell_all "dir mydirectory" force_list=True
Execute a shell command and return the command's return code.
Parameters: |
|
---|---|
Return type: | |
Return type: | |
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'
Execute the passed command and return the output as a string
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
Parameters: |
|
---|
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'
Execute the passed command and return a dict of return data
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'
Execute the passed command in the background and return it's PID
Note
If the init system is systemd and the backgrounded task should run even if the salt-minion process is restarted, prepend systemd-run
--scope
to the command. This will reparent the process in its own scope separate from salt-minion, and will not be affected by restarting the minion service.
Parameters: |
|
---|
Warning
This function does not process commands through a shell unless the python_shell
argument 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
.
Parameters: |
|
---|
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'
New in version 2014.7.0.
This function runs cmd.run_all
wrapped within a chroot, with dev and proc mounted in the chroot
Parameters: | root (str) -- Path to the root of the jail to use. |
---|
stdin
parameter. This can be useful in cases where sensitive information must be read from standard input.:Parameters: |
|
---|---|
Parar str stdin: | |
A string of standard input can be specified for the command to be run using the |
non-zero return codes that should be considered a success. If the return code returned from the run matches any in the provided list, the return code will be overridden with zero.
New in version 2019.2.0.
CLI Example:
salt '*' cmd.run_chroot /var/lib/lxc/container_name/rootfs 'sh /tmp/bootstrap.sh'
Execute a command and only return the standard error
Parameters: |
|
---|
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'
Execute a command, and only return the standard out
Parameters: |
|
---|
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'
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'
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'
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.
Parameters: |
|
---|
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'
New in version 2016.11.0.
Provides information about a shell or script languages which often use #!
. The values returned are dependent on the shell or scripting languages all return the installed
, path
, version
, version_raw
Parameters: | |
---|---|
Returns: |
A dictionary of information about the shell |
Return type: |
{'version': '<2 or 3 numeric components dot-separated>', 'version_raw': '<full version string>', 'path': '<full path to binary>', 'installed': <True, False or None>, '<attribute>': '<attribute value>'}
Note
installed
is always returned, if None
or False
also returns error and may also return stdout
for diagnostics.version
is for use in determine if a shell/script language has a particular feature set, not for package management.CLI Example:
salt '*' cmd.shell_info bash salt '*' cmd.shell_info powershell
Codeauthor: | Damon Atkins <https://github.com/damon-atkins> |
---|
Lists the valid shells on this system via the /etc/shells file
New in version 2015.5.0.
CLI Example:
salt '*' cmd.shells
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'
Returns the path of an executable available on the minion, None otherwise
CLI Example:
salt '*' cmd.which cat
Returns the first command found in a list of commands
CLI Example:
salt '*' cmd.which_bin '[pip2, pip, pip-python]'
© 2019 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.cmdmod.html