Saltstack module cmd 详解

cmd.powershell

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.

:param str cmd: The powershell command to run.

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

:param str runas: Specify an alternate user to run the command. The default
behavior is to run as the user under which Salt is running. If running
on a Windows minion you must also use the password argument, and
the target user account must be in the Administrators group.

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.powershell 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

Note:
This should not need to be used in most cases. By default, Salt
will try to use the encoding detected from the system locale, and
will fall back to UTF-8 if this fails. This should only need to be
used in cases where the output of the command is encoded in
something other than the system locale or UTF-8.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool ignore_retcode: If the exit code of the command is nonzero,
this is treated as an error condition, and the output from the command
will be logged to the minion log. However, there are some cases where
programs use the return code for signaling and a nonzero exit code
doesn't necessarily mean failure. Pass this argument as True to
skip logging the output if the command has a nonzero exit code.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

:param bool reset_system_locale: Resets the system locale

:param str saltenv: The salt environment to use. Default is 'base'

:param int depth: The number of levels of contained objects to be included.
Default is 2. Values greater than 4 seem to greatly increase the time
it takes for the command to complete for some commands. eg: dir

New in version 2016.3.4

:param bool encode_cmd: Encode the command before executing. Use in cases
where characters may be dropped or incorrectly converted when executed.
Default is False.

:param list success_retcodes: This parameter will be allow a list of
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

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

:returns:
:dict: A dictionary of data returned by the powershell command.

CLI Example:

salt '*' cmd.powershell "$PSVersionTable.CLRVersion"

cmd.run

Execute the passed command and return the output as a string

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

:param str runas: Specify an alternate user to run the command. The default
behavior is to run as the user under which Salt is running.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
on linux while using run, to pass special characters to the
command you need to escape the characters on the shell.

Example:

