Health-Check URLs
Problem statement
Check a list of URLs, print each one's HTTP status, and exit with a failure code if any of them is not healthy, with a timeout so a dead host cannot hang the script. This is the core of smoke tests after a deploy, cron health checks and CI gates.
The script starts a small test web server on 127.0.0.1 (python3 -m http.server) serving two pages, /health and /index.html, and also picks a port where nothing listens. Port numbers change every run, so the output shows web and dead-port instead.
- Check two healthy URLs and print the result and exit code.
- Check a healthy URL, a missing page (404) and the dead port, list the failures, and print the exit code.
Expected output:
== healthy endpoints only ==OK 200 web/healthOK 200 web/index.htmlall 2 checks passedexit code: 0== with a missing page and a dead port ==OK 200 web/healthFAIL 404 web/missingFAIL 000 dead-port/health2 of 3 checks failed: web/missing dead-port/healthexit code: 1Hints
curl -s -o /dev/null -w '%{http_code}' --max-time 2 URL prints only the status code. When it cannot connect at all, it prints 000 and exits non-zero, so add || true to keep the code.Approach
Optimal: curl -w http_code with a timeout
Covers: HTTP status codes, curl -s -o /dev/null -w '%{http_code}', --max-time, 000 for no connection, -f, -L, collecting failures in an array, exit codes for checks, cleaning up the test server with trap.
Strict mode, used on every page in this section. The second line, set -euo pipefail, makes bash stop on mistakes instead of carrying on:
| Option | Means |
|---|---|
-e |
exit as soon as a command fails (with some exceptions, see Handle Command Failures) |
-u |
treat an unset variable as an error, instead of silently using empty text |
-o pipefail |
a pipeline fails if any command in it fails, not just the last one |
Put it right after the shebang line #!/usr/bin/env bash in every script you write.
A health check has three parts. A request, a time limit, and a clear yes or no:
OK"]:::green C --> E["404, 5xx
FAIL"]:::red C --> Z["000
no answer, FAIL"]:::red classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,stroke-width:2px classDef yellow fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px classDef green fill:#d1fae5,stroke:#059669,color:#064e3b,stroke-width:2px classDef red fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,stroke-width:2px classDef purple fill:#ede9fe,stroke:#7c3aed,color:#4c1d95,stroke-width:2px classDef gray fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:2px linkStyle default stroke:#94a3b8,stroke-width:2px
Getting just the status code. By default curl prints the page. These options turn it into a checker:
| Option | Does |
|---|---|
-s |
silent: no progress bar or error text |
-o /dev/null |
throw the page body away |
-w '%{http_code}' |
after the request, print the HTTP status code |
--max-time 2 |
give up after 2 seconds in total |
What the codes mean.
| Code | Means | Healthy? |
|---|---|---|
| 200 | OK | yes |
| 301, 302 | redirect elsewhere | follow with -L, or treat as a problem |
| 404 | not found | no: wrong path, or the app is missing a route |
| 500, 502, 503 | server or proxy error | no |
| 000 | no HTTP answer at all: refused, timeout, DNS failure | no |
000 is not a real HTTP code; it is curl saying nothing answered. curl also exits non-zero then (7 for "could not connect", 28 for a timeout), which would stop a set -e script, so || true keeps the 000 and lets the check report it.
Collect, then decide. The check does not stop at the first failure. It records each failing URL in the failed array, prints a summary, and returns 1 if any failed. That gives a full picture in one run, and an exit code that cron, CI or a monitoring agent can act on.
to the failed array"]:::yellow F --> D{{"any failed?"}}:::yellow D --> X["return 1"]:::red D --> Y["return 0"]:::green classDef blue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,stroke-width:2px classDef yellow fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px classDef green fill:#d1fae5,stroke:#059669,color:#064e3b,stroke-width:2px classDef red fill:#fee2e2,stroke:#dc2626,color:#7f1d1d,stroke-width:2px classDef purple fill:#ede9fe,stroke:#7c3aed,color:#4c1d95,stroke-width:2px classDef gray fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:2px linkStyle default stroke:#94a3b8,stroke-width:2px
Clean up the test server. The server runs in the background, so trap ... EXIT stops it when the script ends, whatever happens. The { ...; } 2>/dev/null hides bash's notice about the stopped job.
Walking through the code. The # Setup: lines start the test server on a free port and wait until it answers, so skip past them.
status_ofreturns the code for one URL.check_allchecks each URL, printsOKorFAILwith a short label, collects the failures and returns 1 if there are any.- The healthy run passes with exit 0. The second run reports the 404 and the
000, and exits 1.
Edge cases. Only test URLs you own; never point a test at production or other people's sites. A 200 from a cache or load balancer does not prove the app behind it works, so health endpoints should check what really matters, like the database connection. With many URLs, run checks in parallel, as in the follow-up.
#!/usr/bin/env bash
set -euo pipefail
# Setup: serve two pages from a test web server on a free port on 127.0.0.1, and pick a dead port
cd "$(mktemp -d)"
mkdir site && echo ok > site/health && echo hi > site/index.html
free_port() { python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1])'; }
port=$(free_port); dead=$(free_port)
python3 -m http.server "$port" --bind 127.0.0.1 --directory site > server.log 2>&1 &
server=$!
trap '{ kill "$server"; wait "$server"; } 2>/dev/null || true' EXIT
for _ in $(seq 1 50); do curl -s -o /dev/null --max-time 1 "http://127.0.0.1:$port/" && break; sleep 0.1; done
status_of() { curl -s -o /dev/null -w '%{http_code}' --max-time 2 "$1" || true; }
check_all() {
local failed=() url code label
for url in "$@"; do
code=$(status_of "$url")
label=${url#http://}; label=${label/127.0.0.1:$port/web}; label=${label/127.0.0.1:$dead/dead-port}
if [[ $code == 200 ]]; then
echo "OK $code $label"
else
echo "FAIL $code $label"
failed+=("$label")
fi
done
if (( ${#failed[@]} > 0 )); then
echo "${#failed[@]} of $# checks failed: ${failed[*]}"
return 1
fi
echo "all $# checks passed"
}
echo "== healthy endpoints only =="
check_all "http://127.0.0.1:$port/health" "http://127.0.0.1:$port/index.html" && echo "exit code: 0"
echo "== with a missing page and a dead port =="
check_all "http://127.0.0.1:$port/health" "http://127.0.0.1:$port/missing" \
"http://127.0.0.1:$dead/health" || echo "exit code: $?"RecapThe whole problem in a few lines, for the night before
- Spot it: "check these URLs", "fail the deploy if any is down"
- Idea:
curl -s -o /dev/null -w '%{http_code}' --max-time 2, collect failures,return 1if any - Cost: one request per URL, at most the timeout each
- Trap: no timeout, so one dead host hangs the script; or
set -estopping on curl's error before the report
Interview follow-ups
Check the URLs in parallel and still print the results in the input order.
Start each check in the background and write its result to a numbered file:
i=0; for url in "$@"; do status_of "$url" > "res.$i" & i=$((i + 1)); done; wait. Then loop over the numbers in order and readres.0,res.1and so on, so the report keeps the input order even though checks finished in any order. With many URLs, limit how many run at once withxargs -P 8. The total time drops from the sum of all checks to about the slowest one.
Frequently asked questions
curl -f makes curl exit with 22 on any HTTP error (400 or above), which is the shortest check: curl -fs --max-time 2 "$url" > /dev/null || echo down. Reading the code with -w '%{http_code}' tells you which error it was, which is much more useful in a report or alert, and lets you accept other codes like 204 or 301 when they are fine. Use -f for quick yes or no checks, and the status code when people will read the result.
-L tells curl to follow redirects (301, 302, 307) to the final page and report that page's status. Without it, a redirect shows as 301 or 302, which this script counts as a failure. For checking a site the way a browser sees it, -L is right. For checking a specific health endpoint, a redirect usually means something is misconfigured, such as HTTP being sent to HTTPS, so it is often better to see it.
Without one, a host that accepts the connection but never answers, or a firewall that silently drops packets, makes curl wait for minutes. One bad URL then holds up every check after it, and a cron job can pile up copies of itself. --max-time caps the whole request, and --connect-timeout caps just the connection step. Pick limits a bit above the normal response time, for example 2 to 5 seconds for an internal health endpoint.