# How to Configure Ansible on Linux to Manage Windows Servers using WinRM
Ansible is widely regarded as the industry standard for configuration management and IT automation. Historically, Ansible was designed exclusively by and for Linux engineers, relying heavily on SSH to execute commands on remote nodes.
However, modern IT infrastructure is heterogeneous. Systems administrators frequently need a unified tool to deploy configurations across both Linux and Windows environments simultaneously.
Ansible achieves this not by forcing an SSH server onto Windows, but by utilizing Windows Remote Management (WinRM), a built-in Microsoft technology based on the WS-Management protocol.
This guide provides the complete workflow for configuring an Ansible control node (running on Linux) to securely authenticate and execute playbooks against a Windows Server target.
## Prerequisites
1. **Ansible Control Node:** A Linux machine (e.g., Ubuntu, RHEL) with Ansible installed.
2. **Target Node:** A Windows Server (2016, 2019, or 2022) with network connectivity to the control node.
3. Administrative credentials for the Windows Server.
## Step 1: Install Python WinRM Dependencies on the Control Node
Ansible relies on the Python `pywinrm` library to translate its commands into WS-Management requests that Windows can understand.
On your Linux Ansible control node, install the necessary Python packages.
For Debian/Ubuntu-based systems:
“`bash
sudo apt update
sudo apt install python3-pip -y
pip3 install “pywinrm>=0.3.0”
“`
For RHEL/CentOS systems:
“`bash
sudo dnf install python3-pip -y
pip3 install “pywinrm>=0.3.0”
“`
## Step 2: Configure the Ansible Inventory
You must tell Ansible how to connect to the Windows targets. Unlike Linux targets where Ansible defaults to SSH, you must explicitly define the connection protocol, port, and authentication method for Windows.
1. Open or create your Ansible inventory file (e.g., `/etc/ansible/hosts` or a local `inventory.ini` file).
2. Define a group for your Windows servers and set the specific connection variables.
“`ini
[windows]
192.168.1.50
192.168.1.51
ansible_connection=winrm
# Specify the username and password
ansible_user=Administrator
ansible_password=YourSecurePassword123!
# Specify the WinRM port (5986 is for HTTPS, 5985 is for HTTP)
ansible_port=5986
# Use Basic authentication (for testing/standalone servers) or NTLM/CredSSP (for domains)
ansible_winrm_transport=basic
# Ignore SSL certificate validation (necessary if using self-signed certs)
ansible_winrm_server_cert_validation=ignore
“`
*Security Note: Storing plaintext passwords in the inventory file is highly insecure. In a production environment, you should encrypt the `ansible_password` variable using Ansible Vault.*
## Step 3: Prepare the Windows Server (Target Node)
Out of the box, Windows Server does not accept inbound WinRM connections for execution. You must configure the WinRM service to listen for requests.
Microsoft provides an official PowerShell script specifically designed to prepare a Windows machine for Ansible.
1. Log in to your target Windows Server as an Administrator.
2. Open PowerShell as an Administrator.
3. Download the Ansible WinRM setup script:
“`powershell
Invoke-WebRequest -Uri https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1 -OutFile ConfigureRemotingForAnsible.ps1
“`
4. Execute the script:
“`powershell
powershell.exe -ExecutionPolicy Bypass -File .\ConfigureRemotingForAnsible.ps1
“`
### What the Script Does:
– Enables the WinRM service and sets it to start automatically.
– Generates a self-signed SSL certificate for encrypted communication.
– Creates a WinRM listener on port 5986 (HTTPS).
– Configures the Windows Firewall to allow inbound traffic on port 5986.
– Enables Basic authentication (required if the machine is not part of an Active Directory domain).
## Step 4: Test the Connection
Before writing complex playbooks, verify that the Linux control node can successfully authenticate and communicate with the Windows target.
Run the `win_ping` module from your Linux terminal. (This is the Windows equivalent of the standard Ansible `ping` module).
“`bash
ansible windows -m win_ping -i inventory.ini
“`
If the configuration is correct, you will receive a response in green indicating success:
“`json
192.168.1.50 | SUCCESS => {
“changed”: false,
“ping”: “pong”
}
“`
*If you receive a timeout or authentication error, verify your firewall rules on the Windows server and ensure the `pywinrm` library is properly installed on the Linux node.*
## Step 5: Execute Your First Windows Playbook
With the connection established, you can now manage Windows using Ansible’s extensive library of Windows modules (which typically begin with `win_`).
Create a simple playbook named `windows_setup.yml` that installs the IIS Web Server role and creates a directory.
“`yaml
—
– name: Configure Windows Server
hosts: windows
gather_facts: yes
tasks:
– name: Ensure IIS Web Server role is installed
win_feature:
name: Web-Server
state: present
include_management_tools: yes
register: iis_install
– name: Reboot if required by the IIS installation
win_reboot:
when: iis_install.reboot_required
– name: Create a custom directory for application logs
win_file:
path: C:\AppLogs
state: directory
“`
Run the playbook from your Linux control node:
“`bash
ansible-playbook -i inventory.ini windows_setup.yml
“`
Ansible will reach across the network, authenticate via WinRM, execute the necessary PowerShell commands under the hood to install IIS, reboot the machine if necessary, and create the directory—all without you ever needing to log into the Windows GUI.
## Summary
By installing `pywinrm` on your Linux control node and running the preparation script on your Windows targets, you unlock the ability to manage your entire hybrid infrastructure from a single pane of glass. Ansible’s idempotent nature ensures that your Windows servers remain in their desired state, bringing Linux-style automation efficiency to the Microsoft ecosystem.