man8 - zygaena/zyginit

root / docs / man / man8
man8 Plain Text 497 lines 11.9 KB
.\"
.\" 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