Rundeck Python-Winrm Plugin

This is a Rundeck Node Execution/ File Copier plugin that uses WinRM to connect to Windows and execute commands and scripts. It uses the python WinRM Library to provide the WinRM implementation.

Install

Download from the releases page and copy the py-winrm-plugin-X.X.X.zip to the libext/ directory for Rundeck.

Requirements

• Linux, Mac OS X or Windows
• CPython 3.8+ or PyPy3
• pywinrm
• openssl 1.1.1 or higher
• requests-kerberos and requests-credssp is optional

It can be installed with the following command: pip install pywinrm

For further information see: Python Winrm Requirements

• To install requests-kerberos See
• To install requests-credssp See

On distributions that mark the system Python as externally managed (for example Ubuntu 24.04+), either install pywinrm with the OS package manager or point the plugin at a virtualenv interpreter that already has pywinrm installed. See Python interpreter.

Python interpreter

The plugin runs on the Rundeck server or Enterprise Runner, not on the Windows node. Python Interpreter is a free-text command or path (default: python3). Use a command on PATH such as python3, or a full path such as /opt/winrm-venv/bin/python3.

It can be overwritten at node level using winrm-interpreter. That is useful when some runners or hosts need a different Python than the project default.

Configuration

• Python Interpreter: Python command or full path used to run the plugin (default: python3). It can be overwritten at node level using winrm-interpreter. See Python interpreter.
• Authentication Type: The authentication type used for the connection: basic, ntlm, credssp, kerberos. It can be overwritten 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)
• Password Storage Path: Key storage path of the window's user password. It can be overwritten 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 overwritten at node level using winrm-nossl
• Disable TLS 1.2: Disable TLS 1.2 in order to run over TLS 1.0. It can be overwritten at node level using winrm-disable-tls-12
• WinRM Transport Protocol: WinRM transport protocol (http or https). It can be overwritten at node level using winrm-transport
• WinRM Port: WinRM port (Default: 5985/5986 for http/https). It can be overwritten at node level using winrm-port
• Certificate Path: Filesystem path to a PEM certificate used for SSL verification (not a Key Storage path). It can be overwritten at node level using winrm-certpath
• Shell: Windows Shell interpreter (powershell or cmd). It can be overwritten 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 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 overwritten 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. It can be overwritten at node level using winrm-operationtimeout
• Proxy: Proxy address for communicating with Windows nodes. Example HTTP proxy strings are http://server:port and http://user:pass@server:port. An example SOCKS5 proxy string is socks5://user:pass@server:port. It can be overwritten at node level using winrm-proxy
• No Proxy List: Comma-separated list of hosts, IPs, or CIDRs that bypass the proxy. Supports exact IPs, CIDR notation (192.168.1.0/24), domain suffixes (.internal.corp), hostnames, and wildcard (*). Requires Proxy to also be set. It can be overwritten at node level using winrm-noproxy
• retry connection: Retry a connection when it fails for connectivity issues (default 1).
  It can be overwritten at node level using winrm-retry-connection
• retry connection delay: Delay between retries in seconds (default 10 seconds). It can be overwritten at node level using winrm-retry-connection-delay
• Terminate On Abort: When enabled, aborting a job terminates the remote command and its whole process tree on the Windows node. Disabled by default (legacy behaviour). It can be overwritten at node level using winrm-terminate-on-abort. See Aborting jobs.
• Enable HTTP logging in debug mode: Print extra HTTP logging when job log level is DEBUG. It can be overwritten at node level using winrm-enable-http-logging
• Clean Escaping: Cleans unnecessarily escaped characters on commands. It can be overwritten at node level using clean-escaping

For Kerberos

• krb5 Config File: path of the krb5.conf (default: /etc/krb5.conf)
• Kinit Command: kinit command used for create ticket (default: kinit)
• Kerberos Delegation: if true, the TGT is sent to the target server to allow multiple hops (default: false)

Node definition example

<node name="Hostname" 
      description="Windows Server" 
      tags="windows" 
      hostname="192.168.0.1" 
      osArch="amd64" 
      osFamily="windows" 
      osName="Windows Server 2012 R2" 
      osVersion="6.3" 
      username="rundeckuser@domain.local" 
      winrm-password-storage-path="keys/node/windows.password"
      winrm-authtype="basic"/>

The username can be overwritten using a job input option called username or it can be set at project level.

