You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

ansible.builtin.wait_for_connection module – Waits until remote system is reachable/usable

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name wait_for_connection even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 2.3: of ansible.builtin

Synopsis

• Waits for a total of timeout seconds.

• Retries the transport connection after a timeout of connect_timeout.

• Tests the transport connection every sleep seconds.

• This module makes use of internal ansible transport (and configuration) and the ping/win_ping module to guarantee correct end-to-end functioning.

• This module is also supported for Windows targets.

Note

This module has a corresponding action plugin.

Parameters

Parameter	Comments
connect_timeout integer	Maximum number of seconds to wait for a connection to happen before closing and retrying. Default: 5
delay integer	Number of seconds to wait before starting to poll. Default: 0
sleep integer	Number of seconds to sleep between checks. Default: 1
timeout integer	Maximum number of seconds to wait for. Default: 600

Attributes

Attribute	Support	Description
action	Support: full	Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller
async	Support: none	Supports being used with the async keyword
bypass_host_loop	Support: none	Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations Conditionals will work as if run_once is being used, variables used will be from the first available host This action will not work normally outside of lockstep strategies
check_mode	Support: none	Can run in check_mode and return changed status prediction withought modifying target
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platforms: all As long as there is a connection plugin	Target OS/families that can be operated against

See Also

See also

ansible.builtin.wait_for

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

ansible.windows.win_wait_for

The official documentation on the ansible.windows.win_wait_for module.

community.windows.win_wait_for_process

The official documentation on the community.windows.win_wait_for_process module.

Examples

- name: Wait 600 seconds for target connection to become reachable/usable
  wait_for_connection:

- name: Wait 300 seconds, but only start checking after 60 seconds
  wait_for_connection:
    delay: 60
    timeout: 300

# Wake desktops, wait for them to become ready and continue playbook
- hosts: all
  gather_facts: no
  tasks:
  - name: Send magic Wake-On-Lan packet to turn on individual systems
    wakeonlan:
      mac: '{{ mac }}'
      broadcast: 192.168.0.255
    delegate_to: localhost

  - name: Wait for system to become reachable
    wait_for_connection:

  - name: Gather facts for first time
    setup:

# Build a new VM, wait for it to become ready and continue playbook
- hosts: all
  gather_facts: no
  tasks:
  - name: Clone new VM, if missing
    vmware_guest:
      hostname: '{{ vcenter_ipaddress }}'
      name: '{{ inventory_hostname_short }}'
      template: Windows 2012R2
      customization:
        hostname: '{{ vm_shortname }}'
        runonce:
        - powershell.exe -ExecutionPolicy Unrestricted -File C:\Windows\Temp\ConfigureRemotingForAnsible.ps1 -ForceNewSSLCert -EnableCredSSP
    delegate_to: localhost

  - name: Wait for system to become reachable over WinRM
    wait_for_connection:
      timeout: 900

  - name: Gather facts for first time
    setup:

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 connection to appear. Returned: always Sample: 23.1

Authors

• Dag Wieers (@dagwieers)

Collection links

Issue Tracker Repository (Sources) Communication