Web Service Health Check Script

1. The Basic Health Check: Using curl

The primary tool for making web requests from the command line is curl. We can use it to fetch a web page, but for a health check, we're not interested in the page's content. We only care about the HTTP status code the server returns. A 200 OK status means success, while other codes like 404 Not Found or 500 Internal Server Error indicate a problem.

As the resource explains, the command is:
curl -s -o /dev/null -w "%{http_code}" <URL>

• -s: Silent mode. Don't show progress meters or error messages.
• -o /dev/null: Redirect output. Send the actual page content (the response body) to /dev/null, which is a special file that discards everything sent to it.
• -w "%{http_code}": Write-out. After the transfer, print the HTTP response code to standard output.

Let's turn this into a very basic script. Create a new file named health_check.sh and make it executable (chmod +x health_check.sh).

#!/bin/bash

# A public API endpoint for testing
TARGET_URL="https://jsonplaceholder.typicode.com/posts/1"

echo "Checking status of ${TARGET_URL}..."

# Get the HTTP status code
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${TARGET_URL}")

# Check if the status code is 200
if [ "${HTTP_CODE}" -eq 200 ]; then
  echo "SUCCESS: Service is up and running."
else
  echo "FAILURE: Service is down or returned an error. HTTP Code: ${HTTP_CODE}"
fi

Run this script (./health_check.sh). It should report that the service is running. Now, try changing the URL to a non-existent one, like https://jsonplaceholder.typicode.com/invalid, and run it again. You should see a 404 error.

2. Building a More Informative Script

A simple "up" or "down" message is a good start, but we can make our script much more useful by providing specific feedback based on the type of error. In the world of web services, a 404 Not Found error means something very different from a 500 Internal Server Error.

Let's enhance our script to handle different categories of HTTP status codes.

Let's also make our script more flexible by accepting the URL as a command-line argument instead of hardcoding it. Here is the improved version of health_check.sh:

#!/bin/bash

# 1. Validate input
if [ -z "$1" ]; then
  echo "Usage: $0 <URL>"
  exit 1
fi

TARGET_URL=$1

echo "Checking status of ${TARGET_URL}..."

# 2. Get the HTTP status code
# Note: curl will return '000' if it can't connect (e.g., DNS error, host down)
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${TARGET_URL}")

# 3. Interpret the code
if [ "${HTTP_CODE}" -ge 200 ] && [ "${HTTP_CODE}" -lt 300 ]; then
  echo "SUCCESS: Service is up and running (HTTP ${HTTP_CODE})."
  exit 0
elif [ "${HTTP_CODE}" -ge 400 ] && [ "${HTTP_CODE}" -lt 500 ]; then
  echo "CLIENT ERROR: Check the URL or permissions (HTTP ${HTTP_CODE})."
  exit 1
elif [ "${HTTP_CODE}" -ge 500 ] && [ "${HTTP_CODE}" -lt 600 ]; then
  echo "SERVER ERROR: The service is having issues on its end (HTTP ${HTTP_CODE})."
  exit 1
else
  echo "FAILURE: Could not connect or received an unexpected code (HTTP ${HTTP_CODE})."
  exit 1
fi

Key Improvements:

• Argument Validation: The script now requires a URL as an argument, making it reusable.
• Status Code Ranges: Instead of checking for just 200, we check for ranges. This is more robust, as any 2xx code indicates success. Similarly, 4xx codes are client errors, and 5xx codes are server errors.
• Exit Codes: The script now exits with 0 on success and 1 on failure. This is a crucial practice in scripting, as it allows other scripts or automation tools (like a CI/CD pipeline) to know whether this check succeeded or failed.

3. Making the Script Production-Ready

Our script is much better, but there are two common real-world failure scenarios it doesn't handle well:

1. Network Unresponsiveness: What if the server we're checking is frozen and never responds? Our curl command could hang indefinitely.
2. Local Connectivity Issues: What if the service is perfectly fine, but our own machine has lost its internet connection? Our script would incorrectly report that the service is down.

Let's address these by adding timeouts and a pre-flight connectivity check.

Let's integrate these two concepts into our final script.

Final Health Check Script

Here is the complete health_check.sh script incorporating these robustness checks.

#!/bin/bash

# --- 1. Validate Input ---
if [ -z "$1" ]; then
  echo "Usage: $0 <URL>"
  exit 1
fi

