The reboot module actual contract · Ansible

ansible.builtin.reboot is a two-word task that takes a production host out of service and waits for it to come back. It is worth knowing what every one of its parameters does before you write the two words.

The whole table below was read from ansible-doc ansible.builtin.reboot in a virtualenv pinned to ansible-core 2.21.3. Module defaults change between versions; the version you have installed is the only one whose defaults are true for you.

Read-only / Safethe module contract, read rather than assumed— Read-only. ansible-doc prints the parameters, defaults and attributes of the installed module. This is the single cheapest verification in the course.

$ ansible-doc ansible.builtin.reboot

   boot_time_command
      default: cat /proc/sys/kernel/random/boot_id
 connect_timeout
      default: null       (falls back to the connection plugin default)
 msg
      default: Reboot initiated by Ansible
 post_reboot_delay
      default: 0
 pre_reboot_delay
      default: 0
 reboot_command
      default: '[determined based on target OS]'
 reboot_timeout
      default: 600
 search_paths
      default: [/sbin, /bin, /usr/sbin, /usr/bin, /usr/local/sbin]
 test_command
      default: whoami

ATTRIBUTES:
 async: none          check_mode: full
 diff_mode: none      platform: posix

RETURN VALUES:
 elapsed   int   seconds waited for the system to be rebooted
 rebooted  bool  true if the machine was rebooted

The parameter that does the actual proving

boot_time_command is the interesting one, and it is the reason this module is better than a shell: reboot followed by a sleep.

Its default is cat /proc/sys/kernel/random/boot_id. That file holds a random UUID generated by the kernel at boot and stable for the lifetime of that boot. The module reads it before issuing the reboot, and polls for it after. When the value changes, a boot demonstrably happened.

That is a different claim from “the connection dropped and came back”. A connection drop can be a network blip, a restarted sshd, a saturated link, or a firewall reload. None of those are a reboot, and a module that inferred a reboot from a dropped connection would report success on all of them.

The documentation attaches a condition to changing it: “Setting this to a command that has different output each time it is run will cause the task to fail.” The command must be stable within a boot and different across boots. date fails. uptime fails. cat /proc/sys/kernel/random/boot_id is exactly right, which is why it is the default.

`reboot_timeout` is evaluated twice

The default is 600 seconds, and the sentence next to it is the one people miss:

This timeout is evaluated separately for both reboot verification and test command success so the maximum execution time for the module is twice this amount.

So reboot_timeout: 600 is a task that can occupy twenty minutes before it fails, not ten. The two phases are:

Reboot verification — wait until boot_time_command returns a different value from the one recorded before the reboot.
Test command success — wait until test_command (default whoami) runs successfully on the host.

Both get the full timeout independently.

The two delays, and how they differ

pre_reboot_delay and post_reboot_delay both default to 0 and are not symmetric.

pre_reboot_delay is passed as a parameter to the reboot command itself. The documentation records a platform-specific conversion: “On Linux, macOS and OpenBSD, this is converted to minutes and rounded down. If less than 60, it will be set to 0. On Solaris and FreeBSD, this will be seconds.”

That is a genuine trap. pre_reboot_delay: 30 on Linux is zero, not thirty seconds, because 30 seconds rounds down to 0 minutes. If you want a delay that a logged-in user could notice, the smallest meaningful value on Linux is 60.

post_reboot_delay is a controller-side wait after the reboot command succeeded, before validation begins. The documentation describes its purpose precisely: “This is useful if you want wait for something to settle despite your connection already working.”

That sentence names a real problem. sshd frequently accepts connections well before the rest of the boot has finished — before mounts are complete, before the network is fully configured, before services have started. test_command succeeding proves the host answers, not that it is ready. post_reboot_delay buys a fixed pause for the remainder to settle.

Service impact possiblea reboot task with deliberate values— Takes the host down and waits for it to return. Every parameter here overrides a default for a stated reason; on a production fleet this task belongs inside a serial batch with validation after it.

