# 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, args=None, **kwargs)

  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"}'

salt.modules.cmdmod.exec_code_all(lang, code, cwd=None, args=None, **kwargs)

  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"}'

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='powershell', env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, depth=None, encode_cmd=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  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

  Added 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:

    - cmd (str) -- The powershell command to run.

    - cwd (str) -- 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).

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

    - runas (str) -- 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.

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - shell (str) -- Specify an alternate shell. Defaults to "powershell". Can also use "pwsh" for powershell core if present on the system

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - reset_system_locale (bool) -- Resets the system locale

    - saltenv (str) -- The salt environment to use. Default is 'base'

    - depth (int) --

      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`

      Added in version 2016.3.4.

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

      Added in version 2019.2.0.

  Returns:

    dict:

      A dictionary of data returned by the powershell command.

  CLI Example:

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

salt.modules.cmdmod.powershell_all(cmd, cwd=None, stdin=None, runas=None, shell='powershell', env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, depth=None, encode_cmd=False, force_list=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  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

  Added 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:

    - cmd (str) -- The powershell command to run.

    - cwd (str) -- 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).

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

    - runas (str) -- 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.

    - password (str) -- Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

    - shell (str) -- Specify an alternate shell. Defaults to "powershell". Can also use "pwsh" for powershell core if present on the system

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - reset_system_locale (bool) -- Resets the system locale

    - ignore_retcode -- 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.

    - saltenv (str) -- The salt environment to use. Default is 'base'

    - depth (int) -- 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`

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

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

      Added in version 2019.2.0.

  Returns:

    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.

  Return type:

    dict

  CLI Example:

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

  CLI Example:

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

salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, group=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

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

  Parameters:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- The 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).

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

    - runas (str) --

      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.

      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

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

      Added in version 2019.2.0.

  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, group=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, redirect_stderr=True, bg=False, password=None, encoded_cmd=False, raise_err=False, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  Execute the passed command and return the output as a string

  Parameters:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- 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).

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

    - runas (str) --

      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

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

    - python_shell (bool) -- If `False`, let python handle the positional arguments. Set to `True` to use shell features, such as pipes or redirection.

    - bg (bool) --

      If `True`, run command in background and do not await or deliver its results

      Added in version 2016.3.0.

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - prepend_path (str) --

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

      Added in version 2018.3.0.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - redirect_stderr (bool) --

      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. Default is `True`

      Added in version 3006.9.

    - encoded_cmd (bool) --

      Specify if the supplied command is encoded. Only applies to shell 'powershell' and 'pwsh'.

      Added in version 2018.3.0.

      Older versions of powershell seem to return raw xml data in the return. To avoid raw xml data in the return, prepend your command with the following before encoding:

      $ProgressPreference='SilentlyContinue'; <your command>

      The following powershell code block will encode the Write-Output command so that it will not have the raw xml data in the return:

          # target string
          $Command = '$ProgressPreference="SilentlyContinue"; Write-Output "hello"'

          # Convert to Base64 encoded string
          $Encoded = [convert]::ToBase64String([System.Text.encoding]::Unicode.GetBytes($command))

          Write-Output $Encoded

    - raise_err (bool) -- 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

  Parameters:

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\\n` present in the `stdin` value to newlines.

      Added in version 2019.2.0.

    - windows_codepage (int) --

      65001

        Only applies to Windows: the minion uses C:WindowsSystem32chcp.com to verify or set the code page before the command cmd is executed. Code page 65001 corresponds with UTF-8 and allows international localization of Windows.

      Added in version 3002.

  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, group=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, redirect_stderr=False, password=None, encoded_cmd=False, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  Execute the passed command and return a dict of return data

  Parameters:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- The 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).

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

    - runas (str) --

      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.

      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

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - prepend_path (str) --

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

      Added in version 2018.3.0.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - encoded_cmd (bool) --

      Specify if the supplied command is encoded. Only applies to shell 'powershell' and 'pwsh'.

      Added in version 2018.3.0.

      Older versions of powershell seem to return raw xml data in the return. To avoid raw xml data in the return, prepend your command with the following before encoding:

      $ProgressPreference='SilentlyContinue'; <your command>

      The following powershell code block will encode the Write-Output command so that it will not have the raw xml data in the return:

          # target string
          $Command = '$ProgressPreference="SilentlyContinue"; Write-Output "hello"'

          # Convert to Base64 encoded string
          $Encoded = [convert]::ToBase64String([System.Text.encoding]::Unicode.GetBytes($command))

          Write-Output $Encoded

    - redirect_stderr (bool) --

      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.

      Added in version 2015.8.2.

    - password --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      > Added in version 2016.3.0.

    - bg (bool) --

      If `True`, run command in background and do not await or deliver its results

      Added in version 2016.3.6.

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

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

salt.modules.cmdmod.run_bg(cmd, cwd=None, runas=None, group=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, umask=None, timeout=None, output_encoding=None, output_loglevel='debug', log_callback=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  Added in version 2016.3.0.

  Execute the passed command in the background and return its 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:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- 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).

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - shell (str) -- Shell to execute under. Defaults to the system default shell.

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - runas (str) --

      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.

      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

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - shell -- Specify an alternate shell. Defaults to the system's default shell.

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - prepend_path (str) --

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

      Added in version 2018.3.0.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

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

    - timeout (int) -- A timeout in seconds for the executed process to return.

  Warning

  This function does not process commands through a shell unless the `python_shell` 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:

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\\n` present in the `stdin` value to newlines.

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

  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, group=None, shell='/bin/sh', python_shell=True, binds=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='quiet', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, bg=False, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  Added 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 (str) -- A string of standard input can be specified for the command to be run using the `stdin` parameter. This can be useful in cases where sensitive information must be read from standard input.:

    - runas (str) -- User to run script as.

    - group (str) -- Group to run script as.

    - shell (str) -- Shell to execute under. Defaults to the system default shell.

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- 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).

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

    - shell -- Specify an alternate shell. Defaults to the system's default shell.

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

    - binds (list) --

      List of directories that will be exported inside the chroot with the bind option.

      Added in version 3000.

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - success_retcodes --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

  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.

  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, group=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  Execute a command and only return the standard error

  Parameters:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- 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).

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

    - runas (str) --

      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.

      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

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - prepend_path (str) --

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

      Added in version 2018.3.0.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

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

salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, group=None, shell='/bin/sh', python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

  Execute a command, and only return the standard out

  Parameters:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- 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).

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

    - runas (str) --

      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.

      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

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - prepend_path (str) --

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

      Added in version 2018.3.0.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

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

salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, group=None, shell='/bin/sh', python_shell=None, env=None, template=None, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, saltenv=None, use_vt=False, bg=False, password=None, success_retcodes=None, success_stdout=None, success_stderr=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:

    - source (str) -- The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs

    - args (str) --

      String of command line args to pass to the script. Only used if no args are specified as part of the name argument. To pass a string containing spaces in YAML, you will need to doubly-quote it:

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

    - cwd (str) -- The directory from which to execute the command. Defaults to the directory returned from Python's tempfile.mkstemp.

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

    - runas (str) --

      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.

      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>

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - group (str) -- Group to run script as. Not currently supported on Windows.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

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

    - bg (bool) -- If True, run script in background and do not await or deliver its results

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

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

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

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

salt.modules.cmdmod.script_retcode(source, args=None, cwd=None, stdin=None, runas=None, group=None, shell='/bin/sh', python_shell=None, env=None, template='jinja', umask=None, timeout=None, reset_system_locale=True, saltenv=None, output_encoding=None, output_loglevel='debug', log_callback=None, use_vt=False, password=None, success_retcodes=None, success_stdout=None, success_stderr=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:

    - source (str) -- The location of the script to download. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs

    - args (str) -- String of command line args to pass to the script. Only used if no args are specified as part of the name argument. To pass a string containing spaces in YAML, you will need to doubly-quote it: "arg1 'arg two' arg3"

    - cwd (str) -- The 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).

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

    - runas (str) -- 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.

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - group (str) -- Group to run script as. Not currently supported on Windows.

    - shell (str) -- Specify an alternate shell. Defaults to the system's default shell.

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

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

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

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

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

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

salt.modules.cmdmod.shell(cmd, cwd=None, stdin=None, runas=None, group=None, shell='/bin/sh', env=None, clean_env=False, template=None, rstrip=True, umask=None, output_encoding=None, output_loglevel='debug', log_callback=None, hide_output=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=None, use_vt=False, bg=False, password=None, prepend_path=None, success_retcodes=None, success_stdout=None, success_stderr=None, **kwargs)

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

  Added in version 2015.5.0.

  Parameters:

    - cmd (str) -- The command to run. ex: `ls -lart /home`

    - cwd (str) -- 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).

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

    - runas (str) --

      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.

      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

    - group (str) -- Group to run command as. Not currently supported on Windows.

    - password (str) --

      Windows only. Required when specifying `runas`. This parameter will be ignored on non-Windows platforms.

      Added in version 2016.3.0.

    - shell (int) -- Shell to execute under. Defaults to the system default shell.

    - bg (bool) -- If True, run command in background and do not await or deliver its results

    - env (dict) --

      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"}'

      Note

      When using environment variables on Window's, case-sensitivity matters, i.e. Window's uses Path as opposed to PATH for other systems.

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

    - prepend_path (str) --

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

      Added in version 2018.3.0.

    - template (str) -- If this setting is applied then the named templating engine will be used to render the downloaded file. Currently jinja, mako, and wempy are supported.

    - rstrip (bool) -- Strip all whitespace off the end of output before it is returned.

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

    - output_encoding (str) --

      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 `test.versions_report`.

      Added in version 2018.3.0.

    - output_loglevel (str) --

      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.

    - ignore_retcode (bool) -- 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.

    - hide_output (bool) --

      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.

      Added in version 2018.3.0.

    - timeout (int) -- A timeout in seconds for the executed process to return.

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

  Warning

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

  Parameters:

    - success_retcodes (list) --

      This parameter will 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.

      Added in version 2019.2.0.

    - success_stdout (list) --

      This parameter will allow a list of

        strings that when found in standard out should be considered a success. If stdout returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - success_stderr (list) --

      This parameter will allow a list of

        strings that when found in standard error should be considered a success. If stderr returned from the run matches any in the provided list, the return code will be overridden with zero.

      Added in version 3004.

    - stdin_raw_newlines (bool) --

      False

        If `True`, Salt will not automatically convert the characters `\n` present in the `stdin` value to newlines.

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

  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.shell_info(shell, list_modules=False)

  Added 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:

    - shell (str) -- Name of the shell. Support shells/script languages include

    - bash

    - cmd

    - perl

    - php

    - powershell

    - python

    - zsh (ruby and)

    - list_modules (bool) -- True to list modules available to the shell.

    - modules. (Currently only lists powershell)

  Returns:

    A dictionary of information about the shell

  Return type:

    dict

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

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

salt.modules.cmdmod.shells()

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

  Added in version 2015.5.0.

  CLI Example:

      salt '*' cmd.shells

salt.modules.cmdmod.tty(device, echo='')

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