startup.sh

Overview

`startup.sh` is a lightweight Bash startup probe script designed to check whether a daemon process, presumably an Ethereum JSON-RPC node or similar service, is actively listening for network requests on the local machine. The script determines readiness by sending a JSON-RPC request to the daemon’s HTTP interface and interpreting the response.

The script functions as a health check utility, commonly used in containerized or orchestrated environments (e.g., Kubernetes) to confirm that the service is operational before routing traffic to it. It also supports a simple override mechanism to disable the startup probe by the presence of a specific file.

Functionality and Workflow

1. Startup Probe Disable Check:
   The script first checks for the existence of a "disable probe" marker file (/data/disable_startup). If this file is present, the script outputs "startup probe disabled" and exits successfully (exit 0). This mechanism allows operators or other processes to skip the startup check if desired.

2. Send JSON-RPC net_listening Request:
   If the probe is not disabled, the script sends a POST request with the JSON-RPC payload {"jsonrpc":"2.0","method":"net_listening","params":[],"id":1} to http://localhost:8545. This endpoint is the default port for many Ethereum-compatible JSON-RPC services.

3. Parse Response:
   The script parses the JSON response using jq to extract the .result field, which indicates whether the daemon is listening (true or false).

4. Exit Status Based on Listening State:

   • If .result is true, the script prints "daemon is listening" and exits with success (exit 0).

   • If .result is false or if the request fails, it prints "daemon is not listening" and exits with failure (exit 1).

Detailed Explanation of Script Components

Variables

• DISABLE_STARTUP_PROBE

  • Type: String (file path)

  • Value: /data/disable_startup

  • Purpose: Path to a file that disables the startup probe check if it exists.

• NET_LISTENING

  • Type: String (JSON response)

  • Value: Result of the curl command calling the JSON-RPC endpoint.

  • Purpose: Holds the raw JSON response from the daemon.

• LISTENING

  • Type: String (true or false)

  • Value: Extracted .result field from the JSON response.

  • Purpose: Indicates whether the daemon is listening.

Main Logic (Step-by-Step)

if [[ -f "$DISABLE_STARTUP_PROBE" ]]; then
  echo "startup probe disabled"
  exit 0
fi

• Checks if the disable probe file exists.

• If yes, outputs a message and exits successfully.

NET_LISTENING=$(curl -sf -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' -H 'Content-Type: application/json' http://localhost:8545) || exit 1

• Makes a silent (-s) and fail-fast (-f) POST request.

• Sends a JSON-RPC request for the net_listening method.

• If curl fails (e.g., connection refused), the script exits with failure.

LISTENING=$(echo $NET_LISTENING | jq -r '.result')

• Uses jq to parse the .result field from the JSON response.

• Extracts the value true or false.

if [[ $LISTENING == true ]]; then
  echo "daemon is listening"
  exit 0
fi

echo "daemon is not listening"
exit 1

• If .result is true, prints success message and exits 0.

• Otherwise, prints failure message and exits 1.

Usage Example

This script is typically invoked by an orchestrator or as part of a container lifecycle management:

./startup.sh

• If the daemon is listening, the script returns exit code 0.

• If not, it returns exit code 1.

• If the disable file /data/disable_startup exists, it returns 0 immediately.

Important Implementation Details

• Health Check Endpoint:
  The script relies on the Ethereum JSON-RPC method net_listening which returns a boolean indicating if the node is actively listening for network connections.

• Silent and Fail-Fast Curl:
  The use of curl -sf ensures immediate failure on connection errors or non-2xx HTTP responses, allowing quick detection of unavailable daemons.

• JSON Parsing with jq:
  The script assumes jq is installed for parsing JSON. Without jq, the script would fail.

• Disable Mechanism:
  The presence of the /data/disable_startup file is a simple toggle to disable this startup probe, useful for manual overrides or special deployment modes.

Interaction with Other System Components

• Daemon Process (Ethereum or Compatible Node):
  The primary interaction is with the local daemon listening on port 8545. This script queries its JSON-RPC API to verify readiness.

• Orchestration/Container Management:
  This script is intended for integration as a startup probe or readiness check in container orchestrators like Kubernetes. The exit code signals the health status.

• File System:
  Checks the file /data/disable_startup for disabling the probe. This file can be managed by other components or administrators.

Visual Diagram: Flowchart of startup.sh Workflow

flowchart TD
    A[Start script] --> B{Does /data/disable_startup exist?}
    B -- Yes --> C[Print "startup probe disabled"]
    C --> D[Exit 0]
    B -- No --> E[Send JSON-RPC net_listening request to localhost:8545]
    E --> F{Did curl succeed?}
    F -- No --> G[Exit 1]
    F -- Yes --> H[Parse JSON response with jq]
    H --> I{Is .result true?}
    I -- Yes --> J[Print "daemon is listening"]
    J --> D
    I -- No --> K[Print "daemon is not listening"]
    K --> G

Summary

• startup.sh acts as a simple startup probe to verify if a local daemon is listening on port 8545.

• It can be disabled by a marker file.

• Uses JSON-RPC net_listening method to check daemon health.

• Outputs status messages and returns exit codes for integration with orchestration tools.

• Depends on curl and jq.

• The script is concise and efficient for container startup readiness verification.

This documentation should help developers, DevOps engineers, and system administrators understand the purpose, operation, and integration points of `startup.sh` within the overall system.