Ansible ping Module: Test Host Connectivity (Complete Guide)

Ansible ping Module: Test Host Connectivity (Complete Guide)

The Ansible ping module (ansible.builtin.ping) is the first command every Ansible user runs. It verifies that Ansible can connect to remote hosts, execute Python, and return results. It's NOT an ICMP ping — it's a full connectivity test.

See also: Ansible win_ping Module: Test Windows Host Connectivity (Examples)

Basic Usage

# Ping all hosts in inventory
ansible all -m ping
# Ping specific group
ansible webservers -m ping
# Ping single host
ansible web01 -m ping
# Ping localhost
ansible localhost -m ping

Successful Output

web01 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

Failed Output

web01 | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: Permission denied",
    "unreachable": true
}

What ansible ping Actually Tests

The ping module verifies the entire Ansible connection chain: ✅ Inventory is configured correctly ✅ SSH (or WinRM) connection works ✅ Authentication succeeds (key or password) ✅ Python is available on the remote host ✅ Ansible can execute modules and return JSON

It is NOT an ICMP ping. For ICMP ping, use the shell module:

ansible all -m shell -a "ping -c 1 8.8.8.8"

See also: Ansible Ping Module: Test Host Connectivity & Availability (Guide)

Common Options

# Specify inventory file
ansible all -m ping -i inventory/hosts.ini
# Specify SSH user
ansible all -m ping -u deploy
# Use password authentication
ansible all -m ping --ask-pass
# Use sudo
ansible all -m ping --become --ask-become-pass
# Specify SSH key
ansible all -m ping --private-key ~/.ssh/deploy_key
# Increase verbosity for debugging
ansible all -m ping -vvv
# Set timeout
ansible all -m ping -T 10

Ping in Playbooks

---
- name: Verify connectivity
  hosts: all
  gather_facts: false
  tasks:
    - name: Ping all hosts
      ansible.builtin.ping:
      register: ping_result
- name: Show result
      ansible.builtin.debug:
        var: ping_result

Custom Ping Data

- name: Ping with custom data
  ansible.builtin.ping:
    data: "alive"
  register: result
# Returns: {"ping": "alive"} instead of {"ping": "pong"}

See also: Ansible Custom Modules: Write Your Own Module in Python (Complete Guide)

Troubleshooting Ping Failures

SSH Connection Refused

UNREACHABLE! => {"msg": "Failed to connect via ssh: Connection refused"}

Fix:

# Check SSH is running on remote host
ssh user@host
# Check port
ansible all -m ping -e "ansible_port=2222"

Permission Denied

UNREACHABLE! => {"msg": "Failed to connect via ssh: Permission denied"}

Fix:

# Copy SSH key
ssh-copy-id user@host

# Or use password
ansible all -m ping --ask-pass
# Check SSH key permissions
chmod 600 ~/.ssh/id_ed25519

Python Not Found

FAILED! => {"msg": "/usr/bin/python: not found"}

Fix:

# Specify Python interpreter
ansible all -m ping -e "ansible_python_interpreter=/usr/bin/python3"

# Or use raw module to install Python first
ansible all -m raw -a "apt install -y python3"

Host Key Verification Failed

UNREACHABLE! => {"msg": "Host key verification failed"}

Fix:

# ansible.cfg
[defaults]
host_key_checking = False

Or:

export ANSIBLE_HOST_KEY_CHECKING=False
ansible all -m ping

Timeout

UNREACHABLE! => {"msg": "timed out"}

Fix:

# Increase timeout
ansible all -m ping -T 30

# Check network connectivity
ping host  # ICMP ping
telnet host 22  # Check SSH port

Ping Windows Hosts

For Windows hosts using WinRM:

ansible windows -m ansible.windows.win_ping

- name: Ping Windows hosts
  hosts: windows
  tasks:
    - name: Win ping
      ansible.windows.win_ping:

Ping with Different Connection Types

# Local connection (no SSH)
ansible localhost -m ping -c local
# Docker connection
ansible container1 -m ping -c docker
# Network devices
ansible switches -m ping -c network_cli

FAQ

What does ansible -m ping do?

It tests the full Ansible connection to remote hosts: SSH connectivity, authentication, Python availability, and module execution. It returns "pong" on success. It does NOT perform an ICMP ping.

Why does ansible ping fail with "Permission denied"?

The SSH key isn't authorized on the remote host, or the username is wrong. Fix with ssh-copy-id user@host to copy your key, or use --ask-pass for password authentication.

Why does ansible ping say "Python not found"?

The remote host doesn't have Python in the expected path. Set ansible_python_interpreter=/usr/bin/python3 in your inventory or use ansible all -m raw -a "apt install -y python3" to install it.

Is ansible ping the same as ICMP ping?

No. Ansible ping (ansible.builtin.ping) is an application-level test that verifies SSH + Python + module execution. For ICMP ping, use ansible all -m shell -a "ping -c 1 target".

How do I ping all hosts in my inventory?

Run ansible all -m ping. Use -i inventory_file to specify a custom inventory. The output shows SUCCESS or UNREACHABLE for each host.

Conclusion

The Ansible ping module is your first diagnostic tool. Run it after setting up inventory, after SSH key changes, and before any automation to verify connectivity. For failures, use -vvv to get detailed debug output.

Related Articles

• Getting Started with Ansible • Ansible Inventory: Complete Guide • Ansible Troubleshooting: Debug & Fix Errors • Ansible Windows Automation: WinRM Guide