Optional node attributes that override project settings include winrm-interpreter, winrm-nossl, winrm-transport, winrm-port, winrm-proxy, winrm-noproxy, winrm-terminate-on-abort, and codepage. See Configuration and Windows code page.

Transport methods

The transport methods supported are:

• basic
• kerberos
• ntlm
• credssp

Further information here

CredSSP

To use CredSSP authentication you need these optional dependencies

pip install pywinrm[credssp]

Kerberos

The pywinrm library has support for kerberos authentication, but it cannot create the kerberos ticket, which needs to be initiate outside the pywinrm scope:

kerberos: Will use Kerberos authentication for domain accounts which only works when the client is in the same domain as the server and the required dependencies are installed. Currently a Kerberos ticket needs to be initialized outside of pywinrm using the kinit command.

Source here

So, in order to connect to a windows box using kerberos we added a call to the kinit username command before connecting to the node.

In resume, to use Kerberos authentication the following requirements are needed:

• domain accounts which only works when the client is in the same domain as the server
• kerberos client installed
• domain set on krb5.conf file (default /etc/krb5.conf)
• python pexpect library
• python kerberos library
• Kerberos authentication enabled on remote windows node (WINRM settings)

Install Basic dependencies

for Debian/Ubuntu/etc:

$ sudo apt-get install python-dev libkrb5-dev
$ pip install wheel
$ pip install pywinrm[kerberos]
$ pip install requests-kerberos
$ pip install pexpect

for RHEL/CentOS/etc:

$ sudo yum install python-devel krb5-devel krb5-workstation gcc
$ pip install wheel
$ pip install pywinrm[kerberos]
$ pip install requests-kerberos
$ pip install pexpect

Limitations

Don't use the file copier to transfer big files, the performance is not the best to transfer large files. It works OK passing inline scripts to remote windows nodes

Check Step/Script

This plugin include a connectivity test script that can be used as a Workflow Step or it could be called it directly, for example:

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

Aborting jobs

When a job step runs on a Windows node over WinRM, the command (and any child processes it spawns) runs on the remote node, while only a thin client process runs on the Rundeck server/runner. Historically, aborting the job killed the local client but left the remote command — and especially the child processes it had spawned — running on the Windows node.

The Terminate On Abort option fixes this. It is disabled by default; enable the checkbox (or set node attribute winrm-terminate-on-abort=true) to turn it on. When enabled:

1. Before launching, the plugin prepends a tiny preamble that makes the remote shell report the root PID of its process tree. The marker line is parsed by the plugin and removed from the job output, so it is not visible in the log.
   • For the powershell shell this uses the built-in $PID variable.
   • For the cmd shell the PID of the cmd.exe process is resolved via a short-lived child PowerShell (no dependency on the deprecated wmic).
2. When the job is aborted, the plugin:
   • sends the WS-Man terminate signal to the running command, and
   • opens a fresh WinRM shell and runs taskkill /F /T /PID <pid> to kill the entire process tree on the node.

Notes:

• The powershell shell (the default) provides the most reliable PID capture.
• If no PID could be captured, only the WS-Man terminate signal is sent, and some child processes may survive — the behaviour then matches older versions.
• When the option is disabled (the default), the preamble/termination is skipped entirely and the plugin behaves exactly as older versions did on abort.

Windows code page

WinRM shells default to code page 65001 (UTF-8). If command output is garbled on nodes that use a different ANSI code page (for example Japanese Windows, code page 932), set the node attribute codepage to the numeric Windows code page:

mywindows:
  hostname: 192.168.1.10
  osFamily: windows
  username: Administrator
  winrm-password-storage-path: keys/windows.password
  codepage: 932

Invalid values are ignored and the plugin falls back to 65001.

Troubleshooting

If a required Python module is missing and the interpreter is externally managed, install the package with the OS package manager or set Python Interpreter / winrm-interpreter to a virtualenv that has pywinrm (and optional Kerberos/CredSSP extras) installed.

If you get the following error:

module object has no attribute 'SSL_ST_INIT'

Update your version of PyOpenSSL:

python -m easy_install --upgrade pyOpenSSL

If you get the following error after run a PowerShell Script:

Failed: NonZeroResultCode: [WinRM Python] Result code: 1

Configure the Script Invocation Script as:

powershell.exe -ExecutionPolicy Bypass

Or you can make it permanent on the server executing on the Remote Node in powershell:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted

Docker example

Check these instructions for docker test