Ansible Reboot Module: Safely Reboot Servers & Wait for Recovery

How to reboot remote hosts with Ansible?

I'm going to show you a live Playbook with some simple Ansible code. I'm Luca Berton and welcome to today's episode of Ansible Pilot.

See also: Three options to Safely Limit Ansible Playbooks Execution to a Single Machine

Ansible reboot remote hosts

Today we're talking about the Ansible module reboot. The full name is ansible.builtin.reboot which means is part of the collection of modules "builtin" with ansible and shipped with ansible-core. This module is pretty stable and out for years and supports a large variety of operating systems. The purpose is to reboot a remote machine, wait for it to go down, come back up, and respond to commands. For Windows targets, use the ansible.windows.win_reboot module instead.

Parameters

• reboot_timeout _integer_ - 600 • msg _string_ - "Reboot initiated by Ansible" • reboot_command _string_ - "[OS specific]" • pre_reboot_delay _integer_ - 0 • post_reboot_delay _integer_ - 0 • test_command string - "whoami" • boot_time_command string - "cat /proc/sys/kernel/random/boot_id"

This module has not required parameters but some of them might are nice to know. Let me summarize the most useful parameters. The "reboot_timeout" defines how much time to expect before a machine returns up & running. The real timeout is double because of the process of reboot and test command success. The first step in the reboot process is to print a message to all the logged users. You could keep the default "Reboot initiated by Ansible" or customize using the "msg" parameter. Secondly is going to execute the reboot command, OS-specific. If you need a specific one, please customize the "reboot_command" parameter. You could define also some extra delay time using the "pre_reboot_delay" or "post_reboot_delay" integer. Both default to zero. Once rebooted the target host Ansible is going to verify the workstation fully working using a test command. The default is whoami, but you could customize using the "test_command" parameter. This module could return also the amount of time indeed for bootstrap process reading throw kernel, specifically /proc/sys/kernel/random/boot_id.

## Playbook

Let's jump into a real-life playbook on how to reboot remote hosts with Ansible Playbook. • reboot.yml

---
- name: reboot module Playbook
  hosts: all
  become: true
  tasks:
    - name: reboot host(s)
      ansible.builtin.reboot:
        msg: "reboot by Ansible"
        pre_reboot_delay: 5
        post_reboot_delay: 10
        test_command: "whoami"

code with ❤️ in GitHub

See also: Ansible on Fedora CoreOS: Reboot-aware Patching Workflow Complete Guide

Conclusion

Now you know how to reboot remote Linux hosts with Ansible.

Basic Reboot

- name: Reboot the server
  ansible.builtin.reboot:
  become: true

The module automatically waits for the host to come back online.

See also: Ansible on Fedora Silverblue 45: Reboot-aware Patching Workflow Complete Guide

Reboot with Custom Timeouts

- name: Reboot with extended timeout
  ansible.builtin.reboot:
    reboot_timeout: 600     # Wait up to 10 min for reboot
    connect_timeout: 30     # SSH connection timeout
    pre_reboot_delay: 10    # Wait 10s before rebooting
    post_reboot_delay: 30   # Wait 30s after reboot before testing
    msg: "Ansible is rebooting this server for maintenance"
  become: true

Conditional Reboot

Reboot only if kernel was updated

- name: Update packages
  ansible.builtin.apt:
    upgrade: dist
  register: update_result
  become: true
- name: Check if reboot needed (Debian/Ubuntu)
  ansible.builtin.stat:
    path: /var/run/reboot-required
  register: reboot_needed
- name: Reboot if required
  ansible.builtin.reboot:
    msg: "Rebooting after kernel update"
  when: reboot_needed.stat.exists
  become: true

Reboot only if RHEL needs it

- name: Check if reboot needed (RHEL)
  ansible.builtin.command: needs-restarting -r
  register: reboot_check
  changed_when: false
  failed_when: false
- name: Reboot if needed
  ansible.builtin.reboot:
  when: reboot_check.rc == 1
  become: true

Rolling Reboot (Zero Downtime)

---
- name: Rolling reboot of web servers
  hosts: webservers
  serial: 1
  become: true
  tasks:
    - name: Remove from load balancer
      ansible.builtin.uri:
        url: "http://lb/api/disable/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost
- name: Reboot
      ansible.builtin.reboot:
        reboot_timeout: 300
- name: Wait for application
      ansible.builtin.uri:
        url: "http://{{ inventory_hostname }}:8080/health"
      register: health
      retries: 10
      delay: 10
      until: health.status == 200
- name: Re-enable in load balancer
      ansible.builtin.uri:
        url: "http://lb/api/enable/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost

Reboot Windows

- name: Reboot Windows host
  ansible.windows.win_reboot:
    reboot_timeout: 600
    post_reboot_delay: 60

Key Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | reboot_timeout | 600s | Max wait for host to come back | | pre_reboot_delay | 0s | Delay before issuing reboot | | post_reboot_delay | 0s | Delay after reboot before testing | | connect_timeout | varies | SSH connection timeout | | test_command | whoami | Command to verify host is ready | | msg | — | Broadcast message before reboot |

FAQ

What if the host doesn't come back?

The task fails after reboot_timeout seconds. Use ignore_errors: true or ignore_unreachable: true if you want the play to continue.

Does reboot wait for all services to start?

It waits until SSH is accessible and test_command succeeds. For application readiness, add a separate health check task.

How is this different from command: reboot?

The reboot module handles the full lifecycle: disconnect, wait, reconnect, verify. Using command: reboot would lose the SSH connection and fail.

