# 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`.
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.
**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\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
```