Skip to main content
Bash and Linux

Health-Check URLs

mediumBash scripts and automation Must-do

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.

  1. Check two healthy URLs and print the result and exit code.
  2. Check a healthy URL, a missing page (404) and the dead port, list the failures, and print the exit code.

Expected output:

TEXT
== healthy endpoints only ==
OK 200 web/health
OK 200 web/index.html
all 2 checks passed
exit code: 0
== with a missing page and a dead port ==
OK 200 web/health
FAIL 404 web/missing
FAIL 000 dead-port/health
2 of 3 checks failed: web/missing dead-port/health
exit code: 1

Hints

Hint 1: 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:

%%{init: {"flowchart": {"padding": 18, "nodeSpacing": 30, "rankSpacing": 40, "htmlLabels": true}, "themeVariables": {"fontSize": "18px"}}}%% flowchart TB R(["curl with --max-time"]):::purple --> C{{"status code"}}:::yellow C --> OK["200
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.

%%{init: {"flowchart": {"padding": 18, "nodeSpacing": 30, "rankSpacing": 40, "htmlLabels": true}, "themeVariables": {"fontSize": "18px"}}}%% flowchart TB U["each URL"]:::blue --> CK(["check"]):::purple CK --> F["add failures
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.

  1. status_of returns the code for one URL.
  2. check_all checks each URL, prints OK or FAIL with a short label, collects the failures and returns 1 if there are any.
  3. 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 1 if any
  • Cost: one request per URL, at most the timeout each
  • Trap: no timeout, so one dead host hangs the script; or set -e stopping 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 read res.0, res.1 and 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 with xargs -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.