Basic Reboot

- name: Reboot the server
  ansible.builtin.reboot:
  become: true

With Custom Timeouts

- reboot:
    reboot_timeout: 600        # Wait up to 10 min for reboot
    connect_timeout: 30        # SSH connection timeout
    pre_reboot_delay: 5        # Seconds before reboot
    post_reboot_delay: 30      # Wait after reboot before checking
    msg: "Rebooting for kernel update"
  become: true

Conditional Reboot

# Reboot only if kernel was updated
- apt:
    name: linux-image-generic
    state: latest
  register: kernel_update
  become: true
- reboot:
  when: kernel_update.changed
  become: true

Check if Reboot Needed

# Debian/Ubuntu
- stat: { path: /var/run/reboot-required }
  register: reboot_required
- reboot:
  when: reboot_required.stat.exists
  become: true
# RHEL/Rocky
- command: needs-restarting -r
  register: reboot_needed
  changed_when: false
  failed_when: false
- reboot:
  when: reboot_needed.rc == 1
  become: true

Reboot with Service Validation

- reboot:
    test_command: systemctl is-active nginx
  become: true
# Or manual validation after reboot
- reboot:
  become: true
- wait_for:
    port: 80
    delay: 10
    timeout: 120
- uri:
    url: http://localhost/health
    status_code: 200
  retries: 5
  delay: 10

Rolling Reboot

---
- hosts: webservers
  serial: 1  # One host at a time
  tasks:
    - name: Remove from load balancer
      uri:
        url: "http://lb.internal/api/drain/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost
- name: Reboot
      reboot: { reboot_timeout: 300 }
      become: true
- name: Verify service
      wait_for: { port: 80, timeout: 60 }
- name: Add back to load balancer
      uri:
        url: "http://lb.internal/api/enable/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost

Patching + Reboot Playbook

---
- hosts: all
  become: true
  tasks:
    - name: Update all packages
      apt:
        upgrade: dist
        update_cache: true
      register: updates
- name: Check reboot required
      stat: { path: /var/run/reboot-required }
      register: reboot_file
- name: Reboot if needed
      reboot:
        msg: "Reboot after patching"
        reboot_timeout: 600
      when: reboot_file.stat.exists
- name: Verify services
      service_facts:
- assert:
        that: ansible_facts.services['nginx.service'].state == 'running'
        fail_msg: "nginx not running after reboot!"

Windows Reboot

- ansible.windows.win_reboot:
    reboot_timeout: 600
    post_reboot_delay: 60

Key Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | reboot_timeout | 600 | Max seconds to wait | | pre_reboot_delay | 0 | Delay before reboot | | post_reboot_delay | 0 | Delay after reboot | | connect_timeout | 5 | SSH reconnection timeout | | test_command | whoami | Verify host is back | | msg | Reboot message | Broadcast message |

FAQ

What if the reboot hangs?

reboot_timeout controls the max wait time. If exceeded, the task fails. Increase it for slow hardware or complex boot processes.

Does Ansible reconnect automatically?

Yes — the reboot module handles disconnection and reconnection automatically. It polls until the host responds.

Can I reboot without the reboot module?

- command: /sbin/reboot
  async: 1
  poll: 0
- wait_for_connection: { delay: 30, timeout: 300 }

The reboot module is simpler and handles edge cases better.

Basic Reboot

- ansible.builtin.reboot:
  become: true

With Custom Timeout

- reboot:
    reboot_timeout: 600   # Wait up to 10 minutes
    connect_timeout: 5
    pre_reboot_delay: 5   # Wait 5s before reboot
    post_reboot_delay: 30 # Wait 30s after boot before checking
  become: true

Conditional Reboot

# Only reboot if needed (e.g., after kernel update)
- apt:
    name: linux-generic
    state: latest
  register: kernel_update
  become: true
- reboot:
  when: kernel_update.changed
  become: true

Check If Reboot Required

# Debian/Ubuntu
- stat:
    path: /var/run/reboot-required
  register: reboot_required
- reboot:
  when: reboot_required.stat.exists
  become: true
# RHEL/CentOS
- command: needs-restarting -r
  register: needs_restart
  changed_when: false
  failed_when: false
  become: true
- reboot:
  when: needs_restart.rc == 1
  become: true

Custom Reboot Command

- reboot:
    reboot_command: "shutdown -r +1 'Ansible scheduled reboot'"
  become: true

Wait for Specific Service After Reboot

- reboot:
  become: true
- wait_for:
    port: 8080
    delay: 10
    timeout: 120
- uri:
    url: http://localhost:8080/health
    status_code: 200
  retries: 5
  delay: 10

Rolling Reboot

- hosts: webservers
  serial: 1  # One server at a time
  tasks:
    - reboot:
      become: true
- wait_for:
        port: 80
        delay: 10

Reboot Message

- reboot:
    msg: "Ansible is rebooting this host for kernel update"
    pre_reboot_delay: 60  # Give users time to save work
  become: true

FAQ

What if the reboot takes too long?

Increase reboot_timeout. Default is 600 seconds (10 minutes). For slow hardware: reboot_timeout: 1200.

How does Ansible know the server is back?

It polls SSH connectivity. Once SSH responds and the system is usable, the task completes.

Can I reboot Windows?

Yes — ansible.windows.win_reboot works the same way but over WinRM.

Related Articles

• privilege escalation with Ansible become • Windows management with Ansible

See also

• Ansible reboot Module: Restart Hosts and Wait for Recovery (Complete Guide)