cmd.run 'echo '''h="baz"'''' runas=macuser

:param str group: Group to run command as. Not currently supported
on Windows.

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param bool bg: If True, run command in background and do not await or
deliver it's results

New in version 2016.3.0

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.run 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
necessary) to $PATH

New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

:param bool encoded_cmd: Specify if the supplied command is encoded.
Only applies to shell 'powershell'.

:param bool raise_err: If True and the command has a nonzero exit code,
a CommandExecutionError exception will be raised.

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

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \\n
present in the stdin value to newlines.

New in version 2019.2.0

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'

cmd.run_chroot

New in version 2014.7.0

This function runs :mod:cmd.run_all <salt.modules.cmdmod.run_all> wrapped
within a chroot, with dev and proc mounted in the chroot

:param str root: Path to the root of the jail to use.

:param str 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.:

:param str runas: User to run script as.

:param str group: Group to run script as.

:param str shell: Shell to execute under. Defaults to the system
default shell.

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:parar str 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.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param list binds: List of directories that will be exported inside
the chroot with the bind option.

New in version 3000

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.run_chroot 'some command' env='{"FOO": "bar"}'

:param dict clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output
before it is returned.

:param str umask: The umask (in octal) to use when running the
command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout:
A timeout in seconds for the executed process to return.

:param bool use_vt:
Use VT utils (saltstack) to stream the command output more
interactively to the console and the logs. This is experimental.

success_retcodes: This parameter will be allow a list of
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'

cmd.script

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.

:param str source: 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

:param str args: 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:

salt myminion cmd.script salt://foo.sh "arg1 'arg two' arg3"

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

Note:

For Window's users, specifically Server users, it may be necessary
to specify your runas user using the User Logon Name instead of the
legacy logon name. Traditionally, logons would be in the following
format.

Domain/user

In the event this causes issues when executing scripts, use the UPN
format which looks like the following.

user@domain.local

More information https://github.com/saltstack/salt/issues/55080

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str group: Group to run script as. Not currently supported
on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param bool bg: If True, run script in background and do not await or
deliver it's results

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.script 'some command' env='{"FOO": "bar"}'

:param str 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.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: If the command has not terminated after timeout
seconds, send the subprocess sigterm, and if sigterm is ignored, follow
up with sigkill

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

cmd.script_retcode

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

:param str source: 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

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str group: Group to run script as. Not currently supported
on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.script_retcode 'some command' env='{"FOO": "bar"}'

:param str 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.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param int timeout: If the command has not terminated after timeout
seconds, send the subprocess sigterm, and if sigterm is ignored, follow
up with sigkill

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

cmd.run_stdout

Execute a command, and only return the standard out

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
to pass special characters to the command you need to escape
the characters on the shell.

Example:

cmd.run_stdout 'echo '''h="baz"'''' runas=macuser

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.run_stdout 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not necessary)
to $PATH

New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

cmd.shells

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

New in version 2015.5.0

CLI Example::

salt '*' cmd.shells

cmd.shell_info

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

Args:
shell (str): Name of the shell. Support shells/script languages include
bash, cmd, perl, php, powershell, python, ruby and zsh

list_modules (bool): True to list modules available to the shell.
Currently only lists powershell modules.

Returns:
dict: A dictionary of information about the shell

{'version': '<2 or 3 numeric components dot-separated>',
'version_raw': '',
'path': '',
'installed': <True, False or None>,
'': ''}

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.
- The shell must be within the executable search path.

CLI Example:

salt '' cmd.shell_info bash
salt '' cmd.shell_info powershell

:codeauthor: Damon Atkins https://github.com/damon-atkins

cmd.run_stderr

Execute a command and only return the standard error

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
to pass special characters to the command you need to escape
the characters on the shell.

Example:

cmd.run_stderr 'echo '''h="baz"'''' runas=macuser

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.run_stderr 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
necessary) to $PATH

New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

cmd.run_bg

.. versionadded: 2016.3.0

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.

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str group: Group to run command as. Not currently supported
on Windows.

:param str shell: Shell to execute under. Defaults to the system default
shell.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
to pass special characters to the command you need to escape
the characters on the shell.

Example:

cmd.run_bg 'echo '''h="baz"'''' runas=macuser

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.run_bg 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
necessary) to $PATH

New in version 2018.3.0

:param str 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.

:param str umask: The umask (in octal) to use when running the command.

:param int timeout: A timeout in seconds for the executed process to return.

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.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \\n
present in the stdin value to newlines.

New in version 2019.2.0

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'

salt '*' cmd.run_bg cmd='ls -lR / | sed -e s/=/:/g > /tmp/dontwait'

cmd.retcode

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

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
to pass special characters to the command you need to escape
the characters on the shell.

Example:

cmd.retcode 'echo '''h="baz"'''' runas=macuser

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.retcode 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param int timeout: A timeout in seconds for the executed process to return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

:rtype: int
:rtype: None
:returns: Return Code as an int or None if there was an exception.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

cmd.which

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

CLI Example:

salt '*' cmd.which cat

cmd.shell

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

New in version 2015.5.0

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
to pass special characters to the command you need to escape
the characters on the shell.

Example:

cmd.shell 'echo '''h="baz"'''' runas=macuser

:param str group: Group to run command as. Not currently supported
on Windows.

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param int shell: Shell to execute under. Defaults to the system default
shell.

:param bool bg: If True, run command in background and do not await or
deliver its results

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.shell 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not necessary)
to $PATH

New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
return.

:param bool use_vt: 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.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

salt '*' cmd.shell cmd='sed -e s/=/:/g'

cmd.which_bin

Returns the first command found in a list of commands

CLI Example:

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

cmd.exec_code

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 :mod:cmd.run_all <salt.modules.cmdmod.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"}'

cmd.powershell_all

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:

- If the value of the force_list parameter is True, then the
result field of the return dictionary will be an empty list.

- If the value of the 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:

- If the value of the force_list parameter is True, then the
result field will be a singleton list with the Python object as its
sole member.

- If the value of the 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

- no output when x is an empty directory.
- a dictionary object when x contains just one item.
- a list of dictionary objects when x contains multiple items.

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.

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.

:param str cmd: The powershell command to run.

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.powershell_all 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param int timeout: A timeout in seconds for the executed process to
return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

:param bool reset_system_locale: Resets the system locale

:param str saltenv: The salt environment to use. Default is 'base'

:param bool encode_cmd: Encode the command before executing. Use in cases
where characters may be dropped or incorrectly converted when executed.
Default is False.

:param bool force_list: The purpose of this parameter is described in the
preamble of this function's documentation. Default value is False.

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

:return: A dictionary with the following entries:

result
For a complete description of this field, please refer to this
function's preamble. This key will not be added to the dictionary
when force_list is False and Powershell's output is the empty
string.
stderr
What the PowerShell invocation wrote to stderr.
pid
The process id of the PowerShell invocation
retcode
This is the exit code of the invocation of PowerShell.
If the final execution status (in PowerShell) of our command
(with | ConvertTo-JSON appended) is False this should be non-0.
Likewise if PowerShell exited with $LASTEXITCODE set to some
non-0 value, then retcode will end up with this value.

:rtype: dict

CLI Example:

salt '*' cmd.powershell_all "$PSVersionTable.CLRVersion"

CLI Example:

salt '*' cmd.powershell_all "dir mydirectory" force_list=True

cmd.tty

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'

cmd.has_exec

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

CLI Example:

salt '*' cmd.has_exec cat

cmd.exec_code_all

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 :mod:cmd.run_all <salt.modules.cmdmod.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"}'

cmd.run_all

Execute the passed command and return a dict of return data

:param str cmd: The command to run. ex: ls -lart /home

:param str cwd: The directory from which to execute the command. Defaults
to the home directory of the user specified by runas (or the user
under which Salt is running if runas is not specified).

:param str 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.

Warning:

For versions 2018.3.3 and above on macosx while using runas,
to pass special characters to the command you need to escape
the characters on the shell.

Example:

cmd.run_all 'echo '''h="baz"'''' runas=macuser

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param str group: Group to run command as. Not currently supported
on Windows.

:param str shell: Specify an alternate shell. Defaults to the system's
default shell.

:param bool python_shell: If False, let python handle the positional
arguments. Set to True to use shell features, such as pipes or
redirection.

:param dict env: Environment variables to be set prior to execution.

Note:
When passing environment variables on the CLI, they should be
passed as the string representation of a dictionary.

salt myminion cmd.run_all 'some command' env='{"FOO": "bar"}'

:param bool clean_env: Attempt to clean out all other shell environment
variables and set only those provided in the 'env' argument to this
function.

:param str prepend_path: $PATH segment to prepend (trailing ':' not
necessary) to $PATH

New in version 2018.3.0

:param str 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.

:param bool rstrip: Strip all whitespace off the end of output before it is
returned.

:param str umask: The umask (in octal) to use when running the command.

:param str output_encoding: Control the encoding used to decode the
command's output.

To see the encoding Salt has detected from the system locale, check
the locale line in the output of :py:func:test.versions_report <salt.modules.test.versions_report>.

New in version 2018.3.0

:param str output_loglevel: Control the loglevel at which the output from
the command is logged to the minion log.

Note:
The command being run will still be logged at the debug
loglevel regardless, unless quiet is used for this value.

:param bool hide_output: If True, suppress stdout and stderr in the
return data.

Note:
This is separate from output_loglevel, which only handles how
Salt logs to the minion log.

New in version 2018.3.0

:param int timeout: A timeout in seconds for the executed process to
return.

:param bool use_vt: Use VT utils (saltstack) to stream the command output
more interactively to the console and the logs. This is experimental.

:param bool encoded_cmd: Specify if the supplied command is encoded.
Only applies to shell 'powershell'.

New in version 2018.3.0

:param bool redirect_stderr: 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

:param str password: Windows only. Required when specifying runas. This
parameter will be ignored on non-Windows platforms.

New in version 2016.3.0

:param bool bg: If True, run command in background and do not await or
deliver its results

New in version 2016.3.6

New in version 2019.2.0

:param bool stdin_raw_newlines: False
If True, Salt will not automatically convert the characters \n
present in the stdin value to newlines.

New in version 2019.2.0

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'

posted @ 2020-03-28 20:23 random_lee 阅读(405) 评论(0) 收藏举报

刷新页面返回顶部

random_lee

Saltstack module cmd 详解

cmd.powershell

cmd.run

cmd.run_chroot

cmd.script

cmd.script_retcode

cmd.run_stdout

cmd.shells

cmd.shell_info

cmd.run_stderr

cmd.run_bg

cmd.retcode

cmd.which

cmd.shell

cmd.which_bin

cmd.exec_code

cmd.powershell_all

cmd.tty

cmd.has_exec

cmd.exec_code_all

cmd.run_all

公告