From eb36640078ee6469427e85ca0695f8c920909ea0 Mon Sep 17 00:00:00 2001 From: PS Date: Sat, 7 Feb 2026 10:34:21 +0100 Subject: Add doc --- doc/bin/system-init.html | 132 +++++++++++++++++++++++++++++++ doc/bin/system-shutdown.html | 88 +++++++++++++++++++++ doc/index.html | 113 +++++++++++++++++++++++++++ doc/service/system/.s6-svscan.html | 38 +++++++++ doc/service/system/goetia-shutdown.html | 133 ++++++++++++++++++++++++++++++++ 5 files changed, 504 insertions(+) create mode 100644 doc/bin/system-init.html create mode 100644 doc/bin/system-shutdown.html create mode 100644 doc/index.html create mode 100644 doc/service/system/.s6-svscan.html create mode 100644 doc/service/system/goetia-shutdown.html 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 @@ + + + + + + + system-init + + + +

+ goetia-freebsd-init +
+ goetia +
+ Software +
+ 0x53.net +

+ +

The system-init program

+ system-init is a minimal, scripted init to bring up a goetia based system. +

Interface

     system-init

+ system-init takes no arguments. +
+ It makes /dev/console its stdout and stderr. +
+ It reads the environment variable BUNDLE, + which can be specified on the Kernel command line. + If it is undefined, it uses default as the value. +
+ It reads the environment variable PATH, + which can be specified on the Kernel command line. + If it is undefined, it uses + /command:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/libexec:/usr/local/libexec + as the value. +
+ It sets the PATH environment variable to the value + chosen above. +
+ It chdirs to /. +
+ It runs s6-setsid + to become the session leader. +
+ It creates the + runtime directory + if it does not already exist. +
+ It mounts the + runtime directory + tmpfs. +
+ It copies the old system logs from the + system/uncaught-logs + subdirectory of the + log directory + to the + system/ + subdirectory of the + runtime directory + if they exist. +
+ It runs + prepare-svscan + with the proper arguments. +
+ Finally, it executes into + s6-svscan + on the scandir represented by the + system/service + subdirectory of the + runtime directory. +

Exit codes

+ system-init usually executes into + s6-svscan + which exits according to its page. +
+ Since system-init is an + execline + script, it exits with an approximation + of employed program that failed. +
+ system-init mostly uses + execline + and + s6 + software, the exit behaviour of which can be looked up on + their respective pages. +
+ See also: + execline exit code handling. +

Options

+ There are no options to system-init. +

Notes

+ system-init is primarily intended to be used + as an init for an acutal boot process, not for containers. +

+ + 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 @@ + + + + + + + system-shutdown + + + +

+ goetia-freebsd-init +
+ goetia +
+ Software +
+ 0x53.net +

+ +

The system-shutdown program

+ system-shutdown is the interface to the + system-shutdown-daemon. +

Interface

     system-shutdown -h | -p | -r

+ system-shutdown writes its argument to the file DIRECTIVE in the envdir at the + shutdown-directive subdirectory of the + system runtime directory. +
+ It continues to initiate the shutdown sequence by starting the service + goetia-shutdown. +

Options

+ -h: at the end of the shutdown sequence, halt the system. +
+ -p: at the end of the shutdown sequence, poweroff the system. +
+ -r: at the end of the shutdown sequence, reboot the system. +

Exit codes

+ system-shutdown exits 100 if wrong options were used. +
+ Since system-shutdown is an + execline + script, it exits with an approximation + of employed program that failed. +
+ system-shutdown mostly uses + execline + and + s6 + software, the exit behaviour of which can be looked up on + their respective pages. +
+ See also: + execline exit code handling. +

Notes

+ There is a reason this program exists as part of (multiple) + goetia-init packages and not as part of + goetia-base. + It is that some supported init systems, like + s6-linux-init + (through goetia-s6-linux-init) + provide their own shutdown procedure and interface. +

+ + 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 @@ + + + + + + + goetia-freebsd-init + + + +

+ goetia +
+ Software +
+ 0x53.net +

+ +

goetia-freebsd-init

What is it?

+ goetia-freebsd-init contains + init and shutdown scripts for running goetia on a + FreeBSD operating system. + Additionally, it contains + service directories + specific to this init system. +

Installation

Requirements

+ A POSIX-compliant implementation of make, or GNU make +
+ A set of POSIX and kernel specific tools as described in the general + requirements. + This is a runtime requirement +
+ goetia-base, + this is a runtime requirement +
+ The package and its runtime requirements need to reside at + the root partition. +

Licensing

+ goetia-freebsd-init is free software. It is available under the + ISC license. +

Download

+ Alternatively, you can checkout a copy of the + goetia-freebsd-init git repository: +
```
git clone git://git.0x53.net/goetia-freebsd-init
```
+

Compilation

+ See the enclosed INSTALL file for installation details. +

Reference

Commands

+ All of the following are + execline + scripts. +

+ system-init +
+ system-shutdown +

Service directories

+ Service directories specific to the Linux Kernel + and to this init system. +

+ .s6-svscan +
+ goetia-shutdown +

+ + 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 @@ + + + + + + + system .s6-svscan + + + +

+ goetia-freebsd-init +
+ goetia +
+ Software +
+ 0x53.net +

+ +

The system .s6-svscan directory

+ The .s6-svscan directory contains scripts + that are executed if + s6-svscan + receives a signal or exits. + In this case its main use is to properly shutdown + the system using system-shutdown + upon receiving certain signals. +

+ The .s6-svscan directory is easily overlooked, + do not forget to symlink/copy it! +

+ + 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 @@ + + + + + + + goetia-shutdown + + + +

+ goetia-freebsd-init +
+ goetia +
+ Software +
+ 0x53.net +

+ +

The goetia-shutdown service

+ goetia-shutdown is the service that starts + system-shutdown-daemon. + goetia-shutdown is down by default. + Starting it initiates the shutdown procedure. +

+ goetia-shutdown consists of three scripts: +

run

+ This script just executes system-shutdown-daemon. +

stage3b

+ stage3b tries to execute ./stage4, + which is by default not executable. + If it can not execute ./stage4, + and only in this case, + it continues with the following. +
+ It makes ./stage4 executable. +
+ It sends SIGCONT to all processes. +
+ It sleeps for 1 second. +
+ It writes a banner to its standard out. +
+ It send SIGKILL to all processes. +
+ This also stops the system-shutdown-daemon process. + It is automatically restarted by the system supervision tree, + but this time, both the files + ./stage3b and + ./stage4 + are executable. + Which leads to the execution of ./stage4. +

stage4

+ stage4 reads the envdir at the + shutdown-directive subdirectory of the + system runtimedirectory + using + s6-envdir. +
+ It reads the DIRECTIVE evironment variable, + defaulting to -r, if DIRECTIVE is + not specified. +
+ It runs umount -A. +
+ It remounts the root filesystem read-only. +
+ It runs shutdown -o ${DIRECTIVE} now. +

Notes

+ The entire shutdown procedure roughly works as follows: +

+ This service, running + system-shutdown-daemon + gets the instructions from + system-shutdown + to shutdown. +
+ 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. +
+ this service gets restarted automatically. + system-shutdown-daemon now instantly executes into stage3b. +
+ stage3b makes stage4 executable. + Followed by sending SIGKILL to all processes + but PID 1, including itself. +
+ 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. +

+ + -- cgit v1.2.3