startup.sh

Overview

`startup.sh` is a shell script designed to act as a **startup readiness probe** for a daemon process running on a local server (presumably part of a blockchain or networking application). Its primary function is to check whether the daemon is operational and ready to accept network connections by performing a sequence of health checks. It accomplishes this by querying the daemon’s JSON-RPC endpoints to verify:

• Whether the daemon is currently listening for network connections.

• Whether the daemon has any active peers connected.

If the daemon is ready (listening and has peers), the script exits successfully (`exit 0`), otherwise it exits with a failure status (`exit 1`). This can be useful in container orchestration environments like Kubernetes, where readiness probes determine if a pod is ready to serve traffic.

Additionally, the script supports a "disable" feature: if a specific file exists (`/data/disable_startup`), it will skip all checks and immediately signal readiness.

Detailed Explanation

Script Execution Flow

1. Disable Check

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

   • Checks if the file /data/disable_startup exists.

   • If it does, the script prints a message and exits with success, effectively disabling startup readiness checks.

2. Daemon Status Queries

   NET_LISTENING=$(curl -sf -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' -H 'Content-Type: application/json' http://localhost:9650/ext/bc/C/rpc) || exit 1
   INFO_PEERS=$(curl -sf -d '{"jsonrpc":"2.0","method":"info.peers","params":[],"id":1}' -H 'Content-Type: application/json' http://localhost:9650/ext/info) || exit 1
   

   • Sends two JSON-RPC POST requests to specific endpoints on localhost port 9650:

     • net_listening method on /ext/bc/C/rpc to check if the daemon is listening.

     • info.peers method on /ext/info to retrieve peer information.

   • Uses curl with -s (silent) and -f (fail silently on HTTP errors) flags.

   • If either request fails, the script exits immediately with failure (exit 1).

3. Parsing JSON Results

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

   • Uses jq to parse the JSON responses.

   • Extracts:

     • LISTENING as a boolean (true or false) from .result of the net_listening response.

     • NUM_PEERS as an integer from .result.numPeers of the info.peers response.

4. Readiness Decision Logic

   if [[ $LISTENING == true ]]; then
     if (( $NUM_PEERS > 0 )); then
       echo "daemon is listening, with $NUM_PEERS peers"
       exit 0
     fi
   
     echo "daemon is listening, but has no peers"
     exit 1
   fi
   
   echo "daemon is not listening"
   exit 1
   

   • If the daemon is listening and has at least one peer, the script exits successfully.

   • If listening but no peers, treat as not ready (exit 1).

   • If not listening, also treat as not ready.

Usage Example

1. Place startup.sh on the server where the daemon runs.

2. Ensure it has execute permissions:

   chmod +x startup.sh
   

3. Run manually to test daemon readiness:

   ./startup.sh
   

4. In Kubernetes or other orchestrators, configure this script as a readiness probe command to inform the system when the daemon is ready to accept traffic.

Important Implementation Details

• Disable Mechanism: The presence of /data/disable_startup file overrides all checks, allowing operators to bypass readiness checks temporarily.

• JSON-RPC Protocol: The script uses JSON-RPC 2.0 method calls via HTTP POST to query the daemon status.

• Error Handling: Uses curl with fail flags and exits immediately on request failure, preventing false positives.

• JSON Parsing: Leverages jq utility to parse responses, assuming it is installed on the host.

• Exit Codes: Uses standard Unix conventions where 0 means ready/success and 1 means not ready/failure.

Interaction with Other System Components

• Daemon on localhost:9650: The script expects the daemon to expose JSON-RPC HTTP endpoints on port 9650.

• Orchestration Systems: Typically invoked by container orchestrators (Kubernetes, Docker Swarm) as a readiness probe script.

• File System: Checks the existence of /data/disable_startup to enable/disable readiness checks.

• Dependencies: Requires curl and jq to be installed on the system.

Mermaid Flowchart

The following flowchart summarizes the logical workflow of the `startup.sh` script:

flowchart TD
    A[Start] --> 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]
    E -- Fail --> F[Exit 1]
    E -- Success --> G[Send JSON-RPC info.peers request]
    G -- Fail --> F
    G -- Success --> H[Parse LISTENING and NUM_PEERS]
    H --> I{Is LISTENING true?}
    I -- No --> J[Print "daemon is not listening"]
    J --> F
    I -- Yes --> K{Is NUM_PEERS > 0?}
    K -- Yes --> L[Print "daemon is listening, with NUM_PEERS peers"]
    L --> D
    K -- No --> M[Print "daemon is listening, but has no peers"]
    M --> F

Summary

`startup.sh` is a minimalistic yet effective shell script that serves as a startup readiness probe by:

• Optionally disabling checks via a sentinel file.

• Querying daemon readiness via JSON-RPC API calls.

• Parsing JSON responses to verify listening and peer connectivity.

• Reporting readiness state via exit codes and messages.

It integrates seamlessly into containerized environments to ensure the daemon is fully ready before accepting workload or traffic.

End of Documentation for startup.sh