# Connect to Windows Nodes with PyWinRM

Rundeck allows users to execute jobs to remote Windows nodes to manage and automate tasks using Rundeck workflows. This article shows how to add a Windows node and execute Rundeck jobs and commands with windows-based systems.

To communicate with Windows nodes, Rundeck uses an out-of-the-box Node Execution/ File Copier plugin (opens new window) that uses the WinRM (opens new window) (Windows Remote Management) protocol.

Note: If this is the first time adding remote nodes, we suggest reviewing the Rundeck Tutorial before adding Windows nodes. This exercise assumes some experience with Windows and Rundeck basics covered in the Tutorial.

# Basic pywinrm Plugin Requirements

The pywinrm plugin (opens new window) needs the following requirements on the Rundeck server to work properly. It is supported on Rundeck running on Linux, Mac OS X, or Windows operating systems.

# Requirements:


Make sure that your python installation is same that the one that is exported in your "PATH" environment variable, so the PyWinRm plugin can access its packages.

  • We recommend this commands to check the python installation:
# Windows OS
where python - "exaple/path/to/python"
# linux OS
which python - "exaple/path/to/python"

The path to the executable must be the same if we dispatch the command to the required node with the AD-HOC command functionality.

The pywinrm plugin (opens new window) uses the python WinRM Library (opens new window) to provide the WinRM implementation.

  • Python 3.3-3.5 or PyPy2 installed on Rundeck server. (Python 3 strongly recommended)
  • Pywinrm library (It can be installed with the following command: pip install pywinrm)
  • OpenSSL version 1.1.1 or higher. (openssl version can be checked with the following command: openssl version - "OpenSSL 1.1.1k")
    • requests-kerberos and requests-credssp are optional.

Note: Due to networking complexity issues this exercise will not work with the Welcome Projects. These steps assume you have Rundeck installed using these instructions. For more information see the Additional Information section.

# Basic Windows Requirements

To follow this How to Guide, your Windows system needs the following requirements:

  • A Windows node in the same network as the Rundeck instance
  • Windows Server 2008 R2 or above
  • PowerShell 2.0 or above

# Windows Configuration

The first step is to configure the Windows machine. To do this, go to the Windows instance and follow the these steps:

  1. Open a PowerShell terminal as an admin user profile.
  2. Enable the WinRM protocol on Windows:
    winrm qc
  3. Define the authentication type:
    winrm set winrm/config/service/Auth '@{Basic="true"}'
  4. Define the client authentication type:
    winrm set winrm/config/client/Auth '@{Basic="true"}'
  5. Allow unencrypted SOAP messages:
    winrm set winrm/config/service '@{AllowUnencrypted="true"}'


It's important to allow access to the 5985 port via Windows Firewall (any between the Rundeck server and the node), to receive the remote requests.

Note: These settings are for Exercise purposes only and do not represent the most secure method of implementing. Please follow your own security guidelines for production implementations.

# Rundeck Configuration

Create a Windows-based project on the Rundeck instance.

  1. Create a new project: Name windows, and LabelWindows Jobs

    Create Project

  2. Go to the Default Node Executor tab and then select WinRM Node Executor Python. It may be necessary to set the Python interpreter textbox to python3 interpreter as the command/path.

    Node Executor

  3. Go to the Default File Copier tab and select the WinRM Python File Copier. Similar to the previous step, it may be necessary to define the Python interpreter textbox as python3 interpreter for the command/path.

    File Copier

  4. Click on the Create button.

# Adding a Windows Test Node

Now Rundeck should ask about the model source. Let's start with the Windows node definition.

Don't forget to add the Windows user password to the Rundeck key storage.

  1. Go to the System Menu(Gear Icon) > Key Storage.

    Key Storage

  2. Click on the + Add or Upload a Key button.
  3. Enter the Windows password as shown in the image and save.

    Key Storage Entry

Enterprise Users may need to add project/windows to the Storage Path line.

# Testing the New Windows Remote Node

Now it's time to send some commands against the windows remote machine.

  1. Click on the Commands section on the left sidebar.
  2. On the Nodes section use a filter to dispatch only to the Windows machine, type:
    name: mywindows
  3. On the Enter a command textbox type: dir (listing directories and files).
  4. Click on the Run on 1 Node button.


And now your Windows node is ready to receive PowerShell commands from the Rundeck instance.

# Additional Information

Using Linux? Read the Using SSH on Linux/Unix Nodes article to learn more.

# Networking Issues

Docker Desktop has some limitations to how it handles networking. Check out this information about how to get the Rundeck Welcome Projects to connect to a single host on your local network.

Last Updated: 9/28/2023, 11:38:04 PM