SSI LogoSSI

Manifest Reference

The Manifest block contains metadata about the service script. This metadata is parsed by the SSI Agent when adding a service.

Manifest Format

Each manifest field is a comment line with the format:

bash
1# field: value

Fields

name (Required)

The human-readable name of the service.

bash
1# name: API Health

Constraints:

  • Minimum: 3 characters
  • Maximum: 60 characters
  • Allowed: Letters, numbers, spaces, hyphens

What it's used for:

  • Display name in the mobile app
  • Deriving the service ID (name → kebab-case)

Examples:

bash
1# --- Manifest --- #
2# name: API Health
3# name: ZFS Zpool Health
4# name: System Updates
5# name: Daily Backup Verifier

description (Required)

A short description of what the service monitors.

bash
1# description: Checks the health of an API that has a health check endpoint

Constraints:

  • Maximum: 255 characters

What it's used for:

  • Displayed in the mobile app
  • systemd unit file Description field

Examples:

bash
1# description: Checks the health of an API endpoint
2# description: Monitors available system updates on Debian/Ubuntu
3# description: Verifies BTRFS filesystem integrity via scrub

version (Required)

The version of the service script.

bash
1# version: 1.0

Format:

  • Any string (typically semver like 1.0, 1.0.0, 2.1.3) For simplicity, we recommend x.y format like 1.0, 1.1, 2.0.

What it's used for:

  • Tracking script versions
  • Future: Detecting when to update

Examples:

bash
1# version: 1.0
2# version: 1.1
3# version: 2.0

schedule (Required)

The schedule for running the service script, in systemd OnCalendar format.

bash
1# schedule: *:0/01:00

Format: systemd OnCalendar expression

Common patterns:

PatternMeaning
*:0/01:00Every 1 minute
*:0/05:00Every 5 minutes
*:0/15:00Every 15 minutes
*-*-* 06:00:00Daily at 6:00 AM
*-*-* 00:00:00Daily at midnight
Mon *-*-* 00:00:00Every Monday at midnight
*-*-01 00:00:00First of every month at midnight

Understanding the format:

DayOfWeek Year-Month-Day Hour:Minute:Second Examples: *-*-* 06:00:00 = Every day at 06:00:00 Mon *-*-* 06:00:00 = Every Monday at 06:00:00 *:0/5:00 = Every 5 minutes (at :00, :05, :10, etc.) *:*:0/30 = Every 30 seconds

Testing your schedule:

Use systemd-analyze calendar to verify:

bash
1systemd-analyze calendar "*:0/05:00"

Output:

Original form: *:0/05:00 Normalized form: *-*-* *:00/5:00 Next elapse: Fri 2024-01-15 10:35:00 UTC (in UTC): Fri 2024-01-15 10:35:00 UTC From now: 2min 30s left

timeout (Optional)

Maximum execution time in seconds. The script will be killed if it exceeds this duration.

bash
1# timeout: 30

Default: 20 seconds

Constraints:

  • Minimum: 1 second
  • Recommended maximum: Match your schedule interval

What it's used for:

  • systemd TimeoutSec directive
  • Preventing hung scripts from blocking the system

Examples:

bash
1# timeout: 10      # Quick API check
2# timeout: 60      # Longer health check
3# timeout: 300     # 5-minute ZFS scrub status check
4# timeout: 86400   # Full day for very long operations

Complete Manifest Example

bash
1# name: API Health
2# description: Checks the health of an API that has a health check endpoint
3# version: 1.0
4# schedule: *:0/01:00
5# timeout: 10

Validation

When you run ssi add, the manifest is validated:

FieldValidation
nameRequired, 3-60 chars
descriptionRequired, max 255 chars
versionRequired
scheduleRequired, valid OnCalendar format
timeoutOptional, must be > 0 if provided

Error examples:

ValueError: Service name must be between 3 and 60 characters. ValueError: Service description cannot exceed 255 characters. ValueError: Service script must contain a schedule metadata. ValueError: Invalid schedule format...

Service ID Derivation

The service ID is automatically derived from the name field:

  1. Convert to lowercase
  2. Replace spaces with hyphens

Examples:

NameService ID
API Healthapi-health
ZFS Zpool Healthzfs-zpool-health
System Updatessystem-updates
Daily Backup Verifierdaily-backup-verifier

The service ID is used for:

  • systemd unit file names (ssi-api-health.service)
  • Log file names (api-health.log)
  • CLI commands (ssi service status api-health)