Add doc

author: PS <p@0x53.net> 2026-02-07 10:37:36 +0100
committer: PS <p@0x53.net> 2026-02-07 10:37:36 +0100
commit: 02a071125de739ed54660ad014ffd57c42516abf (patch)
tree: 719d4127af9dc8dfa854042be8b47d3bf7356ef7
parent: 291a2d0ad47d29d7f4e83da47efb3a125f3667fc (diff)
download: goetia-linux-init-02a071125de739ed54660ad014ffd57c42516abf.tar.gz
goetia-linux-init-02a071125de739ed54660ad014ffd57c42516abf.tar.bz2
goetia-linux-init-02a071125de739ed54660ad014ffd57c42516abf.zip
5 files changed, 507 insertions, 0 deletions
diff --git a/doc/bin/system-init.html b/doc/bin/system-init.html
new file mode 100644
index 0000000..7b3df53
--- /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 Linux." />
+    	<meta name="Keywords" content="goetia s6 s6-rc Linux" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-linux-init">goetia-linux-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>uncaught-logs/</code>
+				subdirectory of the
+				<a href="//0x53.net/software/goetia/logdir.html#system">system log directory</a>
+				to the
+				<code>log/</code>
+				subdirectory of the
+				<a href="//0x53.net/software/goetia/rundir.html#system">system 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>service/</code>
+				subdirectory of the
+				<a href="//0x53.net/software/goetia/rundir.html#system">system 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..ac2758c
--- /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 Linux shutdown" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-linux-init">goetia-linux-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-linux-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..2ff7296
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,116 @@
+<!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-linux-init</title>
+    	<meta name="Description" content="goetia-linux-init contains minimal init and shutdown scripts for Linux." />
+    	<meta name="Keywords" content="goetia s6 s6-rc Linux 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-linux-init</h1>
+		<h2>What is it?</h2>
+		<p>
+			goetia-linux-init contains
+			init and shutdown scripts for running goetia on a Linux Kernel.
+			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/linux-supplements/">linux-supplements</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-linux-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-linux-init is
+				<a href="./goetia-linux-init-0.0.1.0.tar.gz">0.0.1.0</a>.
+				You can access its checksum
+				<a href="./goetia-linux-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-linux-init">goetia-linux-init git repository</a>:
+				<pre>git clone git://git.0x53.net/goetia-linux-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..2b1b437
--- /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-linux-init">goetia-linux-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..2dd3728
--- /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 Linux providing the actual shutdown procedure." />
+    	<meta name="Keywords" content="goetia s6 s6-rc service Linux shutdown" />
+	</head>
+	<header>
+		<p>
+			<a href="//0x53.net/software/goetia/goetia-linux-init">goetia-linux-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>linux-powertool ${DIRECTIVE}</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-linux-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:37:36 +0100
committer	PS <p@0x53.net>	2026-02-07 10:37:36 +0100
commit	02a071125de739ed54660ad014ffd57c42516abf (patch)
tree	719d4127af9dc8dfa854042be8b47d3bf7356ef7
parent	291a2d0ad47d29d7f4e83da47efb3a125f3667fc (diff)
download	goetia-linux-init-02a071125de739ed54660ad014ffd57c42516abf.tar.gz goetia-linux-init-02a071125de739ed54660ad014ffd57c42516abf.tar.bz2 goetia-linux-init-02a071125de739ed54660ad014ffd57c42516abf.zip