- name: Reboot to activate the new kernel
ansible.builtin.reboot:
  msg: 'Rebooting for the {{ patch_window_id }} maintenance window'
  reboot_timeout: 900
  post_reboot_delay: 30
  test_command: 'systemctl is-system-running --wait'
register: reboot_result

- name: Record how long the host took to return
ansible.builtin.debug:
  msg: >-
    {{ inventory_hostname }} rebooted={{ reboot_result.rebooted }}
    elapsed={{ reboot_result.elapsed }}s
    kernel_before={{ ansible_facts.kernel }}

post_reboot_delay: 30 is a fixed cost per host and it is the honest kind: thirty seconds of doing nothing, multiplied by the fleet, in exchange for not validating a host that is halfway through its boot.

`test_command`, and making it mean something

The default test_command is whoami. It proves the transport works and a command can be executed. That is the module’s job and it is a deliberately minimal bar.

It is not a health check. whoami succeeds on a host whose filesystems failed to mount, whose application did not start, and which came up on the wrong kernel.

Replacing it with something stronger — systemctl is-system-running --wait is the usual choice — moves part of the validation inside the module. That has one real advantage: it happens inside reboot_timeout, so a host that answers but never reaches a running system state fails the reboot task rather than passing it and failing something later.

`search_paths` and the ignored `PATH`

The module locates the shutdown command by searching search_paths, which defaults to /sbin, /bin, /usr/sbin, /usr/bin and /usr/local/sbin. The documentation is emphatic that only those paths are searched, and the notes repeat it: “PATH is ignored on the remote node when searching for the shutdown command.”

This is why a host with shutdown somewhere unusual fails a reboot task with a “cannot find shutdown” error even though which shutdown works perfectly when you SSH in and look. Your interactive PATH is not consulted.

The module’s own example covers the commonest real instance: a host with molly-guard installed, which interposes its own shutdown in /lib/molly-guard.

Service impact possiblea host whose shutdown lives somewhere else— Reboots the host, searching an additional path for the shutdown binary. Adding to search_paths does not remove the defaults being searched.

- name: Reboot a host with molly-guard installed
ansible.builtin.reboot:
  search_paths:
    - /lib/molly-guard
    - /sbin
    - /usr/sbin

reboot_command is the alternative: give the module a complete command to run instead of composing one. It carries a consequence stated directly in the documentation — “This will cause pre_reboot_delay, post_reboot_delay, and msg to be ignored.”

Losing post_reboot_delay is the one that catches people, because it is the settle-time parameter and its absence is invisible until a validation step starts failing intermittently.

Reboots the module did not initiate

ansible.builtin.reboot handles the case where Ansible issues the reboot. Sometimes something else does: a dnf transaction that triggers a restart, a cloud API call, a firmware update, a colleague.

ansible.builtin.wait_for_connection is the module for waiting on a host to become reachable again, and its defaults are its own:

Parameter	Default
`timeout`	600
`connect_timeout`	5
`sleep`	1
`delay`	0

Read-only / Safewaiting for a host somebody else rebooted— Read-only. Repeatedly attempts a connection and a ping until the host answers. It changes nothing; delay avoids the false success of connecting before the host has actually gone down.

- name: Trigger the firmware update, which reboots the host itself
ansible.builtin.command:
  argv: [/usr/local/sbin/apply-firmware, '--reboot']
register: firmware
changed_when: firmware.rc == 0
async: 30
poll: 0

- name: Wait for the host to go away and come back
ansible.builtin.wait_for_connection:
  delay: 60
  timeout: 900
  sleep: 5

Without delay, wait_for_connection succeeds before the host has gone down

The reboot has been requested and the host has not yet stopped answering. wait_for_connection connects on its first attempt, succeeds, and the play proceeds to validate a host that is about to disappear.

The symptom is a validation step that passes and then the next task reports the host unreachable, which reads as a random network fault and is not one.

