zosbuilder/components/zinit/docs/services.md

Service Configuration Format

This document describes the structure and options for Zinit service configuration files.

File Format

Zinit uses YAML files for service configuration. Each service has its own configuration file stored in the Zinit configuration directory (default: /etc/zinit).

File Naming and Location

• Location: /etc/zinit/ (default, can be changed with -c flag)
  • on osx ~/hero/cfg/zinit
• Naming: <service-name>.yaml

For example:

• /etc/zinit/nginx.yaml
• /etc/zinit/redis.yaml

Configuration Schema

Service configuration files use the following schema:

# Command to run (required)
exec: "command line to start service"

# Command to test if service is running (optional)
test: "command line to test service"

# Whether the service should be restarted (optional, default: false)
oneshot: true|false

# Maximum time to wait for service to stop during shutdown (optional, default: 10)
shutdown_timeout: 30

# Services that must be running before this one starts (optional)
after:
  - service1_name
  - service2_name

# Signals configuration (optional)
signal:
  stop: SIGKILL  # signal sent on 'stop' action (default: SIGTERM)

# Log handling configuration (optional, default: ring)
log: null|ring|stdout

# Environment variables for the service (optional)
env:
  KEY1: "VALUE1"
  KEY2: "VALUE2"

# Working directory for the service (optional)
dir: "/path/to/working/directory"

Configuration Options

Required Fields

Field	Description
exec	Command line to execute when starting the service

Optional Fields

Field	Type	Default	Description
test	String	-	Command to determine if service is running
oneshot	Boolean	false	If true, service won't be restarted after exit
shutdown_timeout	Integer	10	Seconds to wait for service to stop during shutdown
after	String[]	[]	List of services that must be running first
signal.stop	String	"sigterm"	Signal to send when stopping the service
log	Enum	ring	How to handle service output (null, ring, stdout)
env	Object	{}	Environment variables to pass to the service
dir	String	""	Working directory for the service

Field Details

exec

The command to run when starting the service. This is the only required field in the configuration.

exec: "/usr/bin/redis-server --port 6379"

Shell-style commands are supported:

exec: "sh -c 'echo Starting service && /usr/local/bin/myservice'"

test

Command that tests whether the service is running properly. Zinit runs this command periodically until it succeeds (exit code 0), at which point the service is considered running.

test: "redis-cli -p 6379 PING"

If no test command is provided, the service is considered running as soon as it's started.

oneshot

When set to true, the service will not be automatically restarted when it exits. This is useful for initialization tasks or commands that should run only once.

oneshot: true

Services that depend on a oneshot service will start only after the oneshot service has exited successfully.

shutdown_timeout

How long (in seconds) to wait for the service to stop during system shutdown before giving up:

shutdown_timeout: 30  # Wait up to 30 seconds

after

List of service names that must be running (or completed successfully for oneshot services) before this service starts:

after:
  - networking
  - database

signal

Custom signals to use for operations. Currently, only the stop signal is configurable:

signal:
  stop: SIGKILL  # Use SIGKILL instead of default SIGTERM

Valid signal names follow the standard UNIX signal naming (SIGTERM, SIGKILL, SIGINT, etc).

log

How to handle stdout/stderr output from the service:

log: stdout  # Print output to zinit's stdout

Options:

• null: Ignore all service output (like redirecting to /dev/null)
• ring: Store logs in the kernel ring buffer with service name prefix (default)
• stdout: Send service output to zinit's stdout

Note

: To use ring inside Docker, make sure to add the kmsg device:

docker run -dt --device=/dev/kmsg:/dev/kmsg:rw zinit

env

Additional environment variables for the service. These are added to the existing environment:

env:
  PORT: "8080"
  DEBUG: "true"
  NODE_ENV: "production"

dir

Working directory for the service process:

dir: "/var/lib/myservice"

If not specified, the process inherits zinit's working directory.

Example Configurations

Web Server

exec: "/usr/bin/nginx -g 'daemon off;'"
test: "curl -s http://localhost > /dev/null"
after:
  - networking
log: stdout

Database Initialization

exec: "sh -c 'echo Creating database schema && /usr/bin/db-migrate'"
oneshot: true
dir: "/opt/myapp"
env:
  DB_HOST: "localhost"
  DB_USER: "admin"

Application with Dependencies

exec: "/usr/bin/myapp --config /etc/myapp.conf"
test: "curl -s http://localhost:8080/health > /dev/null"
after:
  - database
  - cache
signal:
  stop: SIGINT  # Use SIGINT for graceful shutdown
env:
  PORT: "8080"
shutdown_timeout: 20