unit 2 · Setup
Your first ad-hoc command
One line, straight answer, no playbook
you may want to read 5 · Installing a control node first — but nothing is locked
tl;dr
- ansible <target> -m <module> runs one module against some hosts, right now. That is an ad-hoc command.
- Use it for quick checks and one-offs: ping a group, run uptime, gather a fact.
- Anything repeatable is playbook territory (unit 4) — ad-hoc is a probe, not configuration.
why it matters Ad-hoc is how you prove Ansible can reach your machines and answer "is it up?" in one line — and knowing when NOT to use it keeps real configuration in reviewable playbooks.
Lesson 5 gave you a control node. So far it has configured exactly nothing. The fastest way to change that — and the tool you’ll reach for daily — is the
ad-hoc command : one line that runs one module against some hosts, immediately. No YAML file, no playbook, answer straight back to your terminal.
Here is the whole anatomy:
# target module to run, by FQCN
ansible web -m ansible.builtin.pingRead it left to right. ansible is the CLI itself. web is the target —
the name of a group in your inventory; all targets every host you manage,
and richer patterns exist, but that whole machinery is unit 3, so park it.
-m names the module to run, by FQCN as always. This
one runs ansible.builtin.ping against everything in web — the classic
first command, because it proves the thing that matters before anything else:
Ansible can reach those hosts and execute a module on them.
Most modules also want arguments, and that’s -a. In ad-hoc commands you pass
them as key=value pairs inside one quoted string. There’s a second form of
-a you’ll see constantly: used without -m, it takes a command to run
on the targets.
ansible web -m ansible.builtin.ping # can I reach the web group?
ansible all -a "uptime" # run a quick command everywhere
ansible all -m ansible.builtin.setup # gather facts (lesson 17) from every hostWhen ad-hoc, when playbook
Ad-hoc is for quick checks and one-offs: ping a group before a deploy, restart a service that’s wedged, pull a fact from a fleet to answer a question in chat. Fire, read, done.
What it is not for is repeatable configuration. An ad-hoc command vanishes with your shell history — nothing to review, nothing to re-run next month, nothing a colleague can read to learn what “configured” means for this host. The moment you’d run the same line twice, or the line describes desired state rather than asks a question, it belongs in a playbook — the reviewable, repeatable artifact that unit 4 is entirely about.
Until then, one habit: make ansible <group> -m ansible.builtin.ping your
opening move whenever anything acts strange. Reachability first, diagnosis
second — it’s the cheapest fact you can buy.
at work, this sounds like
- “Just do it ad-hoc.”
- Run it as a one-liner from the CLI — it is a one-off, not worth writing a playbook for.
self-check — recall, not a test
1 Name the three parts of "ansible web -m ansible.builtin.ping".
2 Restart a service on twenty boxes once, versus keep a package installed on every box forever. Which is ad-hoc, which is playbook?
3 Where is key=value argument shorthand fine, and where does it date you?
lab (optional — never required)
On your control node, run ansible localhost -m ansible.builtin.ping, then ansible localhost -a "uptime", and compare what each returns.
needs: The control node from lesson 5.