AnsibleByExample

Ansible win_ping — Test Windows Host

Beginneransiblepingmodulewindows
2024-01-015By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

Introduction

Before running any automation against Windows hosts, you need to verify that Ansible can connect and execute commands. The win_ping module is the standard connectivity test for Windows managed nodes — it verifies WinRM access and that PowerShell is available to execute Ansible modules.

This is the Windows equivalent of the Linux ping module.

What Does win_ping Actually Test?

Unlike network ICMP ping, win_ping tests the entire Ansible communication chain:

  1. WinRM connectivity — Can Ansible reach the Windows host over WinRM (HTTP/HTTPS)?
  2. Authentication — Are the credentials valid?
  3. PowerShell execution — Is PowerShell available and functional?
  4. Module execution — Can Ansible transfer and execute a module on the remote host?

If win_ping succeeds, your Windows host is fully ready for Ansible automation.

Module Reference

Full name: ansible.windows.win_ping Collection: ansible.windows

Parameters

ParameterTypeDefaultDescription
datastringpongText to return in the response

Return Values

KeyTypeDescription
pingstringThe value of the data parameter (default: pong)

Basic Playbook

---
- name: Test Windows host connectivity
  hosts: windows
  gather_facts: false
  tasks:
    - name: Test WinRM connection
      ansible.windows.win_ping:

Run it:

ansible-playbook win_ping.yml -i inventory.ini

Expected output:

TASK [Test WinRM connection] ***************
ok: [win-server01] => {
    "changed": false,
    "ping": "pong"
}

Ad-Hoc Command

For a quick test without a playbook:

ansible windows -m ansible.windows.win_ping -i inventory.ini

Or test a single host:

ansible win-server01 -m ansible.windows.win_ping -i inventory.ini

Inventory Configuration for Windows

Windows hosts require WinRM-specific variables in your inventory:

[windows]
win-server01 ansible_host=192.168.1.100
win-server02 ansible_host=192.168.1.101

[windows:vars]
ansible_user=Administrator
ansible_password=SecureP@ss123
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore
ansible_port=5986

Connection Variables Explained

VariableDescriptionCommon Values
ansible_connectionConnection pluginwinrm (required for Windows)
ansible_winrm_transportAuthentication methodntlm, kerberos, basic, credssp
ansible_portWinRM port5985 (HTTP), 5986 (HTTPS)
ansible_winrm_server_cert_validationSSL certificate validationvalidate, ignore
ansible_winrm_schemeHTTP or HTTPShttp, https

Setting Up WinRM on Windows

Before win_ping can work, WinRM must be configured on the Windows host.

Quick Setup (PowerShell as Administrator)

# Enable WinRM
winrm quickconfig -force

# Allow basic authentication (for testing)
Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true

# Allow unencrypted traffic (for testing only)
Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true

# Configure HTTPS listener (production)
$cert = New-SelfSignedCertificate -DnsName $(hostname) -CertStoreLocation Cert:\LocalMachine\My
winrm create winrm/config/Listener?Address=*+Transport=HTTPS "@{Hostname=`"$(hostname)`"; CertificateThumbprint=`"$($cert.Thumbprint)`"}"

Using the ConfigureRemotingForAnsible.ps1 Script

Ansible provides a convenience script:

# Download and run
$url = "https://raw.githubusercontent.com/ansible/ansible-documentation/devel/examples/scripts/ConfigureRemotingForAnsible.ps1"
$file = "$env:temp\ConfigureRemotingForAnsible.ps1"
(New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file)
powershell.exe -ExecutionPolicy ByPass -File $file

Verify WinRM Configuration

# Check WinRM service
Get-Service WinRM

# List listeners
winrm enumerate winrm/config/Listener

# Test locally
winrm identify -r:http://localhost:5985 -auth:basic -u:Administrator -p:Password

Custom Data Parameter

Test with custom response data:

- name: Test with custom data
  ansible.windows.win_ping:
    data: "alive"
  register: result

- name: Show result
  ansible.builtin.debug:
    msg: "Host responded: {{ result.ping }}"

Using win_ping in Health Checks

Check Multiple Hosts with Error Handling

- name: Windows health check
  hosts: windows
  gather_facts: false
  tasks:
    - name: Test connectivity
      ansible.windows.win_ping:
      register: ping_result
      ignore_unreachable: true

    - name: Report unreachable hosts
      ansible.builtin.debug:
        msg: "WARNING: {{ inventory_hostname }} is unreachable!"
      when: ping_result.unreachable is defined and ping_result.unreachable

    - name: Continue with reachable hosts only
      ansible.builtin.debug:
        msg: "{{ inventory_hostname }} is ready for automation"
      when: ping_result.ping is defined

Pre-Flight Check Before Deployment

- name: Pre-deployment connectivity check
  hosts: windows_servers
  gather_facts: false
  tasks:
    - name: Verify all hosts are reachable
      ansible.windows.win_ping:
      register: connectivity

    - name: Fail fast if any host is down
      ansible.builtin.fail:
        msg: "Cannot proceed — {{ inventory_hostname }} is unreachable"
      when: connectivity is failed

Troubleshooting win_ping Failures

"winrm or requests is not installed"

fatal: [host]: FAILED! => {"msg": "winrm or requests is not installed"}

Fix: Install the pywinrm library on the Ansible control node:

pip install pywinrm

"Connection refused" or Timeout

fatal: [host]: UNREACHABLE! => {"msg": "plaintext: HTTPConnectionPool... Connection refused"}

Causes and fixes:

  • WinRM service not running → Start-Service WinRM on Windows host
  • Firewall blocking port 5985/5986 → Open the port in Windows Firewall
  • Wrong port in inventory → Verify ansible_port matches WinRM listener

"401 Unauthorized"

fatal: [host]: UNREACHABLE! => {"msg": "the specified credentials were rejected by the server"}

Fixes:

  • Verify username/password
  • Check ansible_winrm_transport matches server configuration
  • For domain accounts, use user@DOMAIN.COM format
  • Enable the required auth method on WinRM

"SSL: CERTIFICATE_VERIFY_FAILED"

fatal: [host]: UNREACHABLE! => {"msg": "ssl: certificate verify failed"}

Fix: Either install a valid certificate or set:

ansible_winrm_server_cert_validation=ignore

win_ping vs ping

Featurewin_pingping
Target OSWindowsLinux/macOS/Unix
ConnectionWinRMSSH
ShellPowerShellsh/bash
Collectionansible.windowsansible.builtin
Parametersdatadata

Conclusion

The win_ping module is the essential first step for any Windows automation with Ansible. It validates the complete communication chain — WinRM connectivity, authentication, and PowerShell execution — in a single test. If win_ping returns pong, your Windows host is ready for automation. If it fails, the error messages guide you directly to the issue: missing pywinrm, WinRM not configured, firewall blocking, or authentication problems.

All Tutorials