delay is the fix: it waits that many seconds before the first attempt. Set it longer than the host takes to actually stop accepting connections. Sixty seconds is a reasonable starting point for a physical server and generous for a VM.

ansible.builtin.reboot does not have this problem, because it does not wait for a connection — it waits for boot_time_command to return a different value, which cannot happen until a boot has occurred. That is the structural advantage of using the module where you can.

Do not confuse wait_for_connection with wait_for. wait_for polls a port or a file and defaults to host: 127.0.0.1 — meaning that unless you override it, it polls a port on the host it is running on, and run from the controller with delegate_to it polls the controller. wait_for_connection uses the actual connection plugin and the ping module, which is the question you are asking after a reboot.

Under the hood

The module’s declared attributes explain several behaviours that otherwise look arbitrary.

async: none. The module cannot be used with the async keyword. That rules out the pattern people reach for first — fire the reboots at the whole batch asynchronously and collect the results afterwards. The reason is structural: the module has to hold the before-and-after boot identifier across the connection loss, and an async job launched on a host that is about to reboot has nowhere to keep it.

platform: posix. Windows targets use ansible.windows.win_reboot, which is a different module in a different collection with different parameters. A play that patches a mixed estate cannot share the reboot task.

check_mode: full. A --check run through the reboot module does not reboot anything and reports what it would have done. That is worth knowing because it makes a whole patch play safe to check-run, including the reboot task, which is not true of every module in a patch role.

bypass_host_loop: none. The task runs per host, so it respects serial, throttle and the rest of the batching machinery — exactly what you want, and worth confirming rather than assuming, because a module that bypassed the host loop would reboot the whole play at once regardless of serial.

The action plugin does the work on the controller. The module has a corresponding action plugin, which is what makes surviving the connection loss possible at all: the logic that records the boot identifier, issues the reboot, and then polls, runs on the controller, not on a host that is in the middle of going away.

The elapsed return value comes out of that polling loop, and it is more useful than it looks. Logged per host over several patch cycles it tells you which hosts are getting slower to boot, which is a leading indicator for failing storage and for a firmware update that added thirty seconds of POST to every machine in a rack.

What happens if a host never comes back?

The task fails on that host after the timeout, and everything about what happens next was decided before the run started.

The failure is a task failure rather than an unreachable, because the module ran and returned a result. With max_fail_percentage: 0 the play stops and the remaining batches never start — which is exactly the design, because a host that did not come back from a kernel upgrade is the strongest possible signal that the next batch should not be attempted.

What the play cannot do is fix it. The host is down, it is not answering SSH, and Ansible has no out-of-band path to it. Recovery is console access: iDRAC, iLO, the hypervisor console, or someone with a crash cart. That is why the runbook for a patch window contains console credentials, and why a window scheduled at a time when nobody can reach the console is a window with no recovery path.

The single most useful thing the play can do is make the state unambiguous. A host in always: that records “reboot initiated at 02:14, never returned, drained from the load balancer, NOT returned to service” turns a mystery into a starting point.

And this is the argument for the canary being one host, restated in its strongest form: if the new kernel does not boot on this hardware, you find out with one machine down, not ten.

Knowledge check

Why this matters

Almost every parameter on this module exists because somebody’s fleet did something unexpected and the fix had to be expressible.

search_paths exists because molly-guard moves shutdown. post_reboot_delay exists because sshd answers before the host is ready. boot_time_command is configurable because not every platform has /proc. reboot_timeout is doubled because verification and readiness are separate waits and someone had to be told.

Read as a list of parameters it is unremarkable. Read as a list of failures, it is a fairly complete map of the ways a scripted reboot goes wrong, written by people who hit each one.

The practical takeaway is narrower than the map. ansible.builtin.reboot with mostly-default parameters is the right tool, and the two values worth setting deliberately every time are reboot_timeout — because it governs your window — and post_reboot_delay — because zero is rarely the right answer on a real host.

Everything else, leave alone until a host proves you need it.