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 Ansible 2.3

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 without 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
  ansible.builtin.wait_for_connection:

- name: Wait 300 seconds, but only start checking after 60 seconds
  ansible.builtin.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
    community.general.wakeonlan:
      mac: '{{ mac }}'
      broadcast: 192.168.0.255
    delegate_to: localhost

  - name: Wait for system to become reachable
    ansible.builtin.wait_for_connection:

  - name: Gather facts for first time
    ansible.builtin.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
    community.vmware.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
    ansible.builtin.wait_for_connection:
      timeout: 900

  - name: Gather facts for first time
    ansible.builtin.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