Ansible reboot Module — Reboot Linux

Introduction

Rebooting servers is a critical operation in system administration — kernel updates, configuration changes, and hardware maintenance all require it. The ansible.builtin.reboot module handles the entire lifecycle: notifying users, executing the reboot, waiting for the host to come back online, and verifying it's functional. No manual SSH reconnection needed.

For Windows hosts, use ansible.windows.win_reboot instead.

Module Reference

Full name: ansible.builtin.reboot Collection: ansible.builtin

Parameters

Parameter	Type	Default	Description
`reboot_timeout`	int	600	Max seconds to wait for reboot to complete
`msg`	string	"Reboot initiated by Ansible"	Broadcast message to logged-in users
`reboot_command`	string	OS-specific	Custom reboot command
`pre_reboot_delay`	int	0	Seconds to wait before rebooting
`post_reboot_delay`	int	0	Seconds to wait after host comes back
`test_command`	string	`whoami`	Command to verify host is functional
`boot_time_command`	string	`cat /proc/sys/kernel/random/boot_id`	Command to detect if host has rebooted
`connect_timeout`	int	None	Override connection timeout during reboot

Return Values

Key	Type	Description
`rebooted`	bool	Whether the host was rebooted
`elapsed`	int	Seconds elapsed waiting for reboot

Basic Playbook

---
- name: Reboot servers
  hosts: all
  become: true
  tasks:
    - name: Reboot host
      ansible.builtin.reboot:
        msg: "Reboot by Ansible for maintenance"
        pre_reboot_delay: 5
        post_reboot_delay: 10
        test_command: whoami

How the Reboot Process Works

The module follows this sequence:

Broadcast message to all logged-in users via wall
Wait for pre_reboot_delay seconds
Execute the reboot command
Wait for the host to go offline
Poll until the host responds to SSH connections
Wait for post_reboot_delay seconds
Run test_command to verify the host is functional
Report success with elapsed time

If any step fails or reboot_timeout is exceeded, the task fails.

Conditional Reboot After Kernel Update

The most common pattern — reboot only when required:

- name: Update kernel
  ansible.builtin.dnf:
    name: kernel
    state: latest
  register: kernel_update

- name: Reboot if kernel was updated
  ansible.builtin.reboot:
    msg: "Rebooting for kernel update"
    reboot_timeout: 300
  when: kernel_update.changed

Using a Handler

- name: Patch servers
  hosts: all
  become: true
  tasks:
    - name: Apply all updates
      ansible.builtin.dnf:
        name: "*"
        state: latest
      notify: Reboot if needed

    - name: Check if reboot is required
      ansible.builtin.stat:
        path: /var/run/reboot-required
      register: reboot_required
      changed_when: reboot_required.stat.exists
      notify: Reboot if needed

  handlers:
    - name: Reboot if needed
      ansible.builtin.reboot:
        msg: "Ansible: rebooting after updates"
        post_reboot_delay: 30

Check needs-restarting (RHEL/CentOS)

- name: Check if reboot is needed
  ansible.builtin.command: needs-restarting -r
  register: reboot_check
  changed_when: reboot_check.rc == 1
  failed_when: reboot_check.rc > 1
  notify: Reboot server

handlers:
  - name: Reboot server
    ansible.builtin.reboot:
      reboot_timeout: 600

Rolling Reboot with serial

Reboot hosts in batches to maintain service availability:

- name: Rolling reboot
  hosts: web_servers
  serial: 1
  become: true
  tasks:
    - name: Remove from load balancer
      ansible.builtin.uri:
        url: "http://lb.example.com/api/pool/remove"
        method: POST
        body: '{"host": "{{ inventory_hostname }}"}'
        body_format: json
      delegate_to: localhost

    - name: Reboot host
      ansible.builtin.reboot:
        msg: "Rolling reboot - maintenance window"
        post_reboot_delay: 30
        test_command: systemctl is-active httpd

    - name: Add back to load balancer
      ansible.builtin.uri:
        url: "http://lb.example.com/api/pool/add"
        method: POST
        body: '{"host": "{{ inventory_hostname }}"}'
        body_format: json
      delegate_to: localhost

