ansible.windows.win_reboot module – Reboot a windows machine

Note

This module is part of the ansible.windows collection (version 1.12.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_reboot.

Synopsis

  • Unconditionally reboot a Windows machine, wait for it to go down, come back up, and respond to commands.

  • For non-Windows targets, use the ansible.builtin.reboot module instead.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

boot_time_command

string

Command to run that returns a unique string indicating the last time the system was booted.

Setting this to a command that has different output each time it is run will cause the task to fail.

Default: "(Get-CimInstance -ClassName Win32_OperatingSystem -Property LastBootUpTime).LastBootUpTime.ToFileTime()"

connect_timeout

aliases: connect_timeout_sec

float

Maximum seconds to wait for a single successful TCP connection to the WinRM endpoint before trying again.

Default: 5.0

msg

string

Message to display to users.

Default: "Reboot initiated by Ansible"

post_reboot_delay

aliases: post_reboot_delay_sec

float

Seconds to wait after the reboot command was successful before attempting to validate the system rebooted successfully.

This is useful if you want wait for something to settle despite your connection already working.

Default: 0.0

pre_reboot_delay

aliases: pre_reboot_delay_sec

float

Seconds to wait before reboot. Passed as a parameter to the reboot command.

The minimum version is 2 seconds and cannot be set lower.

Default: 2.0

reboot_timeout

aliases: reboot_timeout_sec

float

Maximum seconds to wait for machine to re-appear on the network and respond to a test command.

This timeout is evaluated separately for both reboot verification and test command success so maximum clock time is actually twice this value.

Default: 600.0

test_command

string

Command to expect success for to determine the machine is ready for management.

By default this test command is a custom one to detect when the Windows Logon screen is up and ready to accept credentials. Using a custom command will replace this behaviour and just run the command specified.

Notes

Note

See Also

See also

ansible.builtin.reboot

The official documentation on the ansible.builtin.reboot module.

Examples

- name: Reboot the machine with all defaults
  ansible.windows.win_reboot:

- name: Reboot a slow machine that might have lots of updates to apply
  ansible.windows.win_reboot:
    reboot_timeout: 3600

# Install a Windows feature and reboot if necessary
- name: Install IIS Web-Server
  ansible.windows.win_feature:
    name: Web-Server
  register: iis_install

- name: Reboot when Web-Server feature requires it
  ansible.windows.win_reboot:
  when: iis_install.reboot_required

# One way to ensure the system is reliable, is to set WinRM to a delayed startup
- name: Ensure WinRM starts when the system has settled and is ready to work reliably
  ansible.windows.win_service:
    name: WinRM
    start_mode: delayed

# Additionally, you can add a delay before running the next task
- name: Reboot a machine that takes time to settle after being booted
  ansible.windows.win_reboot:
    post_reboot_delay: 120

# Or you can make win_reboot validate exactly what you need to work before running the next task
- name: Validate that the netlogon service has started, before running the next task
  ansible.windows.win_reboot:
    test_command: 'exit (Get-Service -Name Netlogon).Status -ne "Running"'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

elapsed

float

The number of seconds that elapsed waiting for the system to be rebooted.

Returned: always

Sample: 23.2

rebooted

boolean

True if the machine was rebooted.

Returned: always

Sample: true

Authors

  • Matt Davis (@nitzmahone)