Merge pull request #58 from rundeck-plugins/issue/54

avoid failure when script returns warning

README.md

@@ -24,13 +24,14 @@ For further information see:
 ## Configuration
 
 * **Authentication Type**: The authentication type used for the connection: basic, ntlm, credssp, kerberos. It can be overwriting at node level using `winrm-authtype`
-* **Username**: (Optional) Username that will connect to the remote node. This value can be set also at node level or as a job input option (with the name `username)
+* **Username**: (Optional) Username that will connect to the remote node. This value can be set also at node level or as a job input option (with the name `username`)
 * **Password Storage Path**: Key storage path of the window's user password. It can be overwriting at node level using `winrm-password-storage-path`. 
   Also the password can be overwritten on the job level using an input secure option called `winrmpassword`
 * **No SSL Verification**: When set to true SSL certificate validation is not performed.  It can be overwriting at node level using `winrm-nossl`
 * **WinRM Transport Protocol**: WinRM transport protocol (http or https). It can be overwriting at node level using `winrm-transport`
 * **WinRM Port**: WinRM port (Default: 5985/5986 for http/https). It can be overwriting at node level using `winrm-port`
 * **Shell**: Windows Shell interpreter (powershell o cmd).  It can be overwriting at node level using `winrm-shell`
+* **Script Exit Behaviour**: Script Exit Behaviour. console: if the std error console has data (default), the process fails. exitcode: script won't fail by default, the user must control the exit code (eg: using try/catch block). See https://github.com/rundeck-plugins/py-winrm-plugin/tree/master#running-scripts
 * **connect/read times out**: maximum seconds to wait before an HTTP connect/read times out (default 30). This value should be slightly higher than operation timeout, as the server can block *at least* that long.  
 It can be overwriting at node level using `winrm-readtimeout`
 * **operation timeout**: maximum allowed time in seconds for any single wsman HTTP operation (default 20). Note that operation timeouts while receiving output (the only wsman operation that should take any significant time, and where these timeouts are expected) will be silently retried indefinitely.
@@ -131,6 +132,43 @@ This plugin include a connectivity test script that can be used as a Workflow St
 python contents/winrm-check.py --username <username> --hostname <windows-server> --password <password>
 ```
 
+## Running Scripts
+
+From version 2.0.8, we added a config option to control the way a script finishes (about success/failure status)
+
+The option called `Script Exit Behaviour` defines the behavior of scripts step status.
+
+* **console**:  This is the default behavior and the way previous versions work. The script will fail if there are any logs in the error console (stderr).
+In some cases, a script can return a warning which will produce that the step fails.
+
+* **exitcode**:  This is the new approach. The script step will fail if the exit code is set manually.
+So if you need to control errors, you will need to find the way to capture the exit code of your commands inside the script, for example:
+
+* Option 1: check the last exit code
+```
+# some code with error
+get-services
+
+# if last exit code is not zero, return a value 
+if ($lastExitCode -ne "0") {
+    exit 1
+}
+
+```
+
+* Option 2: add a try/catch block
+
+```
+try {
+    # some code with error
+    get-services
+}
+catch {
+    Write-Error $_
+    exit 1
+}
+```
+
 ## Troubleshooting
 
 If you get the following error:

contents/winrm-exec.py

@@ -12,6 +12,17 @@
 import kerberosauth
 from colored_formatter import ColoredFormatter
 
+
+class SuppressFilter(logging.Filter):
+    def filter(self, record):
+        return 'wsman' not in record.getMessage()
+
+try:
+    from urllib3.connectionpool import log
+    log.addFilter(SuppressFilter())
+except:
+    pass
+
 #checking and importing dependencies
 ISPY3 = sys.version_info[0] == 3
 WINRM_INSTALLED = False
@@ -71,11 +82,10 @@
 except ImportError as e:
     HAS_PEXPECT = False
 
-log_level = 'INFO'
 if os.environ.get('RD_JOB_LOGLEVEL') == 'DEBUG':
     log_level = 'DEBUG'
 else:
-    log_level = 'ERROR'
+    log_level = 'INFO'
 
 ##end
 
@@ -104,6 +114,8 @@
 forceTicket = False
 readtimeout = None
 operationtimeout = None
+forcefail = False
+exitBehaviour = "console"
 
 if "RD_CONFIG_AUTHTYPE" in os.environ:
     authentication = os.getenv("RD_CONFIG_AUTHTYPE")
@@ -129,6 +141,9 @@
 if "RD_CONFIG_SHELL" in os.environ:
     shell = os.getenv("RD_CONFIG_SHELL")
 
+if "RD_CONFIG_EXITBEHAVIOUR" in os.environ:
+    exitBehaviour = os.getenv("RD_CONFIG_EXITBEHAVIOUR")
+
 if os.getenv("RD_JOB_LOGLEVEL") == "DEBUG":
     debug = True
 
@@ -186,6 +201,8 @@
 log.debug("shell:" + shell)
 log.debug("readtimeout:" + str(readtimeout))
 log.debug("operationtimeout:" + str(operationtimeout))
+log.debug("exit Behaviour:" + exitBehaviour)
+
 
 
 
@@ -282,9 +299,21 @@
 sys.stdout = realstdout
 sys.stderr = realstderr
 
-if tsk.e_std:
-    log.error("Execution finished with the following error")
-    log.error(tsk.e_std)
-    sys.exit(1)
+if exitBehaviour == 'console':
+    if tsk.e_std:
+        log.error("Execution finished with the following error")
+        log.error(tsk.e_std)
+        sys.exit(1)
+    else:
+        sys.exit(tsk.stat)
 else:
-    sys.exit(tsk.stat)
+    if tsk.stat != 0:
+        log.error("Execution finished with the following exit code: {} ".format(tsk.stat))
+        log.error(tsk.stat)
+        log.error(tsk.e_std)
+
+        sys.exit(tsk.stat)
+    else:
+        if tsk.e_std:
+            log.warning(tsk.e_std)
+        sys.exit(tsk.stat)

plugin.yaml

@@ -31,7 +31,7 @@ providers:
         scope: Instance
       - name: authtype
         title: Authentication Type
-        description: "Authentication Type"
+        description: "Authentication Type. It can be overwriting at node level using `winrm-authtype`"
         type: Select
         values: "basic,credssp,ntlm,kerberos"
         default: "basic"
@@ -42,7 +42,7 @@ providers:
           instance-scope-node-attribute: "winrm-authtype"
       - name: nossl
         title: No SSL Verification
-        description: "When set to true ssl certificate validation is not performed"
+        description: "When set to true ssl certificate validation is not performed. It can be overwriting at node level using `winrm-nossl`"
         type: Select
         values: "true, false"
         default: "false"
@@ -63,7 +63,7 @@ providers:
           instance-scope-node-attribute: "winrm-disable-tls-12"
       - name: winrmtransport
         title: WinRM Transport Protocol
-        description: "WinRM transport protocol (http or https)"
+        description: "WinRM transport protocol (http or https). It can be overwriting at node level using `winrm-transport`"
         type: Select
         default: "http"
         values: "http, https"
@@ -74,7 +74,7 @@ providers:
           instance-scope-node-attribute: "winrm-transport"
       - name: winrmport
         title: WinRM Port
-        description: "WinRM port (Default: 5985/5986 for http/https)"
+        description: "WinRM port (Default: 5985/5986 for http/https). It can be overwriting at node level using `winrm-port`"
         type: String
         default: "5985"
         required: true
@@ -84,7 +84,7 @@ providers:
           instance-scope-node-attribute: "winrm-port"
       - name: certpath
         title: Certificate Path
-        description: "Certificate path for ssl verification"
+        description: "Certificate path for ssl verification. It can be overwriting at node level using `winrm-certpath`"
         type: String
         required: false
         scope: Instance
@@ -93,7 +93,7 @@ providers:
           instance-scope-node-attribute: "winrm-certpath"
       - name: readtimeout
         title: connect/read times out
-        description: "maximum seconds to wait before an HTTP connect/read times out (default 30). This value should be slightly higher than operation timeout, as the server can block *at least* that long."
+        description: "maximum seconds to wait before an HTTP connect/read times out (default 30). This value should be slightly higher than operation timeout, as the server can block *at least* that long. It can be overwriting at node level using `winrm-readtimeout`"
         type: String
         required: false
         scope: Instance
@@ -102,7 +102,7 @@ providers:
           instance-scope-node-attribute: "winrm-readtimeout"
       - name: operationtimeout
         title: operation timeout
-        description: "maximum allowed time in seconds for any single wsman HTTP operation (default 20). Note that operation timeouts while receiving output (the only wsman operation that should take any significant time, and where these timeouts are expected) will be silently retried indefinitely."
+        description: "maximum allowed time in seconds for any single wsman HTTP operation (default 20). Note that operation timeouts while receiving output (the only wsman operation that should take any significant time, and where these timeouts are expected) will be silently retried indefinitely. It can be overwriting at node level using `winrm-operationtimeout`"
         type: String
         required: false
         scope: Instance
@@ -111,7 +111,7 @@ providers:
           instance-scope-node-attribute: "winrm-operationtimeout"
       - name: shell
         title: Shell
-        description: "Windows Shell interpreter"
+        description: "Windows Shell interpreter. It can be overwriting at node level using `winrm-shell`"
         type: Select
         values: "cmd, powershell"
         default: 'powershell'
@@ -120,6 +120,15 @@ providers:
         renderingOptions:
           groupName: Connection
           instance-scope-node-attribute: "winrm-shell"
+      - name: exitbehaviour
+        title: Script Exit Behaviour
+        description: "Script Exit Behaviour. console: if the std error console has data (default), the process fails. exitcode: script won't fail by default, the user must control the exit code (eg: using try/catch block). See https://github.com/rundeck-plugins/py-winrm-plugin/tree/master#running-scripts"
+        type: Select
+        values: "console, exitcode"
+        default: "console"
+        required: true
+        renderingOptions:
+          groupName: Connection
       - name: username
         title: Username
         type: String
@@ -132,7 +141,7 @@ providers:
         title: Password Storage Path
         type: String
         required: false
-        description: "Optional storage password path. Can contain property references to node attributes. A node attribute named winrm-password-storage-path will override this value."
+        description: "Optional storage password path. Can contain property references to node attributes. A node attribute named winrm-password-storage-path will override this value. Also, it can be set at job level using the option name `winrmpassword`"
         scope: Instance
         renderingOptions:
           groupName: Authentication
@@ -176,7 +185,7 @@ providers:
         title: Authentication Type
         description: "Authentication Type"
         type: Select
-        values: "basic,credssp,ntlm,kerberos"
+        values: "basic,credssp,ntlm,kerberos. It can be overwriting at node level using `winrm-authtype`"
         default: "basic"
         required: true
         scope: Instance
@@ -185,7 +194,7 @@ providers:
           instance-scope-node-attribute: "winrm-authtype"
       - name: nossl
         title: No SSL Verification
-        description: "When set to true ssl certificate validation is not performed"
+        description: "When set to true ssl certificate validation is not performed. It can be overwriting at node level using `winrm-nossl`"
         type: Select
         values: "true, false"
         default: "false"
@@ -206,7 +215,7 @@ providers:
           instance-scope-node-attribute: "winrm-disable-tls-12"
       - name: winrmtransport
         title: WinRM Transport Protocol
-        description: "WinRM transport protocol (Default: http or https when ssl is selected for Authentication type)"
+        description: "WinRM transport protocol (Default: http or https when ssl is selected for Authentication type). It can be overwriting at node level using `winrm-transport`"
         type: Select
         default: "http"
         values: "http, https"
@@ -217,7 +226,7 @@ providers:
           instance-scope-node-attribute: "winrm-transport"
       - name: winrmport
         title: WinRM Port
-        description: "WinRM port (Default: 5985/5986 for http/https)"
+        description: "WinRM port (Default: 5985/5986 for http/https). It can be overwriting at node level using `winrm-port`"
         type: String
         default: "5985"
         required: true
@@ -227,7 +236,7 @@ providers:
           instance-scope-node-attribute: "winrm-port"
       - name: certpath
         title: Certificate Path
-        description: "Certificate path for ssl verification"
+        description: "Certificate path for ssl verification. It can be overwriting at node level using `winrm-certpath`"
         type: String
         required: false
         scope: Instance
@@ -246,7 +255,7 @@ providers:
         title: Password Storage Path
         type: String
         required: false
-        description: "Optional storage password path. Can contain property references to node attributes. A node attribute named winrm-password-storage-path will override this value."
+        description: "Optional storage password path. Can contain property references to node attributes. A node attribute named winrm-password-storage-path will override this value. Also, it can be set at job level using the option name `winrmpassword`"
         scope: Instance
         renderingOptions:
           groupName: Authentication