zyginit.5 - zygaena/zyginit

root / docs / man / man5 / zyginit.5
zyginit.5 Groff 372 lines 8.5 KB
.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGINIT 5
.Os Hammerhead
.Sh NAME
.Nm zyginit
.Nd service definition format for zyginit
.Sh DESCRIPTION
Service definitions for
.Xr zyginit 8
are TOML files stored in
.Pa /etc/zyginit/ .
Each file describes a single service: its type, how to start and stop it,
its dependencies on other services, process contract parameters, and
restart policy.
.Pp
Services are enabled for boot by creating a symlink in the
.Pa /etc/zyginit/enabled.d/
subdirectory.
See
.Xr zygctl 8
for commands to manage the enabled set.
.Sh FILE FORMAT
Each service definition is a TOML file with the following sections.
.Ss [service]
Required.
Identifies the service.
.Bl -tag -width "description"
.It Sy name Pq string, required
A unique identifier for the service.
This name is used in dependency declarations, symlinks, and
.Xr zygctl 8
commands.
Must match the filename without the
.Pa .toml
extension.
.It Sy description Pq string, optional
A human-readable description of the service.
.It Sy type Pq string, required
The service type.
One of:
.Bl -tag -width "transient" -compact
.It Cm daemon
A long-running process monitored continuously.
.It Cm oneshot
A short-lived process that runs once at boot.
.It Cm transient
A process started on demand, not at boot.
.El
.El
.Ss [exec]
Required.
Defines the commands used to start and optionally stop the service.
.Bl -tag -width "start"
.It Sy start Pq string, required
The command to execute when starting the service.
This may be a direct path to a daemon binary with arguments,
or a path to a shell script for services requiring complex startup logic.
.Pp
For daemon services, the command should run in the foreground
.Pq not daemonize itself
so that
.Xr zyginit 8
can track the process.
.It Sy stop Pq string, optional
A command to execute when stopping the service.
Only used when
.Sy [stop] method
is set to
.Cm exec .
If not specified, the service is stopped by signaling its process contract.
.It Sy working_directory Pq string, optional
Change to this directory before executing the start command.
Useful for services that expect to run from a specific path.
.It Sy user Pq string, optional
Run the service as this user.
The daemon looks up the user's UID and primary GID via
.Xr getpwnam 3 ,
then drops privileges with
.Xr setgid 2 ,
.Xr initgroups 3 ,
and
.Xr setuid 2
before executing the start command.
.It Sy group Pq string, optional
Run the service with this group.
Overrides the user's primary group if both
.Sy user
and
.Sy group
are specified.
.It Sy environment Pq array of strings, optional
Environment variables to set before executing the start command.
Each entry has the form
.Dq KEY=value .
Example:
.Bd -literal -offset indent
environment = ["LANG=en_US.UTF-8", "TZ=US/Pacific"]
.Ed
.El
.Ss [stop]
Optional.
Controls how the service is stopped.
.Bl -tag -width "timeout"
.It Sy method Pq string
The stop method.
One of:
.Bl -tag -width "contract" -compact
.It Cm contract
Send a signal to all processes in the service's contract.
This is the default and preferred method.
.It Cm exec
Execute the command specified in
.Sy [exec] stop .
.El
Default:
.Cm contract .
.It Sy signal Pq string
The signal to send when using the
.Cm contract
stop method.
Specified without the
.Dq SIG
prefix.
Common values:
.Cm TERM , HUP , INT , KILL , USR1 , USR2 .
.Pp
Default:
.Cm TERM .
.It Sy timeout Pq integer
The number of seconds to wait for the service to stop before
escalating to
.Dv SIGKILL .
.Pp
Default: 60.
.El
.Ss [dependencies]
Optional.
Declares relationships with other services.
.Bl -tag -width "requires"
.It Sy requires Pq array of strings
Services that must be running before this service can start.
If a required service fails or is not enabled,
.Xr zyginit 8
will print a warning during boot.
.Pp
Example:
.Dl requires = ["network", "filesystem"]
.It Sy after Pq array of strings
Services that should be started before this service, but are not
hard dependencies.
If an
.Cm after
service is not enabled, this service still starts normally.
.Pp
Example:
.Dl after = ["syslog", "name-services"]
.It Sy conflicts Pq array of strings
Services that must never run at the same time as this one.
The relation is symmetric: declaring the conflict on either service is enough.
If two conflicting services are both enabled at boot,
.Em both
are marked failed (zyginit never auto-selects a winner).
At runtime,
.Xr zygctl 8
.Cm start
is refused if a conflicting service is already running.
.Pp
Example:
.Dl conflicts = ["sendmail"]
.El
.Ss [contract]
Optional.
Controls Hammerhead process contract parameters.
See
.Xr contract 5
for details.
.Bl -tag -width "param"
.It Sy param Pq array of strings
Contract parameter flags.
Supported values:
.Bl -tag -width "noorphan" -compact
.It Cm inherit
Child processes inherit the contract.
.It Cm noorphan
Orphaned processes are killed when the contract is abandoned.
.It Cm pgrponly
Only the process group leader is tracked.
.It Cm regent
The contract owner acts as regent for the child.
.El
.Pp
Default:
.Cm inherit , noorphan .
.It Sy fatal Pq array of strings
Events that are considered fatal for the contract.
Supported values:
.Bl -tag -width "signal" -compact
.It Cm empty
All processes in the contract have exited.
.It Cm core
A process produced a core dump.
.It Cm hwerr
A hardware error was detected.
.It Cm signal
A process was killed by a fatal signal.
.El
.Pp
Default:
.Cm empty , hwerr .
.El
.Ss [restart]
Optional.
Controls the restart policy for daemon services.
Ignored for oneshot services.
.Bl -tag -width "max_retries"
.It Sy on Pq string
When to restart the service.
One of:
.Bl -tag -width "failure" -compact
.It Cm always
Restart regardless of exit status.
.It Cm failure
Restart only if the exit status is non-zero.
.It Cm never
Do not restart.
.El
.Pp
Default:
.Cm failure .
.It Sy delay Pq integer
The number of seconds to wait before restarting.
.Pp
Default: 5.
.It Sy max_retries Pq integer
The maximum number of consecutive restart attempts before
placing the service into
.Sy maintenance
state.
Set to \-1 for unlimited retries.
.Pp
Default: 3.
.El
.Sh DIRECTORY LAYOUT
.Bd -literal -offset indent
/etc/zyginit/
\(ba\(em sshd.toml              # Service definition
\(ba\(em cron.toml
\(ba\(em network.toml
\(ba\(em filesystem.toml
\(ba\(em network/               # Scripts for complex services
\(ba   \(em start.sh
\(ba\(em enabled.d/             # Symlinks to enabled services
    \(ba\(em sshd -> ../sshd.toml
    \(em cron -> ../cron.toml
.Ed
.Ss Script Escape Hatch
For services requiring complex startup logic
.Pq database initialization, multi-step network configuration ,
the
.Sy [exec] start
field can point to a shell script in a subdirectory matching the
service name:
.Bd -literal -offset indent
/etc/zyginit/
\(ba\(em postgresql.toml
\(em postgresql/
    \(ba\(em start.sh
    \(em stop.sh
.Ed
.Sh EXAMPLES
.Ss Simple Daemon
A long-running daemon with standard restart behavior:
.Bd -literal -offset indent
[service]
name = "sshd"
description = "Secure Shell Daemon"
type = "daemon"

[exec]
start = "/usr/lib/ssh/sshd -D"

[stop]
method = "contract"
signal = "TERM"
timeout = 60

[dependencies]
requires = ["network", "filesystem"]
after = ["name-services"]

[contract]
param = ["inherit", "noorphan"]
fatal = ["empty", "hwerr"]

[restart]
on = "failure"
delay = 5
max_retries = 3
.Ed
.Ss Oneshot Service
A boot-time task that runs once:
.Bd -literal -offset indent
[service]
name = "filesystem"
description = "Local Filesystem Mounts"
type = "oneshot"

[exec]
start = "/etc/zyginit/filesystem/start.sh"

[dependencies]
requires = ["root-fs"]

[restart]
on = "never"
.Ed
.Ss Service with Custom Stop Command
.Bd -literal -offset indent
[service]
name = "postgresql"
description = "PostgreSQL Database Server"
type = "daemon"

[exec]
start = "/etc/zyginit/postgresql/start.sh"
stop = "/etc/zyginit/postgresql/stop.sh"

[stop]
method = "exec"
timeout = 120

[dependencies]
requires = ["filesystem", "network"]

[restart]
on = "failure"
delay = 10
max_retries = 3
.Ed
.Ss Minimal Service
Only the required fields:
.Bd -literal -offset indent
[service]
name = "myapp"
description = "My Application"
type = "daemon"

[exec]
start = "/usr/local/bin/myapp"
.Ed
.Pp
This service uses all defaults: contract stop method with SIGTERM,
60-second timeout, restart on failure with 5-second delay and
3 maximum retries.
.Sh SEE ALSO
.Xr zyginit 8 ,
.Xr zygctl 8 ,
.Xr contract 5 ,
.Xr toml 5
.Sh HISTORY
The
.Nm
service definition format first appeared in Zygaena/Hammerhead as part of the
.Xr zyginit 8
init system.
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com