Quick Guide for Service-Scripts

This guide is a quick reference for those who are already familiar with writing SSI service-scripts and want to quickly start a new script.

Boilerplate

Create your service-script (e.g., check API health -> api-health.bash, check system updates -> system-updates.bash) and paste the following template:

bash

1#!/bin/bash
2
3# --- Manifest --- #
4# name: Service Name
5# description: Concise description of the check (max 255 chars)
6# version: 1.0.0
7# schedule: *:0/15:00
8# timeout: 20
9
10# --- Standard Constants --- #
11STATUS_OK="OK"
12STATUS_UPDATE="UPDATE"
13STATUS_WARNING="WARNING"
14STATUS_FAILURE="FAILURE"
15TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
16
17# --- Configurations --- #
18# Define configurations and default values using ${VAR:-default}
19WARNING_THRESHOLD="${WARNING_THRESHOLD:-80}"
20CRITICAL_THRESHOLD="${CRITICAL_THRESHOLD:-95}"
21MOUNT_POINT="${MOUNT_POINT:-/}"
22
23# --- Dependencies --- #
24# df
25
26# --- Main --- #
27# Check the disk usage percentage of the configured mount point
28USAGE=$(df -h "$MOUNT_POINT" | awk 'NR==2 {print $5}' | tr -d '%')
29
30if [ "$USAGE" -ge "$CRITICAL_THRESHOLD" ]; then
31    echo "$TIMESTAMP, $STATUS_FAILURE, Disk usage critical: ${USAGE}%"
32    exit 1
33elif [ "$USAGE" -ge "$WARNING_THRESHOLD" ]; then
34    echo "$TIMESTAMP, $STATUS_WARNING, Disk usage high: ${USAGE}%"
35    exit 0
36else
37    echo "$TIMESTAMP, $STATUS_OK, Disk usage normal: ${USAGE}%"
38    exit 0
39fi

Quick Reference

Output Format

The agent parses only the last line of the stdout to determine final status. Use this exact format:

text

1<YYYY-MM-DD HH:MM:SS>, <STATUS>, <MESSAGE>

Example: 2026-06-28 12:00:00, OK, Service is healthy

Exit Codes

exit 0: Script completed successfully (regardless of whether status is OK or WARNING).
exit 1: Script encountered an internal error or critical service failure.

Manifest Fields

name (Required): Human-readable name shown in UI (3-60 chars).
description (Required): Short summary of the script (max 255 chars).
version (Required): Semantic version (e.g. 1.0.0).
schedule (Required): systemd timer OnCalendar schedule (e.g. *:0/05:00 for every 5 mins).
timeout (Optional): Max execution time in seconds (default: 20).

CLI Cheatsheet

1. Test Locally

Make the script executable and run it directly to verify formatting and output:

bash

1chmod +x api-health.bash
2./api-health.bash

2. Add to Agent

bash

1ssi service add api-health.bash

3. Run Manually

Force execution of the service immediately (uses the service ID derived from the name/filename):

bash

1ssi service run api-health

4. Check Status

List registered services and their current status:

bash

1# Get summary status of all services
2ssi service status
3
4# List all installed service configurations
5ssi service list

5. Debug Logs

Tail the logs for your specific service or watch the daemon:

bash

1# Service output logs
2tail -f /var/log/ssi-agent/api-health.log
3
4# Daemon events
5ssi debug logs -f