Ansible Ad-Hoc Commands & Ping Module

Ad-hoc commands are Ansible's answer to the question: "How do I do something quickly on a bunch of servers without writing a full playbook?" They are single-line commands that execute one module against one or more hosts immediately. This lesson introduces the ad-hoc command syntax and walks you through the most important first command every Ansible user runs: the ping test.

Ad-Hoc vs Playbook: When to Use Each

Think of ad-hoc commands as the equivalent of running a command in your terminal — quick, immediate, and not saved for later. Playbooks are like shell scripts — structured, repeatable, version-controlled. Use ad-hoc commands when:

  • You want to verify connectivity or gather quick information
  • You need to perform a one-time urgent task across multiple servers (reboot after a kernel patch, kill a runaway process)
  • You are exploring what modules do before writing them into a playbook
  • You are debugging a specific host issue

Everything you can do with an ad-hoc command can also be done in a playbook, but ad-hoc commands are faster for immediate, non-recurring needs.

The Ad-Hoc Command Syntax

ansible [host-pattern] -i [inventory] -m [module] -a "[module-arguments]" [options]

Breaking this down:

  • [host-pattern] — Which hosts to target: all, a group name, a hostname, or a pattern like web*
  • -i [inventory] — Path to the inventory file or directory
  • -m [module] — The module to run (default is command if omitted)
  • -a "[module-arguments]" — Arguments to pass to the module
  • Common options: -b (become/sudo), -u username (remote user), -f 10 (run against 10 hosts in parallel)

The Ping Module: Your First Ad-Hoc Command

The ping module is not an ICMP ping — it is an Ansible connectivity test. It verifies that Ansible can connect to the managed node via SSH, that Python is available, and that Ansible modules can execute. It is the definitive "is everything working?" test.

ansible all -i inventory.ini -m ping

A successful response from each host:

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

The "changed": false value is important — it tells you the ping module did not change anything on the system. This is the idempotency indicator you will see in every module response.

Understanding the Output

Every Ansible module returns a JSON object. The key fields in a successful response are:

  • SUCCESS or FAILED — The overall task status
  • changed — Whether the module made a change to the system (true) or found the system already in the desired state (false)
  • Module-specific data — each module returns fields relevant to what it does (ping returns "ping": "pong"; the package module returns information about what was installed)

When a task fails, the output includes an error message that describes what went wrong. Learning to read this output is one of the most important diagnostic skills in Ansible.

Running Ping Against a Specific Group

ansible webservers -i inventory.ini -m ping
ansible databases  -i inventory.ini -m ping

Targeting groups lets you verify connectivity for subsets of your infrastructure independently — useful when you are debugging connectivity issues with a specific network segment.

Verbose Mode for Debugging

Add -v flags for increasing levels of detail:

  • -v — Shows the SSH connection details and module output
  • -vv — Shows the module arguments and connection parameters
  • -vvv — Shows the full SSH handshake and module transfer details
  • -vvvv — Maximum debugging output (rarely needed)

When ping fails, running with -vvv reveals exactly where the connection breaks — useful for diagnosing SSH configuration problems.

The gather_facts Module

A closely related diagnostic command gathers system information from managed nodes:

ansible web01 -i inventory.ini -m gather_facts

This returns hundreds of variables about the managed node: IP addresses, OS version, total memory, CPU count, installed packages, mount points, and much more. These variables (called "facts") are automatically available in playbooks and are the foundation for writing conditionals that behave differently on different operating systems.

Common Ping Failures and Solutions

Failure: SSH connection refused

The SSH service is not running on the managed node, or the port is blocked by a firewall. Verify with nc -zv 192.168.56.11 22.

Failure: Permission denied (publickey)

The public key has not been added to the managed node's authorized_keys, or the wrong private key is specified. Review Topic 9 for SSH configuration steps.

Failure: Python not found

Python is not installed on the managed node, or the path is wrong. Install Python 3 on the managed node or set ansible_python_interpreter=/usr/bin/python3 in your inventory.

Try This: Your First Three Ad-Hoc Commands

After confirming ping works, run these three commands and observe the output:

ansible all -i inventory.ini -m ping
ansible webservers -i inventory.ini -m ping
ansible web01 -i inventory.ini -m gather_facts | grep ansible_os_family

The third command filters the facts output to show only the OS family. You should see "ansible_os_family": "Debian" for Ubuntu nodes. This fact will be used extensively in Module 3 when you write OS-conditional playbooks.

Summary

Ad-hoc commands provide immediate, single-task execution against any set of hosts in your inventory. The ping module is the definitive Ansible connectivity test, verifying SSH access, Python availability, and module execution in one command. Verbose mode helps diagnose connectivity failures. The gather_facts module surfaces system information that powers conditional logic in playbooks. Mastering ad-hoc commands builds the intuition that makes playbook writing faster and more accurate.

Previous lessons
Back to courses
Next lessons

Leave a Comment