# ansible.builtin.wait_for
Waits for a condition before continuing

## Parameter
| Parameter           | Type    | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **connect_timeout** | integer | 5           | Maximum number of seconds to wait for a connection to happen before closing and retrying.                                                                                                                                                                                                                                                                                                                                                                                                   |
| **delay**           | integer | 0           | Number of seconds to wait before starting to poll.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **host**            | string  | "127.0.0.1" | A resolvable hostname or IP address to wait for.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **msg**             | string  | -           | This overrides the normal error message from a failure to meet the required conditions.                                                                                                                                                                                                                                                                                                                                                                                                     |
| **path**            | path    | -           | Path to a file on the filesystem that must exist before continuing. `path` and `port` are mutually exclusive parameters.                                                                                                                                                                                                                                                                                                                                                                    |
| **port**            | integer | -           | Port number to poll. `path` and `port` are mutually exclusive parameters.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **search_regex**    | string  | -           | Can be used to match a string in either a file or a socket connection.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **sleep**           | integer | 1           | Number of seconds to sleep between checks.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **timeout**         | integer | 300         | Maximum number of seconds to wait for, when used with another condition it will force an error.                                                                                                                                                                                                                                                                                                                                                                                             |
| **state**           | string  | "started"   | Either `present`, `started`, or `stopped`, `absent`, or `drained`. <br>When checking a port `started` will ensure the port is open, `stopped` will check that it is closed, `drained` will check for active connections. <br>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. <br>**Choices:** (`"absent"`, `"drained"`, `"present"`, `"started"`, `"stopped"`) |

## Return Values
| Value       | Type    | When   | Description                                      |
| ----------- | ------- | ------ | ------------------------------------------------ |
| **elapsed** | integer | always | The number of seconds that elapsed while waiting |

## Examples
```yaml
- name: Sleep for 300 seconds and continue with play
  ansible.builtin.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
  ansible.builtin.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
  ansible.builtin.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
  ansible.builtin.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
  ansible.builtin.wait_for:
    path: /tmp/foo

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

- name: Wait until regex pattern matches in the file /tmp/foo and print the matched group
  ansible.builtin.wait_for:
    path: /tmp/foo
    search_regex: completed (?P<task>\w+)
  register: waitfor
- ansible.builtin.debug:
    msg: Completed {{ waitfor['match_groupdict']['task'] }}

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

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

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

# Do not 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"
  ansible.builtin.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"
  ansible.builtin.wait_for:
    port: 22
    host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
    search_regex: OpenSSH
    delay: 10
  vars:
    ansible_connection: local
```