Custom Test Commands

Verify services are running after reboot, not just SSH:

# Verify web server is running
- name: Reboot and verify httpd
  ansible.builtin.reboot:
    test_command: systemctl is-active httpd

# Verify database is accepting connections
- name: Reboot database server
  ansible.builtin.reboot:
    test_command: pg_isready -U postgres
    reboot_timeout: 900
    post_reboot_delay: 60

# Verify custom application
- name: Reboot app server
  ansible.builtin.reboot:
    test_command: curl -sf http://localhost:8080/health
    post_reboot_delay: 30

Handling Slow Boots

For servers with long boot times (hardware RAID init, BIOS checks, large databases):

- name: Reboot storage server
  ansible.builtin.reboot:
    reboot_timeout: 1800        # 30 minutes max wait
    post_reboot_delay: 120      # Wait 2 min after SSH is back
    connect_timeout: 60         # 60s SSH timeout during reconnect
    test_command: "mountpoint -q /data && systemctl is-active nfs-server"

Error Handling

- name: Reboot with error handling
  block:
    - name: Reboot host
      ansible.builtin.reboot:
        reboot_timeout: 300
      register: reboot_result

    - name: Verify reboot completed
      ansible.builtin.debug:
        msg: "Reboot took {{ reboot_result.elapsed }} seconds"

  rescue:
    - name: Reboot failed - alert
      ansible.builtin.debug:
        msg: "WARNING: {{ inventory_hostname }} failed to reboot within timeout!"

    - name: Attempt manual recovery
      ansible.builtin.wait_for_connection:
        timeout: 600

Async Reboot (Fire and Forget)

For edge cases where you need to trigger a reboot without waiting:

- name: Trigger reboot and move on
  ansible.builtin.command: /sbin/shutdown -r +1 "Scheduled reboot"
  async: 0
  poll: 0

- name: Wait for host to come back
  ansible.builtin.wait_for_connection:
    delay: 90
    timeout: 600

reboot vs win_reboot

Feature	`reboot`	`win_reboot`
Target OS	Linux/macOS/Unix	Windows
Connection	SSH	WinRM
Boot detection	`/proc/sys/kernel/random/boot_id`	Win32 API
Default test	`whoami`	PowerShell command
User notification	`wall` command	Windows message

Common Issues

Timeout Errors

fatal: [host]: FAILED! => {"msg": "Timed out waiting for last boot time check"}

Fix: Increase reboot_timeout or investigate slow boot causes.

"Unreachable" After Reboot

The SSH connection may be refused during boot. The module handles this automatically, but if your SSH config has strict settings:

# In ansible.cfg
[ssh_connection]
ssh_args = -o ServerAliveInterval=30 -o ServerAliveCountMax=10

Conclusion

The ansible.builtin.reboot module handles the complete reboot lifecycle — from user notification through boot verification — in a single task. The key patterns are: conditional reboots after kernel updates (only reboot when needed), rolling reboots with serial (maintain availability), and custom test_command values (verify services, not just SSH). For production environments, always use handlers to trigger reboots only when changes occur, and rolling strategies to avoid downtime.

Ansible reboot Module — Reboot Linux

Introduction

Module Reference

Parameters

Return Values

Basic Playbook

How the Reboot Process Works

Conditional Reboot After Kernel Update

Using a Handler

Check needs-restarting (RHEL/CentOS)

Rolling Reboot with serial

Custom Test Commands

Handling Slow Boots

Error Handling

Async Reboot (Fire and Forget)

reboot vs win_reboot

Common Issues

Timeout Errors

"Unreachable" After Reboot

Related Articles

Conclusion