wait_for - Waits for a condition before continuing

Synopsis

Parameters

Parameter Choices/Defaults Comments
active_connection_states
(added in 2.3)
 Default:
[u'ESTABLISHED', u'FIN_WAIT1', u'FIN_WAIT2', u'SYN_RECV', u'SYN_SENT', u'TIME_WAIT']
The list of TCP connection states which are counted as active connections.
connect_timeout Default:
5
Maximum number of seconds to wait for a connection to happen before closing and retrying.
delay Default:
0
Number of seconds to wait before starting to poll.
exclude_hosts
(added in 1.8)
List of hosts or IPs to ignore when looking for active TCP connections for drained state.
host Default:
127.0.0.1
A resolvable hostname or IP address to wait for.
msg
(added in 2.4)
This overrides the normal error message from a failure to meet the required conditions.
path
(added in 1.4)
Path to a file on the filesystem that must exist before continuing.
path and port are mutually exclusive parameters.
port
Port number to poll.
path and port are mutually exclusive parameters.
search_regex
(added in 1.4)
Can be used to match a string in either a file or a socket connection.
Defaults to a multiline regex.
sleep
(added in 2.3)
 Default:
1
Number of seconds to sleep between checks, before 2.3 this was hardcoded to 1 second.
state
    Choices:
  • absent
  • drained
  • present
  • started ←
  • stopped
Either present, started, or stopped, absent, or drained.
When checking a port started will ensure the port is open, stopped will check that it is closed, drained will check for active connections.
When checking for a file or a search string present or started will ensure that the file or string is present before continuing, absent will check that file is absent or removed.
timeout Default:
300
Maximum number of seconds to wait for, when used with another condition it will force an error.
When used without other conditions it is equivalent of just sleeping.

Notes

Note

  • The ability to use search_regex with a port connection was added in 1.7.
  • Prior to 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
  • Prior to 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
  • Under some circumstances when using mandatory access control, a path may always be treated as being absent even if it exists, but can’t be modified or created by the remote user either.
  • When waiting for a path, symbolic links will be followed. Many other modules that manipulate files do not follow symbolic links, so operations on the path using other modules may not work exactly as expected.
  • This module is also supported for Windows targets.
  • See also wait_for_connection

Examples

- name: sleep for 300 seconds and continue with play
  wait_for: timeout=300
  delegate_to: localhost

- name: Wait for port 8000 to become open on the host, don't start checking for 10 seconds
  wait_for:
    port: 8000
    delay: 10

- name: Waits for port 8000 of any IP to close active connections, don't start checking for 10 seconds
  wait_for:
    host: 0.0.0.0
    port: 8000
    delay: 10
    state: drained

- name: Wait for port 8000 of any IP to close active connections, ignoring connections for specified hosts
  wait_for:
    host: 0.0.0.0
    port: 8000
    state: drained
    exclude_hosts: 10.2.1.2,10.2.1.3

- name: Wait until the file /tmp/foo is present before continuing
  wait_for:
    path: /tmp/foo

- name: Wait until the string "completed" is in the file /tmp/foo before continuing
  wait_for:
    path: /tmp/foo
    search_regex: completed

- name: Wait until the lock file is removed
  wait_for:
    path: /var/lock/file.lock
    state: absent

- name: Wait until the process is finished and pid was destroyed
  wait_for:
    path: /proc/3466/status
    state: absent

- name: Output customized message when failed
  wait_for:
    path: /tmp/foo
    state: present
    msg: Timeout to find file /tmp/foo

# Don't assume the inventory_hostname is resolvable and delay 10 seconds at start
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
  wait_for:
    port: 22
    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
    search_regex: OpenSSH
    delay: 10
  connection: local

# Same as above but you normally have ansible_connection set in inventory, which overrides 'connection'
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
  wait_for:
    port: 22
    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
    search_regex: OpenSSH
    delay: 10
  vars:
    ansible_connection: local

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Jeroen Hoekx (@jhoekx)
  • John Jarvis (@jarv)
  • Andrii Radyk (@AnderEnder)

Hint

If you notice any issues in this documentation you can edit this document to improve it.