TARGET_URL=$1
# Set a timeout for the curl command (in seconds)
TIMEOUT=10

# --- 2. Pre-flight Check: Internet Connectivity ---
# Ping a reliable public DNS server. -c 1 sends one packet, -W 1 sets a 1-sec timeout.
if ! ping -c 1 -W 1 8.8.8.8 &> /dev/null; then
  echo "NETWORK ERROR: Could not reach the internet. Please check your connection."
  exit 1
fi

echo "Internet connectivity OK. Checking status of ${TARGET_URL}..."

# --- 3. Perform Health Check with Timeout ---
HTTP_CODE=$(curl --max-time ${TIMEOUT} -s -o /dev/null -w "%{http_code}" "${TARGET_URL}")
CURL_EXIT_CODE=$?

# --- 4. Interpret Results ---
# Check curl's exit code first. A non-zero code indicates a curl-level error (e.g., timeout, DNS lookup failure).
# 28 is the exit code for a timeout.
if [ ${CURL_EXIT_CODE} -ne 0 ]; then
    if [ ${CURL_EXIT_CODE} -eq 28 ]; then
        echo "FAILURE: Connection timed out after ${TIMEOUT} seconds."
    else
        echo "FAILURE: curl command failed with exit code ${CURL_EXIT_CODE}. Unable to connect."
    fi
    exit 1
fi

# If curl succeeded, check the HTTP code
if [ "${HTTP_CODE}" -ge 200 ] && [ "${HTTP_CODE}" -lt 300 ]; then
  echo "SUCCESS: Service is up and running (HTTP ${HTTP_CODE})."
  exit 0
elif [ "${HTTP_CODE}" -ge 400 ] && [ "${HTTP_CODE}" -lt 500 ]; then
  echo "CLIENT ERROR: Check the URL or permissions (HTTP ${HTTP_CODE})."
  exit 1
elif [ "${HTTP_CODE}" -ge 500 ] && [ "${HTTP_CODE}" -lt 600 ]; then
  echo "SERVER ERROR: The service is having issues on its end (HTTP ${HTTP_CODE})."
  exit 1
else
  # Includes the '000' code from curl when it connects but gets no HTTP response
  echo "FAILURE: Could not connect or received an unexpected code (HTTP ${HTTP_CODE})."
  exit 1
fi

Final Improvements:

• Connectivity Check: The script now pings 8.8.8.8 (Google's public DNS) to make sure there's a general internet connection before proceeding.
• Timeout: The curl command will now give up after 10 seconds, preventing the script from hanging.
• curl Exit Code: We now also check the exit code of curl itself ($?). This allows us to specifically detect low-level errors like a connection timeout (exit code 28) before we even look at the HTTP status code.

Testing the Final Script

1. Success Case: ./health_check.sh https://www.google.com
2. Server Error Case: ./health_check.sh http://httpstat.us/503 (This site returns a 503 error).
3. Client Error Case: ./health_check.sh https://www.google.com/nonexistentpage
4. Timeout Case: ./health_check.sh http://httpstat.us/200?sleep=15000 (This will take 15 seconds, exceeding our 10-second timeout).
5. Connectivity Case: Disconnect your computer from the network and run any check. You should see the "NETWORK ERROR" message.

Conclusion

Congratulations! You have successfully built a robust health-checking script, a fundamental tool in any DevOps engineer's arsenal. This project wraps up our journey into Bash automation by combining system commands, networking, error handling, and robust scripting practices.

Key Takeaways:

• curl is the go-to command-line tool for interacting with web services.
• Checking HTTP status codes is the primary method for basic service health monitoring.
• A production-ready script must be robust: it should handle timeouts, network failures, and different classes of errors gracefully.
• Using script exit codes (0 for success, non-zero for failure) is essential for integrating your scripts into larger automation workflows.

Next Up: Python for DevOps

You have built a fantastic foundation with Linux and Bash. You can navigate the system, manage resources, and automate a wide range of administrative tasks.

While Bash is the undisputed champion for orchestrating command-line tools, some tasks become complex. When you need to work with structured data like JSON, interact with complex APIs, or write more intricate logic, a general-purpose programming language is often a better choice.

This is the perfect time to transition to our next module: Python for DevOps Engineers. Python's clear syntax and powerful libraries have made it the de facto language for cloud automation, API interaction, and configuration management. We will start by learning the basics of Python and quickly see how it can make tasks like today's health check even more powerful and easier to write.