Merge pull request #673 from StackStorm/sudo_password_docs

Documentation for new sudo_password runner parameter

Author: Kami

docs/source/_includes/runner_parameters/local_shell_cmd.rst

@@ -2,7 +2,8 @@
 
 * ``kwarg_op`` (string) - Operator to use in front of keyword args i.e. "--" or "-".
 * ``cmd`` (string) - Arbitrary Linux command to be executed on the host.
-* ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.
+* ``sudo_password`` (string) - Sudo password. To be used when paswordless sudo is not allowed.
 * ``env`` (object) - Environment variables which will be available to the command(e.g. key1=val1,key2=val2)
+* ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.
 * ``sudo`` (boolean) - The command will be executed with sudo.
 * ``cwd`` (string) - Working directory where the command will be executed in

docs/source/_includes/runner_parameters/local_shell_script.rst

@@ -1,7 +1,8 @@
 .. NOTE: This file has been generated automatically, don't manually edit it
 
 * ``kwarg_op`` (string) - Operator to use in front of keyword args i.e. "--" or "-".
-* ``sudo`` (boolean) - The command will be executed with sudo.
-* ``cwd`` (string) - Working directory where the script will be executed in
+* ``sudo_password`` (string) - Sudo password. To be used when paswordless sudo is not allowed.
 * ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.
-* ``env`` (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
+* ``env`` (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
+* ``sudo`` (boolean) - The command will be executed with sudo.
+* ``cwd`` (string) - Working directory where the script will be executed in

docs/source/_includes/runner_parameters/python_script.rst

@@ -1,4 +1,5 @@
 .. NOTE: This file has been generated automatically, don't manually edit it
 
+* ``log_level`` (string) - Default log level for Python runner actions.
 * ``env`` (object) - Environment variables which will be available to the script.
 * ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.

docs/source/_includes/runner_parameters/remote_shell_cmd.rst

@@ -2,16 +2,17 @@
 
 * ``username`` (string) - Username used to log-in. If not provided, default username from config is used.
 * ``private_key`` (string) - Private key material or path to the private key file on disk used to log in.
-* ``cmd`` (string) - Arbitrary Linux command to be executed on the remote host(s).
-* ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.
+* ``sudo_password`` (string) - Sudo password. To be used when paswordless sudo is not allowed.
 * ``env`` (object) - Environment variables which will be available to the command(e.g. key1=val1,key2=val2)
 * ``sudo`` (boolean) - The remote command will be executed with sudo.
-* ``cwd`` (string) - Working directory where the script will be executed in
 * ``kwarg_op`` (string) - Operator to use in front of keyword args i.e. "--" or "-".
 * ``bastion_host`` (string) - The host SSH connections will be proxied through. Note: This connection is made using the same parameters as the final connection, and is only used in ParamikoSSHRunner.
-* ``hosts`` (string) - A comma delimited string of a list of hosts where the remote command will be executed.
 * ``passphrase`` (string) - Passphrase for the private key, if needed.
-* ``parallel`` (boolean) - Default to parallel execution.
 * ``password`` (string) - Password used to log in. If not provided, private key from the config file is used.
 * ``port`` (integer) - SSH port. Note: This parameter is used only in ParamikoSSHRunner.
+* ``cmd`` (string) - Arbitrary Linux command to be executed on the remote host(s).
+* ``parallel`` (boolean) - Default to parallel execution.
+* ``hosts`` (string) - A comma delimited string of a list of hosts where the remote command will be executed.
+* ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.
+* ``cwd`` (string) - Working directory where the script will be executed in
 * ``dir`` (string) - The working directory where the script will be copied to on the remote host.

docs/source/_includes/runner_parameters/remote_shell_script.rst

@@ -2,6 +2,7 @@
 
 * ``username`` (string) - Username used to log-in. If not provided, default username from config is used.
 * ``private_key`` (string) - Private key material to log in. Note: This needs to be actual private key data and NOT path.
+* ``sudo_password`` (string) - Sudo password. To be used when paswordless sudo is not allowed.
 * ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.
 * ``env`` (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
 * ``sudo`` (boolean) - The remote command will be executed with sudo.

docs/source/reference/runners.rst

@@ -52,6 +52,16 @@ This is a remote runner. This runner executes a Linux command on one or more rem
 by the user. The last newline character is stripped from ``stdout`` and ``stderr`` fields in the
 output.
 
+.. note::
+
+   By default |st2| uses paswordless sudo for system user which is used to execute commands on
+   local and remote systems. In addition to paswordless sudo, local and remote runners also support
+   password protected sudo via ``sudo_password`` runner parameter. With the remote runner, sudo
+   password is passed to the sudo command as a command line argument which means it has some
+   security implications - if bash history is enabled for the system user under which |st2|
+   remote commands run, this command which includes sudo password will be saved in bash history
+   and any system user which access to that user bash history file will be able to view it.
+
 Runner Parameters
 ^^^^^^^^^^^^^^^^^