SSI LogoSSI

Service Scripts

What is a Service Script?

A service script is a self-contained BASH script that performs a monitoring check and reports its status. Each service script:

  • Monitors a specific service, system component, or health check
  • Runs on a defined schedule via systemd timers
  • Outputs status in a standardized format
  • Is completely independent and transparent

Philosophy

The SSI Agent follows a core philosophy for service scripts:

"What you see is exactly what is going to be executed."

This means:

  1. No Magic — Scripts are executed exactly as written, with no hidden modifications
  2. Self-Contained — Each script contains everything it needs to run
  3. Transparent — Anyone can read the script and understand exactly what it does
  4. Independent — Scripts don't depend on the SSI Agent at runtime

Why BASH?

BASH was chosen for service scripts because:

  • Universal — Available on virtually all Linux systems
  • Native — No additional runtime or interpreter needed
  • Transparent — Easy to read, understand, and audit
  • Powerful — Can invoke any system command or tool
  • Portable — Scripts can be tested independently of the SSI Agent

Anatomy of a Service Script

Every service script follows a standardized structure with defined blocks:

bash
1#!/bin/bash                           # ← Shebang (Required)
2
3# --- Manifest --- #                   # ← Manifest (Required)
4# name: My Service
5# description: Does something useful
6# version: 1.0
7# schedule: *:0/05:00
8# timeout: 30
9
10# --- Overview --- #                   # ← Overview (Optional)
11# Detailed explanation of what this script does
12
13# --- Standard Constants --- #          # ← Standard Constants (Required)
14STATUS_OK="OK"
15STATUS_UPDATE="UPDATE"
16STATUS_WARNING="WARNING"
17STATUS_FAILURE="FAILURE"
18TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
19
20# --- Configurations --- #              # ← Configurations (Optional)
21MY_SETTING="value"
22
23# --- Dependencies --- #              # ← Dependencies (Optional)
24# curl, jq
25
26# --- Main --- #                        # ← Main (Required)
27# The actual monitoring logic goes here
28echo "$TIMESTAMP, $STATUS_OK, Everything is fine"

How Service Scripts Are Executed

  1. You add a script with ssi add my-script.bash
  2. SSI creates systemd service and timer units
  3. systemd timer triggers the script on schedule
  4. Script runs and outputs to /var/log/ssi-agent/<id>.log
  5. SSI daemon watches the log file and sends updates to backend
Rendering diagram...

Output Format

Service scripts must output status in this exact format:

<TIMESTAMP>, <STATUS>, <MESSAGE>

Example:

2024-01-15 10:30:00, OK, API is healthy

See Status Codes for the complete reference.

In This Section