ansible.builtin.ping module – Try to connect to host, verify a usable python and return pong on success

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name ping even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.ping for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • A trivial test module, this module always returns pong on successful contact. It does not make sense in playbooks, but it is useful from /usr/bin/ansible to verify the ability to login and that a usable Python is configured.

  • This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node.

  • For Windows targets, use the ansible.windows.win_ping module instead.

  • For Network targets, use the ansible.netcommon.net_ping module instead.

Parameters

Parameter

Comments

data

string

Data to return for the ping return value.

If this parameter is set to crash, the module will cause an exception.

Default: "pong"

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platform: posix

Target OS/families that can be operated against

See Also

See also

ansible.netcommon.net_ping

Tests reachability using ping from a network device.

ansible.windows.win_ping

A windows version of the classic ping module.

Examples

# Test we can logon to 'webservers' and execute python with json lib.
# ansible webservers -m ansible.builtin.ping

- name: Example from an Ansible Playbook
  ansible.builtin.ping:

- name: Induce an exception to see what happens
  ansible.builtin.ping:
    data: crash

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

ping

string

Value provided with the data parameter.

Returned: success

Sample: "pong"

Authors

  • Ansible Core Team

  • Michael DeHaan