Port check script: test a list of host:port pairs with timeouts

After a firewall change, a deployment or a network outage, you want one answer per service: can I reach it? This script takes any number of host:port pairs, gives each one a short timeout and prints a result you can read at a glance. It uses only bash and the timeout command, so it runs on any Linux box; on macOS install coreutils once for gtimeout.

The script

#!/usr/bin/env bash
set -uo pipefail

TIMEOUT=${TIMEOUT:-3}

usage() {
  echo "usage: $0 host:port [host:port ...]" >&2
  echo "       $0 -f targets.txt      (one host:port per line, # comments allowed)" >&2
  echo "  TIMEOUT=5 $0 ...            seconds to wait per target (default 3)" >&2
  exit 2
}

if command -v timeout >/dev/null 2>&1; then
  TO=timeout
elif command -v gtimeout >/dev/null 2>&1; then
  TO=gtimeout
else
  echo "need the timeout command (on macOS: brew install coreutils)" >&2
  exit 2
fi

targets=()
if [[ ${1:-} == "-f" ]]; then
  [[ -r ${2:-} ]] || usage
  while read -r line; do
    line=${line%%#*}
    line=${line//[[:space:]]/}
    [[ -n $line ]] && targets+=("$line")
  done < "$2"
else
  targets=("$@")
fi
(( ${#targets[@]} > 0 )) || usage

failed=0
printf '%-40s %-8s %s\n' TARGET RESULT DETAIL
for t in "${targets[@]}"; do
  host=${t%:*}
  port=${t##*:}
  if [[ -z $host || -z $port || ! $port =~ ^[0-9]+$ ]]; then
    printf '%-40s %-8s %s\n' "$t" SKIP "expected host:port"
    continue
  fi
  start=$(date +%s%N 2>/dev/null || date +%s)
  "$TO" "$TIMEOUT" bash -c "exec 3<>/dev/tcp/$host/$port" 2>/dev/null
  rc=$?
  end=$(date +%s%N 2>/dev/null || date +%s)
  if [[ ${#start} -gt 10 ]]; then
    ms=$(( (end - start) / 1000000 ))
    took="${ms} ms"
  else
    took="$(( end - start )) s"
  fi
  case $rc in
    0)   printf '%-40s %-8s %s\n' "$t" OPEN "$took" ;;
    124) printf '%-40s %-8s %s\n' "$t" TIMEOUT "no answer within ${TIMEOUT}s (firewall, wrong address or host down)"; failed=$((failed + 1)) ;;
    *)   printf '%-40s %-8s %s\n' "$t" CLOSED "refused or unreachable after $took (nothing listening, or name did not resolve)"; failed=$((failed + 1)) ;;
  esac
done

echo
if (( failed > 0 )); then
  echo "RESULT: $failed of ${#targets[@]} targets not reachable"
  exit 1
fi
echo "RESULT: all ${#targets[@]} targets reachable"

How to use it

chmod +x portcheck.sh
./portcheck.sh example.com:443 192.0.2.10:22 192.0.2.10:5432
TIMEOUT=5 ./portcheck.sh db.internal:5432

cat > targets.txt <<'EOF'
# production
web1.example.com:443
web1.example.com:22
db1.internal:5432   # PostgreSQL
EOF
./portcheck.sh -f targets.txt

TARGET                                   RESULT   DETAIL
example.com:443                          OPEN     41 ms
192.0.2.10:22                            OPEN     12 ms
192.0.2.10:5432                          CLOSED   refused or unreachable after 11 ms (nothing listening, or name did not resolve)
10.9.9.9:80                              TIMEOUT  no answer within 3s (firewall, wrong address or host down)

RESULT: 2 of 4 targets not reachable

How it works

• /dev/tcp/HOST/PORT is a bash feature: opening it as a file makes bash connect over TCP. No nc, nmap or telnet needed.
• timeout 3 bash -c ... kills the attempt after 3 seconds and returns exit code 124, which the script reports as TIMEOUT. A fast failure (connection refused, unknown host) returns another non-zero code, reported as CLOSED. This distinction mirrors the two error messages explained in the fix article in this topic.
• The exit status is 1 if anything was unreachable, so you can use it in a deployment pipeline or a monitoring check.
• IPv6 literals need brackets in the host:port form and are not handled; use a DNS name instead.

Official documentation

• Bash manual: redirections, including /dev/tcp
• GNU coreutils: timeout