wait-for-it.sh

Overview

wait-for-it.sh is a lightweight Bash script designed to wait for a specific TCP host and port to become available before proceeding. This utility is commonly used in deployment scripts, container initialization, or automated workflows where services depend on other services being up and ready (such as databases, web servers, or message brokers).

The script attempts to establish a TCP connection to the given host and port, retrying every second until either the service responds (indicating availability) or a specified timeout period is reached. It provides options to customize the timeout duration and to suppress output messages.

Detailed Explanation

Script Purpose

Primary goal: Block execution until a TCP service on a specified host and port is reachable.
Use case: Ensures dependent services are ready before starting the next step in automation or orchestration.

Usage Summary

./wait-for-it.sh <host> <port> [options]

<host>: Hostname or IP address of the target service.
<port>: TCP port number to check.
[options]: Optional flags to modify behavior.

Command Line Arguments and Options

Argument/Option	Description	Default
`host`	Hostname or IP to check for TCP availability	(required)
`port`	TCP port number to check on the host	(required)
`-t`, `--timeout`	Number of seconds to wait before giving up	15 seconds
`-q`, `--quiet`	Suppress output messages (only exit code returned)	Output enabled

Script Workflow

Parse positional arguments: The first two arguments are host and port.
Parse options:
- -t or --timeout to set maximum wait time.
- -q or --quiet to suppress messages.
Attempt to connect:
- Loop every second up to the timeout limit.
- Use nc -z (netcat in zero-I/O mode) to check if the TCP port is open.
Success:
- If connection succeeds, print a success message (unless quiet) and exit with code 0.
Failure:
- If timeout expires without success, print failure message and exit with code 1.

Implementation Details

Host and port parsing: The script expects the first two arguments to be the host and port. It shifts these off the argument list to process flags.
Option parsing: Uses a while loop and case statement to handle -t/--timeout and -q/--quiet.
Timeout control: Uses a simple for loop with seq counting from 1 to the timeout value.
Connection check: Uses nc -z "$host" "$port" which attempts to open a TCP connection without sending data.
Output: Uses Unicode checkmark (✔) and cross (✖) symbols for clear status messages.
Exit codes: 0 indicates success (port is available), 1 indicates failure (timeout).

Functions / Methods

This script is a procedural shell script and does not define functions or classes.

Parameters

Parameter	Description
`$1`	Hostname or IP to check
`$2`	TCP port number
`$3...`	Optional flags (`-t`, `-q`)

Return Values (Exit Codes)

Exit Code	Meaning
`0`	Target host and port is available
`1`	Timeout reached without availability

Usage Examples

Basic usage (wait with default timeout 15 seconds)

./wait-for-it.sh example.com 3306

Waits up to 15 seconds for TCP port 3306 on example.com to be available.

Specify a custom timeout (e.g., 30 seconds)

./wait-for-it.sh example.com 3306 -t 30

Waits up to 30 seconds before timing out.

Quiet mode (no output, just exit code)

./wait-for-it.sh example.com 3306 -q

Returns exit code 0 if available, 1 if timeout, but prints no messages.

Interaction with Other System Components

This script is typically invoked by deployment automation tools, container entrypoint scripts, or CI/CD pipelines to ensure services are ready before proceeding.
It relies on the nc (netcat) utility being installed on the host machine.
By waiting for services to become available, it helps coordinate startup order of dependent services in distributed environments.
It does not modify services or network configurations; it only checks connectivity.

Summary

wait-for-it.sh is a simple, effective utility for blocking script execution until a specific TCP service is ready. Its minimal dependencies and straightforward interface make it an excellent choice for orchestrating service readiness in shell scripts, containers, and CI pipelines.

Visual Diagram: Flowchart of Main Workflow

flowchart TD
    Start([Start]) --> ParseArgs[Parse host & port arguments]
    ParseArgs --> ParseOptions{Options present?}
    ParseOptions -->|Yes| ProcessOptions[Process -t and -q flags]
    ParseOptions -->|No| BeginLoop[Begin connection check loop]

    ProcessOptions --> BeginLoop
    BeginLoop --> LoopCondition{Timeout reached?}
    LoopCondition -->|No| AttemptConnect[Try nc -z to host:port]
    AttemptConnect --> CheckSuccess{Connection successful?}
    CheckSuccess -->|Yes| SuccessMsg[Print success message (unless quiet)]
    SuccessMsg --> ExitSuccess[Exit 0]
    CheckSuccess -->|No| Sleep1[Sleep 1 second]
    Sleep1 --> LoopCondition
    LoopCondition -->|Yes| TimeoutMsg[Print timeout message]
    TimeoutMsg --> ExitFail[Exit 1]

End of Documentation for wait-for-it.sh