1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

Docs: Clean up 'win_reboot' module docs (#46377)

* Docs: Clean up 'win_reboot' module docs

This is part of a series of module doc cleanups.

* Remove hypothetical example
This commit is contained in:
Dag Wieers 2018-10-04 05:19:58 +02:00 committed by Jordan Borean
parent 56f23594a5
commit 21d23829be

View file

@ -12,72 +12,96 @@ DOCUMENTATION = r'''
module: win_reboot module: win_reboot
short_description: Reboot a windows machine short_description: Reboot a windows machine
description: description:
- Reboot a Windows machine, wait for it to go down, come back up, and respond to commands. - Reboot a Windows machine, wait for it to go down, come back up, and respond to commands.
version_added: "2.1" version_added: '2.1'
options: options:
pre_reboot_delay: pre_reboot_delay:
description: description:
- Seconds for shutdown to wait before requesting reboot - Seconds for shutdown to wait before requesting reboot.
type: int type: int
default: 2 default: 2
aliases: [ pre_reboot_delay_sec ] aliases: [ pre_reboot_delay_sec ]
post_reboot_delay: post_reboot_delay:
description: description:
- Seconds to wait after the reboot was successful and the connection was re-established - Seconds to wait after the reboot was successful and the connection was re-established.
- This is useful if you want wait for something to settle despite your connection already working - This is useful if you want wait for something to settle despite your connection already working.
type: int type: int
default: 0 default: 0
version_added: '2.4' version_added: '2.4'
aliases: [ post_reboot_delay_sec ] aliases: [ post_reboot_delay_sec ]
shutdown_timeout: shutdown_timeout:
description: description:
- Maximum seconds to wait for shutdown to occur - Maximum seconds to wait for shutdown to occur.
- Increase this timeout for very slow hardware, large update applications, etc - Increase this timeout for very slow hardware, large update applications, etc.
- This option has been removed since Ansible 2.5 as the win_reboot behavior has changed - This option has been removed since Ansible 2.5 as the win_reboot behavior has changed.
type: int type: int
default: 600 default: 600
aliases: [ shutdown_timeout_sec ] aliases: [ shutdown_timeout_sec ]
reboot_timeout: reboot_timeout:
description: description:
- Maximum seconds to wait for machine to re-appear on the network and respond to a test command - 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 network appearance and test command success (so maximum clock time is actually twice this value) - This timeout is evaluated separately for both network appearance and test command success (so maximum clock time is actually twice this value).
type: int type: int
default: 600 default: 600
aliases: [ reboot_timeout_sec ] aliases: [ reboot_timeout_sec ]
connect_timeout: connect_timeout:
description: description:
- Maximum seconds to wait for a single successful TCP connection to the WinRM endpoint before trying again - Maximum seconds to wait for a single successful TCP connection to the WinRM endpoint before trying again.
type: int type: int
default: 5 default: 5
aliases: [ connect_timeout_sec ] aliases: [ connect_timeout_sec ]
test_command: test_command:
description: description:
- Command to expect success for to determine the machine is ready for management - Command to expect success for to determine the machine is ready for management.
type: str
default: whoami default: whoami
msg: msg:
description: description:
- Message to display to users - Message to display to users.
type: str
default: Reboot initiated by Ansible default: Reboot initiated by Ansible
notes: notes:
- If a shutdown was already scheduled on the system, C(win_reboot) will abort the scheduled shutdown and enforce its own shutdown. - If a shutdown was already scheduled on the system, C(win_reboot) will abort the scheduled shutdown and enforce its own shutdown.
- Beware that when C(win_reboot) returns, the Windows system may not have settled yet and some base services could be in limbo.
This can result in unexpected behavior. Check the examples for ways to mitigate this.
- For non-Windows targets, use the M(reboot) module instead. - For non-Windows targets, use the M(reboot) module instead.
author: author:
- Matt Davis (@nitzmahone) - Matt Davis (@nitzmahone)
''' '''
EXAMPLES = r''' EXAMPLES = r'''
# Unconditionally reboot the machine with all defaults - name: Reboot the machine with all defaults
- win_reboot: win_reboot:
# Apply updates and reboot if necessary - name: Reboot a slow machine that might have lots of updates to apply
- win_updates: win_reboot:
register: update_result
- win_reboot:
when: update_result.reboot_required
# Reboot a slow machine that might have lots of updates to apply
- win_reboot:
reboot_timeout: 3600 reboot_timeout: 3600
# Install a Windows feature and reboot if necessary
- name: Install IIS Web-Server
win_feature:
name: Web-Server
register: iis_install
- name: Reboot when Web-Server feature requires it
win_reboot:
when: iis_install.reboot_required
# One way to ensure the system is reliable, is to add a delay before running the next task
- name: Reboot a machine that takes time to settle after being booted
win_reboot:
post_reboot_delay: 120
# Alternatively, you can set WinRM to a delayed startup
- name: Ensure WinRM starts when the system has settled and is ready to work reliably
win_service:
name: WinRM
start_mode: delayed
# 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
win_reboot:
test_command: 'exit (Get-Service -Name Netlogon).Status -ne "Running"'
''' '''
RETURN = r''' RETURN = r'''