man - zygaena/zyginit

root / docs / man
man Plain Text 868 lines 20.4 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
.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGCTL 8
.Os Hammerhead
.Sh NAME
.Nm zygctl
.Nd administrative control utility for zyginit
.Sh SYNOPSIS
.Nm
.Ar command
.Op Ar argument
.Sh DESCRIPTION
.Nm
is the administrative command-line interface for the
.Xr zyginit 8
service supervisor.
It communicates with the running
.Nm zyginit
daemon over a Unix domain socket to query service status,
start and stop services, and manage the enabled service set.
.Pp
Commands that modify the enabled service set
.Pq Cm enable , Cm disable
operate directly on the filesystem and do not require the daemon to be running.
All other commands connect to the daemon socket.
.Sh COMMANDS
.Bl -tag -width "restart"
.It Cm status Op Ar name
Display the status of all services, or of the named service if
.Ar name
is given.
Output includes the service name, current state, and if running,
the process ID and contract ID.
.It Cm start Ar name
Start the named service.
If the service is already running, a message is printed and no
action is taken.
.It Cm stop Ar name
Stop the named service.
The stop method is determined by the service definition: either
a contract-wide signal or execution of a stop command.
If the service does not stop within its configured timeout, it
is forcibly terminated with
.Dv SIGKILL .
.It Cm restart Ar name
Restart the named service.
If the service is running, it is stopped first.
If the service is stopped or in maintenance, it is started immediately.
.It Cm list
List all loaded service definitions with their type
.Pq daemon, oneshot, transient .
.It Cm enable Ar name
Enable a service for automatic start at boot.
Creates a symlink in
.Pa /etc/zyginit/enabled.d/
pointing to the service's TOML definition.
The service is not started immediately; use
.Cm start
to start it now.
.It Cm disable Ar name
Disable a service from automatic start at boot.
Removes the symlink from
.Pa /etc/zyginit/enabled.d/ .
The service is not stopped immediately; use
.Cm stop
to stop it now.
.It Cm log Ar name
Display the output log for the named service.
Service stdout and stderr are captured to per-service log files under
.Pa /var/run/zyginit/log/ .
Log files are truncated on each service start, so only the most recent
output is shown.
Useful for diagnosing startup failures.
.It Cm reload
Reload the service configuration.
The daemon re-scans
.Pa /etc/zyginit/enabled.d/
and compares with the current service table.
Newly-enabled services are started; disabled services are stopped.
This is equivalent to sending
.Dv SIGHUP
to the
.Xr zyginit 8
process.
.It Cm replace Op Fl -wait Ns = Ns Ar N
Replace the running
.Xr zyginit 8
process via in-place
.Xr execve 2
of
.Pa /sbin/init .
All running services keep running across the swap; their process
contracts, restart counters, and uptimes are preserved via a state
file at
.Pa /var/run/zyginit/state.toml .
The operator must drop the new binary at
.Pa /sbin/init
.Em before
issuing this command;
.Nm
does not stage or copy binaries.
.Pp
With
.Fl -wait Ns = Ns Ar N ,
poll up to
.Ar N
seconds for any service in a transient state
.Pq starting , stopping , waiting
to stabilize before refusing.
Default is
.Ar N
=
.Sy 0
(refuse immediately).
Useful for automation: run
.Nm
.Cm replace Fl -wait Ns = Ns Sy 60
to either succeed within a minute or fail with a known upper bound on
time.
.Pp
The replace flow is operator-driven only; it does not cover crash
recovery.
See
.Xr zyginit 8
for the full mechanism.
.It Cm version
Print the version of
.Nm .
.It Cm help
Print a summary of available commands.
.El
.Sh ENVIRONMENT
.Bl -tag -width "ZYGINIT_CONFIG_DIR"
.It Ev ZYGINIT_SOCKET
Path to the
.Xr zyginit 8
control socket.
Default:
.Pa /var/run/zyginit.sock
.It Ev ZYGINIT_LOG_DIR
Path to the per-service log directory.
Used by the
.Cm log
command.
Default:
.Pa /var/run/zyginit/log
.It Ev ZYGINIT_CONFIG_DIR
Path to the service definition directory.
Used by the
.Cm enable
and
.Cm disable
commands to locate TOML files and the
.Pa enabled.d/
subdirectory.
Default:
.Pa /etc/zyginit
.El
.Sh EXIT STATUS
.Nm
exits 0 on success.
If it cannot connect to the daemon socket, a diagnostic message is
printed to standard error.
.Sh EXAMPLES
Show the status of all services:
.Bd -literal -offset indent
$ zygctl status
sshd running pid=1234 ctid=7
cron running pid=1235 ctid=8
filesystem stopped
.Ed
.Pp
Show the status of a single service:
.Bd -literal -offset indent
$ zygctl status sshd
sshd running pid=1234 ctid=7
.Ed
.Pp
Stop and disable a service:
.Bd -literal -offset indent
# zygctl stop sshd
sshd stopping
# zygctl disable sshd
.Ed
.Pp
Enable and start a service:
.Bd -literal -offset indent
# zygctl enable sshd
# zygctl start sshd
sshd started
.Ed
.Pp
List all loaded service definitions:
.Bd -literal -offset indent
$ zygctl list
sshd (daemon)
cron (daemon)
network (oneshot)
filesystem (oneshot)
.Ed
.Sh SEE ALSO
.Xr zyginit 8 ,
.Xr zyginit 5
.Sh HISTORY
.Nm
first appeared in Zygaena/Hammerhead alongside
.Xr zyginit 8 .
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com
.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGINIT 8
.Os Hammerhead
.Sh NAME
.Nm zyginit
.Nd init daemon and service supervisor for Zygaena/Hammerhead
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
.Nm
is the init daemon (PID 1) and service supervisor for the
Zygaena/Hammerhead operating system.
It replaces SMF
.Pq Service Management Facility
with a single-process, TOML-configured service manager.
.Pp
At boot,
.Nm
performs the following sequence:
.Bl -enum
.It
Scans the enabled services directory for symlinks
.Pq see Sx CONFIGURATION .
.It
Reads each service's TOML definition to extract dependencies.
.It
Performs a topological sort to determine parallel boot tiers.
.It
Starts services tier by tier, respecting dependency order.
.It
Opens a Unix domain socket for
.Xr zygctl 8
communication.
.It
Enters the main event loop, monitoring process contracts, signals,
and the control socket via
.Xr poll 2 .
.El
.Pp
.Nm
supervises all managed services.
When a service exits, the restart policy defined in its TOML definition
determines whether the service is restarted, placed into maintenance,
or left stopped.
.Ss Service Types
.Nm
supports three service types:
.Bl -tag -width "transient"
.It Sy daemon
A long-running process.
.Nm
monitors the process via a Hammerhead process contract and applies the
restart policy when it exits.
.It Sy oneshot
A short-lived process that runs once at boot
.Pq e.g., mounting filesystems, configuring network interfaces .
Once it exits successfully, the service is considered
.Dq done .
A non-zero exit places the service into the
.Sy failed
state.
.It Sy transient
A process started on demand via
.Xr zygctl 8
that is not started automatically at boot.
.El
.Ss Service States
Each managed service is in one of the following states:
.Bl -tag -width "maintenance"
.It Sy disabled
The service is not enabled for boot
.Pq no symlink in Ar enabled.d .
.It Sy waiting
The service is waiting to start
.Pq dependency not yet met or restart delay pending .
.It Sy starting
The service is being started
.Pq fork/exec in progress .
.It Sy running
The service process is alive and being monitored.
.It Sy stopping
A stop has been requested; waiting for the process to exit.
.It Sy stopped
The service has exited and will not be restarted.
.It Sy failed
The service exited abnormally
.Pq oneshot with non-zero exit, or unrecoverable error .
.It Sy maintenance
The service has exceeded its maximum restart count.
Administrative intervention is required.
Use
.Xr zygctl 8
to clear and restart.
.El
.Ss Process Contracts
On Hammerhead,
.Nm
uses kernel process contracts
.Pq see Xr contract 5
to track all descendants of a service process.
This ensures that orphaned grandchild processes are properly managed
and that
.Nm
receives notification when all processes in a service's contract have exited.
.Pp
When
.Nm
is restarted
.Pq e.g., for an upgrade ,
it re-adopts existing contracts so that running services are not disrupted.
.Pp
On systems without process contract support,
.Nm
falls back to direct PID-based monitoring via
.Xr waitpid 2 .
.Ss Signal Handling
.Nm
handles the following signals:
.Bl -tag -width "SIGCHLD"
.It Dv SIGTERM , Dv SIGINT
Initiate graceful shutdown.
All running services are stopped in reverse boot order.
.It Dv SIGHUP
Reload service configuration.
The daemon re-scans
.Pa /etc/zyginit/enabled.d/
and compares with the current service table.
Newly-enabled services are started; disabled services are stopped.
This is equivalent to the
.Cm reload
command in
.Xr zygctl 8 .
.It Dv SIGCHLD
Reap exited child processes and dispatch to the service supervisor.
.It Dv SIGPIPE
Ignored.
.El
.Sh CONFIGURATION
.Nm
reads its service definitions from
.Pa /etc/zyginit/ .
Each service is defined by a TOML file in that directory.
See
.Xr zyginit 5
for the full service definition format.
.Ss Enabling and Disabling Services
Services are enabled by creating a symlink in the
.Pa enabled.d
subdirectory:
.Bd -literal -offset indent
/etc/zyginit/enabled.d/sshd -> ../sshd.toml
.Ed
.Pp
To enable a service:
.Bd -literal -offset indent
# zygctl enable sshd
.Ed
.Pp
To disable:
.Bd -literal -offset indent
# zygctl disable sshd
.Ed
.Pp
These operations can also be performed manually with
.Xr ln 1
and
.Xr rm 1 .
.Sh ENVIRONMENT
.Bl -tag -width "ZYGINIT_CONFIG_DIR"
.It Ev ZYGINIT_CONFIG_DIR
Path to the service definition directory.
Default:
.Pa /etc/zyginit
.It Ev ZYGINIT_SOCKET
Path to the Unix domain socket for
.Xr zygctl 8
communication.
Default:
.Pa /var/run/zyginit.sock
.It Ev ZYGINIT_LOG_DIR
Path to the per-service log directory.
Service stdout and stderr are captured here.
Default:
.Pa /var/run/zyginit/log
.El
.Sh FILES
.Bl -tag -width "/etc/zyginit/enabled.d/"
.It Pa /sbin/init
The init daemon binary
.Pq kernel exec target on Hammerhead .
.It Pa /etc/zyginit/
Directory containing service definition TOML files.
.It Pa /etc/zyginit/enabled.d/
Symlinks to enabled service definitions.
Only services with a symlink here are started at boot.
.It Pa /var/run/zyginit.sock
Unix domain socket for administrative communication.
Created after tmpfs is mounted.
.It Pa /var/run/zyginit/log/
Per-service output log directory.
Each service's stdout and stderr are captured to
.Pa <name>.log
in this directory.
Log files are truncated on each service start.
.El
.Sh LIVE REPLACE
.Nm
supports operator-driven, in-place replacement of the PID-1 process
via
.Xr execve 2
without disturbing running services.
The operator drops a new binary at
.Pa /sbin/init
and runs
.Xr zygctl 8
.Cm replace .
The running
.Nm
serializes its in-memory service-supervision state to
.Pa /var/run/zyginit/state.toml
\(em
service name, contract ID, restart count, uptime
\(em
unlinks the control socket, then
.Xr execve 2 Ns 's
.Pa /sbin/init .
PID-1 in-place
.Xr execve 2
preserves
.Va proc_t.p_ct_process ,
so the kernel-level contract ownership survives the swap; the new
.Nm
process re-reads
.Pa /var/run/zyginit/state.toml ,
re-establishes its userspace bookkeeping, and continues supervising.
.Pp
The boot-id sentinel
.Pq Pa /proc/1/stat
field 22 on Linux;
.Pa /proc/1/psinfo
.Va pr_start.tv_sec
on Hammerhead
is read at startup by the new
.Nm
to detect stale state files left over from before a real reboot.
PID 1's process start time survives
.Xr execve 2
.Pq same proc_t
but changes on real reboot
.Pq new PID 1 .
A mismatch causes the new
.Nm
to ignore (and delete) the file and proceed as a fresh boot.
.Pp
This mechanism is for live upgrades only; it does not cover crash
recovery, since
.Nm
crashing as PID 1 is already a system-level event.
See
.Xr zygctl 8
.Cm replace
for invocation details.
.Sh EXAMPLES
Start
.Nm
in non-init mode for testing
.Pq not as PID 1 :
.Bd -literal -offset indent
# ZYGINIT_CONFIG_DIR=/etc/zyginit zyginit
.Ed
.Sh SEE ALSO
.Xr zygctl 8 ,
.Xr zyginit 5 ,
.Xr contract 5
.Sh HISTORY
.Nm
first appeared in Zygaena/Hammerhead as a replacement for SMF
.Pq Service Management Facility .
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com