Add doc

author: PS <p@0x53.net> 2026-02-07 10:34:21 +0100
committer: PS <p@0x53.net> 2026-02-07 10:34:21 +0100
commit: eb36640078ee6469427e85ca0695f8c920909ea0 (patch)
tree: 4e490a9b3b4e2f2c07bf261acde1d8ac70bb87d0 /doc
parent: 891a3316a22acdc57a2e65429f4d59ada268410c (diff)
download: goetia-freebsd-init-eb36640078ee6469427e85ca0695f8c920909ea0.tar.gz
goetia-freebsd-init-eb36640078ee6469427e85ca0695f8c920909ea0.tar.bz2
goetia-freebsd-init-eb36640078ee6469427e85ca0695f8c920909ea0.zip
5 files changed, 504 insertions, 0 deletions
diff --git a/doc/bin/system-init.html b/doc/bin/system-init.html
new file mode 100644
index 0000000..f744d6a
--- /dev/null
+++ b/doc/bin/system-init.html
@@ -0,0 +1,132 @@
+<!DOCTYPE html>
+<html>
+	<head>
+    	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    	<meta http-equiv="Content-Language" content="en" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    	<title>system-init</title>
+    	<meta name="Description" content="Init script for FreeBSD." />
+    	<meta name="Keywords" content="goetia s6 s6-rc FreeBSD" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-freebsd-init">goetia-freebsd-init</a>
+			<br />
+			<a href="//0x53.net/software/goetia">goetia</a>
+			<br />
+			<a href="//0x53.net/software">Software</a>
+			<br />
+			<a href="//0x53.net">0x53.net</a>
+		</p>
+	</header>
+	<body>
+		<h1>The system-init program</h1>
+		<p>
+			system-init is a minimal, scripted init to bring up a goetia based system.
+		</p>
+		<h2>Interface</h2>
+		<pre>     system-init</pre>
+		<ul>
+			<li>
+    			system-init takes no arguments.
+			</li>
+			<li>
+    			It makes <code>/dev/console</code> its stdout and stderr.
+			</li>
+			<li>
+    			It reads the environment variable <code>BUNDLE</code>,
+				which can be specified on the Kernel command line.
+				If it is undefined, it uses <code>default</code> as the value.
+			</li>
+			<li>
+    			It reads the environment variable <code>PATH</code>,
+				which can be specified on the Kernel command line.
+				If it is undefined, it uses
+				<code>/command:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/libexec:/usr/local/libexec</code>
+				as the value.
+			</li>
+			<li>
+    			It sets the <code>PATH</code> environment variable to the value
+				chosen above.
+			</li>
+			<li>
+    			It chdirs to <code>/</code>.
+			</li>
+			<li>
+    			It runs <code><a href="https://skarnet.org/software/s6/s6-setsid.html">s6-setsid</a></code>
+				to become the session leader.
+			</li>
+			<li>
+    			It creates the
+				<a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>
+				if it does not already exist.
+			</li>
+			<li>
+    			It mounts the
+				<a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>
+				tmpfs.
+			</li>
+			<li>
+    			It copies the old system logs from the
+				<code>system/uncaught-logs</code>
+				subdirectory of the
+				<a href="//0x53.net/software/goetia/logdir.html">log directory</a>
+				to the
+				<code>system/</code>
+				subdirectory of the
+				<a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>
+				if they exist.
+			</li>
+			<li>
+    			It runs
+				<code><a href="./prepare-svscan.html">prepare-svscan</a></code>
+				with the proper arguments.
+			</li>
+			<li>
+    			Finally, it executes into
+				<code><a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a></code>
+				on the scandir represented by the
+				<code>system/service</code>
+				subdirectory of the
+				<a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>.
+			</li>
+		</ul>
+		<h2>Exit codes</h2>
+		<ul>
+			<li>
+    			system-init usually executes into
+				<a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
+				which exits according to its page.
+			</li>
+			<li>
+    			Since system-init is an
+				<a href="https://skarnet.org/software/execline/">execline</a>
+				script, it exits with an approximation
+				of employed program that failed.
+			</li>
+			<li>
+    			system-init mostly uses
+				<a href="https://skarnet.org/software/execline/">execline</a>
+				and
+				<a href="https://skarnet.org/software/s6/">s6</a>
+				software, the exit behaviour of which can be looked up on
+				their respective pages.
+			</li>
+			<li>
+    			See also:
+				<a href="https://skarnet.org/software/execline/exitcodes.html">execline exit code handling</a>.
+			</li>
+		</ul>
+		<h2>Options</h2>
+		<ul>
+			<li>
+    			There are no options to system-init.
+			</li>
+		</ul>
+		<h2>Notes</h2>
+		<p>
+			system-init is primarily intended to be used
+			as an init for an acutal boot process, not for containers.
+		</p>
+	</body>
+</html>
diff --git a/doc/bin/system-shutdown.html b/doc/bin/system-shutdown.html
new file mode 100644
index 0000000..c20d0a1
--- /dev/null
+++ b/doc/bin/system-shutdown.html
@@ -0,0 +1,88 @@
+<!DOCTYPE html>
+<html>
+	<head>
+    	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    	<meta http-equiv="Content-Language" content="en" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    	<title>system-shutdown</title>
+    	<meta name="Description" content="Client side shutdown command responsible for starting the service responsible for actual shutdown." />
+    	<meta name="Keywords" content="goetia s6 s6-rc FreeBSD shutdown" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-freebsd-init">goetia-freebsd-init</a>
+			<br />
+			<a href="//0x53.net/software/goetia">goetia</a>
+			<br />
+			<a href="//0x53.net/software">Software</a>
+			<br />
+			<a href="//0x53.net">0x53.net</a>
+		</p>
+	</header>
+	<body>
+		<h1>The system-shutdown program</h1>
+		<p>
+			system-shutdown is the interface to the
+			<a href="//0x53.net/software/goetia/goetia-base/bin/system-shutdown-daemon.html">system-shutdown-daemon</a>.
+		</p>
+		<h2>Interface</h2>
+		<pre>     system-shutdown -h | -p | -r</pre>
+		<ul>
+			<li>
+    			system-shutdown writes its argument to the file <code>DIRECTIVE</code> in the envdir at the
+    			<code>shutdown-directive</code> subdirectory of the
+    			<a href="//0x53.net/software/goetia/rundir.html#system">system runtime directory</a>.
+			</li>
+			<li>
+    			It continues to initiate the shutdown sequence by starting the service
+    			<a href="//0x53.net/software/goetia/goetia-freebsd-init/service/system/goetia-shutdown.html">goetia-shutdown</a>.
+			</li>
+		</ul>
+		<h2>Options</h2>
+		<ul>
+			<li>
+    			<code>-h</code>: at the end of the shutdown sequence, halt the system.
+			</li>
+			<li>
+    			<code>-p</code>: at the end of the shutdown sequence, poweroff the system.
+			</li>
+			<li>
+    			<code>-r</code>: at the end of the shutdown sequence, reboot the system.
+			</li>
+		</ul>
+		<h2>Exit codes</h2>
+		<ul>
+			<li>
+    			system-shutdown exits 100 if wrong options were used.
+			</li>
+			<li>
+    			Since system-shutdown is an
+				<a href="https://skarnet.org/software/execline/">execline</a>
+				script, it exits with an approximation
+				of employed program that failed.
+			</li>
+			<li>
+    			system-shutdown mostly uses
+				<a href="https://skarnet.org/software/execline/">execline</a>
+				and
+				<a href="https://skarnet.org/software/s6/">s6</a>
+				software, the exit behaviour of which can be looked up on
+				their respective pages.
+			</li>
+			<li>
+    			See also:
+				<a href="https://skarnet.org/software/execline/exitcodes.html">execline exit code handling</a>.
+			</li>
+		</ul>
+		<h2>Notes</h2>
+		<p>
+			There is a reason this program exists as part of (multiple)
+			goetia-init packages and not as part of
+			<a href="//0x53.net/software/goetia/goetia-base">goetia-base</a>.
+			It is that some supported init systems, like
+			<a href="https://skarnet.org/software/s6-linux-init/">s6-linux-init</a>
+			(through <a href="//0x53.net/software/goetia/goetia-s6-linux-init">goetia-s6-linux-init</a>)
+			provide their own shutdown procedure and interface.
+		</p>
+	</body>
+</html>
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..38cb5a0
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,113 @@
+<!DOCTYPE html>
+<html>
+	<head>
+    	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    	<meta http-equiv="Content-Language" content="en" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    	<title>goetia-freebsd-init</title>
+    	<meta name="Description" content="goetia-freebsd-init contains minimal init and shutdown scripts for FreeBSD." />
+    	<meta name="Keywords" content="goetia s6 s6-rc FreeBSD init shutdown" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia">goetia</a>
+			<br />
+			<a href="//0x53.net/software">Software</a>
+			<br />
+			<a href="//0x53.net">0x53.net</a>
+		</p>
+	</header>
+	<body>
+		<h1>goetia-freebsd-init</h1>
+		<h2>What is it?</h2>
+		<p>
+			goetia-freebsd-init contains
+			init and shutdown scripts for running goetia on a
+			FreeBSD operating system.
+			Additionally, it contains
+			<a href="https://skarnet.org/software/s6/servicedir.html">service directories</a>
+			specific to this init system.
+		</p>
+		<hr>
+		<h2>Installation</h2>
+		<h3>Requirements</h3>
+		<ul>
+			<li>
+    			A POSIX-compliant implementation of make, or GNU make
+			</li>
+			<li>
+    			A set of POSIX and kernel specific tools as described in the general
+				<a href="//0x53.net/software/requirements.html">requirements</a>.
+				This is a runtime requirement
+			</li>
+			<li>
+    			<a href="//0x53.net/software/goetia/goetia-base">goetia-base</a>,
+				this is a runtime requirement
+			</li>
+			<li>
+    			The package and its runtime requirements need to reside at
+    			the root partition.
+			</li>
+		</ul>
+		<h3>Licensing</h3>
+		<p>
+			goetia-freebsd-init is free software. It is available under the
+			<a href="https://opensource.org/licenses/ISC">ISC license</a>.
+		</p>
+		<h3>Download</h3>
+		<ul>
+			<!--
+			<li>
+    			The current released version of goetia-freebsd-init is
+				<a href="./goetia-freebsd-init-0.0.1.0.tar.gz">0.0.1.0</a>.
+				You can access its checksum
+				<a href="./goetia-freebsd-init-0.0.1.0.tar.gz.sha256">here</a>.
+			</li>
+			-->
+			<li>
+    			Alternatively, you can checkout a copy of the
+				<a href="https://git.0x53.net/goetia-freebsd-init">goetia-freebsd-init git repository</a>:
+				<pre>git clone git://git.0x53.net/goetia-freebsd-init</pre>
+			</li>
+		</ul>
+		<h3>Compilation</h3>
+		<ul>
+			<li>
+    			See the enclosed INSTALL file for installation details.
+			</li>
+		</ul>
+		<hr>
+		<h2>Reference</h2>
+		<section id="bin">
+			<h3>Commands</h3>
+			<p>
+				All of the following are
+				<a href="https://skarnet.org/software/execline/">execline</a>
+				scripts.
+			</p>
+			<ul>
+				<li>
+    				<a href="./bin/system-init.html">system-init</a>
+				</li>
+				<li>
+    				<a href="./bin/system-shutdown.html">system-shutdown</a>
+				</li>
+			</ul>
+		</section>
+		<section id="service">
+			<h3>Service directories</h3>
+			<p>
+				Service directories specific to the Linux Kernel
+				and to this init system.
+			</p>
+			<ul>
+				<li>
+    				<a href="./service/system/.s6-svscan.html">.s6-svscan</a>
+				</li>
+				<li>
+    				<a href="./service/system/goetia-shutdown.html">goetia-shutdown</a>
+				</li>
+			</ul>
+		</section>
+	</body>
+</html>
diff --git a/doc/service/system/.s6-svscan.html b/doc/service/system/.s6-svscan.html
new file mode 100644
index 0000000..46e0db1
--- /dev/null
+++ b/doc/service/system/.s6-svscan.html
@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html>
+	<head>
+    	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    	<meta http-equiv="Content-Language" content="en" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    	<title>system .s6-svscan</title>
+    	<meta name="Description" content="Configuration directory for s6-svscan for the system supervision tree" />
+    	<meta name="Keywords" content="goetia s6 s6-svscan system supervision tree" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-freebsd-init">goetia-freebsd-init</a>
+			<br />
+			<a href="//0x53.net/software/goetia">goetia</a>
+			<br />
+			<a href="//0x53.net/software">Software</a>
+			<br />
+			<a href="//0x53.net">0x53.net</a>
+		</p>
+	</header>
+	<body>
+		<h1>The system .s6-svscan directory</h1>
+		<p>
+			The .s6-svscan directory contains scripts
+			that are executed if
+			<a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
+			receives a signal or exits.
+			In this case its main use is to properly shutdown
+			the system using <code>system-shutdown</code>
+			upon receiving certain signals.
+		</p>
+		<p>
+			The .s6-svscan directory is easily overlooked,
+			do not forget to symlink/copy it!
+		</p>
+	</body>
+</html>
diff --git a/doc/service/system/goetia-shutdown.html b/doc/service/system/goetia-shutdown.html
new file mode 100644
index 0000000..7f6a866
--- /dev/null
+++ b/doc/service/system/goetia-shutdown.html
@@ -0,0 +1,133 @@
+<!DOCTYPE html>
+<html>
+	<head>
+    	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    	<meta http-equiv="Content-Language" content="en" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    	<title>goetia-shutdown</title>
+    	<meta name="Description" content="Shutdown service for FreeBSD providing the actual shutdown procedure." />
+    	<meta name="Keywords" content="goetia s6 s6-rc service FreeBSD shutdown" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-freebsd-init">goetia-freebsd-init</a>
+			<br />
+			<a href="//0x53.net/software/goetia">goetia</a>
+			<br />
+			<a href="//0x53.net/software">Software</a>
+			<br />
+			<a href="//0x53.net">0x53.net</a>
+		</p>
+	</header>
+	<body>
+		<h1>The goetia-shutdown service</h1>
+		<p>
+			goetia-shutdown is the service that starts
+			<a href="//0x53.net/software/goetia/goetia-base/bin/system-shutdown-daemon.html">system-shutdown-daemon</a>.
+			goetia-shutdown is down by default.
+			Starting it initiates the shutdown procedure.
+		</p>
+		<p>
+			goetia-shutdown consists of three scripts:
+		</p>
+		<h2>run</h2>
+		<ul>
+			<li>
+    			This script just executes system-shutdown-daemon.
+			</li>
+		</ul>
+		<h2>stage3b</h2>
+		<ul>
+			<li>
+    			stage3b tries to execute <code>./stage4</code>,
+				which is by default not executable.
+				If it can not execute <code>./stage4</code>,
+				and <em>only</em> in this case,
+				it continues with the following.
+			</li>
+			<li>
+    			It makes <code>./stage4</code> executable.
+			</li>
+			<li>
+    			It sends SIGCONT to all processes.
+			</li>
+			<li>
+    			It sleeps for 1 second.
+			</li>
+			<li>
+    			It writes a banner to its standard out.
+			</li>
+			<li>
+    			It send SIGKILL to all processes.
+			</li>
+			<li>
+    			This also stops the system-shutdown-daemon process.
+				It is automatically restarted by the system supervision tree,
+				but this time, <em>both</em> the files
+				<code>./stage3b</code> and
+				<code>./stage4</code>
+				are executable.
+				Which leads to the execution of <code>./stage4</code>.
+			</li>
+		</ul>
+		<h2>stage4</h2>
+		<ul>
+    		<li>
+    			stage4 reads the envdir at the
+    			<code>shutdown-directive</code> subdirectory of the
+    			<a href="//0x53.net/software/goetia/rundir.html#system">system runtimedirectory</a>
+    			using
+    			<a href="https://skarnet.org/software/s6/s6-envdir.html">s6-envdir</a>.
+			</li>
+			<li>
+    			It reads the <code>DIRECTIVE</code> evironment variable,
+    			defaulting to <code>-r</code>, if <code>DIRECTIVE</code> is
+    			not specified.
+			</li>
+			<li>
+    			It runs <code>umount -A</code>.
+			</li>
+			<li>
+    			It remounts the root filesystem read-only.
+			</li>
+			<li>
+    			It runs <code>shutdown -o ${DIRECTIVE} now</code>.
+			</li>
+		</ul>
+		<h2>Notes</h2>
+		<p>
+			The entire shutdown procedure roughly works as follows:
+		</p>
+		<ul>
+			<li>
+    			This service, running
+				<a href="//0x53.net/software/goetia/goetia-base/bin/system-shutdown-daemon.html">system-shutdown-daemon</a>
+				gets the instructions from
+				<a href="//0x53.net/software/goetia/goetia-freebsd-init/bin/system-shutdown.html">system-shutdown</a>
+				to shutdown.
+			</li>
+			<li>
+    			system-shutdown-daemon does most of the shutdown procedure.
+				Part of it is to make stage3b executable.
+				In the end, system-shutdown-daemon sends SIGTERM to all processes but
+				PID 1, including itself.
+			</li>
+			<li>
+    			this service gets restarted automatically.
+				system-shutdown-daemon now instantly executes into stage3b.
+			</li>
+			<li>
+    			stage3b makes stage4 executable.
+				Followed by sending SIGKILL to all processes
+				but PID 1, including itself.
+			</li>
+			<li>
+    			The final restart of this service causes
+				system-shutdown-daemon to instantly execute into
+				stage3b which instantly executes into stage4,
+				which instructs the Kernel to do the actual
+				halt, poweroff or reboot.
+			</li>
+		</ul>
+	</body>
+</html>
author	PS <p@0x53.net>	2026-02-07 10:34:21 +0100
committer	PS <p@0x53.net>	2026-02-07 10:34:21 +0100
commit	eb36640078ee6469427e85ca0695f8c920909ea0 (patch)
tree	4e490a9b3b4e2f2c07bf261acde1d8ac70bb87d0 /doc
parent	891a3316a22acdc57a2e65429f4d59ada268410c (diff)
download	goetia-freebsd-init-eb36640078ee6469427e85ca0695f8c920909ea0.tar.gz goetia-freebsd-init-eb36640078ee6469427e85ca0695f8c920909ea0.tar.bz2 goetia-freebsd-init-eb36640078ee6469427e85ca0695f8c920909ea0.zip