From 5e95d487982b9362b544139b98d1da55fa6ef78c Mon Sep 17 00:00:00 2001 From: PS
Date: Sat, 7 Feb 2026 10:20:30 +0100 Subject: Add doc --- doc/bin/compile-db.html | 98 +++++++++++++++++++++++++ doc/bin/longrun-make.html | 141 ++++++++++++++++++++++++++++++++++++ doc/bin/oneshot-make.html | 101 ++++++++++++++++++++++++++ doc/bin/prepare-svscan.html | 120 ++++++++++++++++++++++++++++++ doc/bin/system-db.html | 67 +++++++++++++++++ doc/bin/system-ml.html | 96 ++++++++++++++++++++++++ doc/bin/system-rc.html | 63 ++++++++++++++++ doc/bin/system-run.html | 67 +++++++++++++++++ doc/bin/system-shutdown-daemon.html | 123 +++++++++++++++++++++++++++++++ doc/bin/user-db.html | 82 +++++++++++++++++++++ doc/bin/user-init.html | 128 ++++++++++++++++++++++++++++++++ doc/bin/user-ml.html | 104 ++++++++++++++++++++++++++ doc/bin/user-rc.html | 74 +++++++++++++++++++ doc/bin/user-run.html | 78 ++++++++++++++++++++ doc/bin/user-shutdown.html | 68 +++++++++++++++++ doc/bin/user-tmpfs.html | 104 ++++++++++++++++++++++++++ 16 files changed, 1514 insertions(+) create mode 100644 doc/bin/compile-db.html create mode 100644 doc/bin/longrun-make.html create mode 100644 doc/bin/oneshot-make.html create mode 100644 doc/bin/prepare-svscan.html create mode 100644 doc/bin/system-db.html create mode 100644 doc/bin/system-ml.html create mode 100644 doc/bin/system-rc.html create mode 100644 doc/bin/system-run.html create mode 100644 doc/bin/system-shutdown-daemon.html create mode 100644 doc/bin/user-db.html create mode 100644 doc/bin/user-init.html create mode 100644 doc/bin/user-ml.html create mode 100644 doc/bin/user-rc.html create mode 100644 doc/bin/user-run.html create mode 100644 doc/bin/user-shutdown.html create mode 100644 doc/bin/user-tmpfs.html (limited to 'doc/bin') diff --git a/doc/bin/compile-db.html b/doc/bin/compile-db.html new file mode 100644 index 0000000..c0ed957 --- /dev/null +++ b/doc/bin/compile-db.html @@ -0,0 +1,98 @@ + + +
+ + + +
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ compile-db is a helper script for use by other software
+ that compiles a general confdir
+ tries to use the result to update a general
+ livedir.
+
compile-db confdir livedir+
confdir/src/*.
+ confdir/@xyz@_db
+ file with @xyz@ based on the current UNIX time.
+ livedir exists, that is,
+ a goetia based supervision tree is running,
+ compile-db the tries to update the live state at livedir
+ to @xyz@_db using
+ s6-rc-update.
+ confdir/compiled
+ to point to
+ confdir/@xyz@_db
+ and deletes the old database
+ confdir/@abc@_db.
+ confdir/compiled
+ which points to
+ confdir/@abc@_db.
+ Followed by deleting
+ confdir/@xyz@_db.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ longrun-make contains boilerplate code + required to create the + source directory + of a longrun service + based on strings. +
+longrun-make workingdir name type script dependencies+
type can only be one of log | srv.
+ dependencies can only be one of "dependency1 dependency2 ..." | none.
+ workingdir/name-type.
+ workingdir/name-type/type
+ (literal "type") and writes the line longrun to it.
+ workingdir/name-type/notification-fd
+ and writes the line 3 to it.
+ workingdir/name-type/run
+ and writes script to it.
+ type is log and the file
+ workingdir/name-type/consumer-for
+ does not contain the string name:
+ workingdir/name-type/consumer-for
+ using
+ s6-setlock.
+ name-srv to the file
+ workingdir/name-type/consumer-for
+ creating it if it does not exist.
+ workingdir/name-type/pipeline-name,
+ truncating it if it does exist and adds the string name.
+ type is srv:
+ workingdir/name-type/producer-for
+ is created, truncated and the string name-log is added.
+ dependencies is not none:
+ workingdir/name-type/dependencies.d
+ is created.
+ "dependency1 dependency2 ..." in
+ dependencies separated by spaces,
+ a file
+ workingdir/name-type/dependencies.d/dependency
+ is created.
+ + longrun-make is, by means of locking and checking for duplicates, + specifically designed to allow parallel creation of logging + source directories. +
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ oneshot-make contains boilerplate code + required to create the + source directory + of a oneshot service + based on strings. +
+oneshot-make workingdir name upscript downscript dependencies+
dependencies can only be one of "dependency1 dependency2 ..." | none.
+ workingdir/name
+ workingdir/name/type
+ and writes the line oneshot to it.
+ workingdir/name/up
+ and writes upscript to it.
+ workingdir/name/down
+ and writes downscript to it.
+ dependencies is not none:
+ workingdir/name/dependencies.d
+ is created.
+ "dependency1 dependency2 ..." in
+ dependencies separated by spaces,
+ a file
+ workingdir/name/dependencies.d/dependency
+ is created.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ prepare-svscan does generic preparation of the + supervision tree. + It is also used in system-init and + user-init. +
+prepare-svscan workingdir rundir bundle prog...+
/dev/null.
+ 0022.
+ rundir.
+ workingdir/run-image/.
+ to rundir/.
+ rundir/service/s6-svscan-log/fifo.
+ rundir/service/s6-svscan-log/fifo.
+ rundir/s6-rc does not exist,
+ rundir/service using
+ s6-rc-init
+ and starts the bundle bundle using s6-rc.
+ workingdir/env is sourced using
+ s6-env.
+ prog...,
+ which is usually directly or indirectly
+ s6-svscan.
+
+ Once s6-svscan is launched it will start an
+ s6-supervise
+ process on rundir/service/s6-svscan-log which starts
+ s6-log reading
+ from rundir/service/s6-svscan-log/fifo.
+ This in turn triggers the forked background process to continue with its second step.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ system-db compiles the + source directories + of the + system configuration directory + into the compiled format. + This format can then be used by init and + system-rc + to set up and control a + system supervision tree. +
++ system-db is a wrapper around the more general + compile-db + making it target the system supervision tree. +
+system-db+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ system-ml automatically creates logging service + source directories + for longrun services in the + system configuration directory. + To create the logging service source directories, + system-ml uses + longrun-make internally. +
+system-ml+
src/generated-logger subdirectory of the
+ system configuration directory.
+ src subdirecotry of the
+ system configuration directory
+ for longrun services.
+ no-ml.
+ If this file exits, this longrun is skipped in the subsequent logger generation.
+ src/generated-logger/@longrun@-log
+ in the system configuration directory.
+ It does so in parallel for each longrun @longrun@-srv it found.
+
+ The logger services created by this script
+ will drop privileges to
+ @loguser@,
+ which must exist at runtime.
+ (see log directory).
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ system-rc is a thin convenience wrapper around + s6-rc + doing nothing more then pointing it to the right livedir. +
++ Read the page of + s6-rc + to understand what this utility does. +
+system-rc ... see s6-rc ...+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ system-run allows + to hand over the execution of commands to the + system supervision tree. +
+system-run prog...+
prog... is then transferred
+ to and executed by goetia-runner.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ system-shutdown-daemon contains the Kernel independent + part of the shutdown sequence. + It is invoked by the Kernel specifict goetia-shutdown service, + e.g. + goetia-shutdown service for Linux + or + goetia-shutdown service for FreeBSD. + system-shutdown-daemon is a long lived program that waits for instruction by the system-shutdown command + The latter is part of the Kernel specific packages, e.g. + goetia-linux + or + goetia-freebsd. +
+system-shutdown-daemon+
./stage3b,
+ which is by default not executable.
+ If it can not execute ./stage3b,
+ and only in this case,
+ it continues with the following.
+ src subdirectory of the
+ system configuration directory.
+ stage3b, expected to exist in the current working directory
+ is made executable.
+ This file is part of the Kernel secific service directories.
+ (see e.g. goetia-shutdown)
+ log/uncaught-logs
+ subdirectory of the
+ system runtime directory.
+ to the
+ uncaught-logs
+ subdirectory of the
+ system log directory.
+ ./stage3b is executable
+ and executed instead of what is described above.
+ What happens in ./stage3b is Kernel specific,
+ and documented on
+ goetia-shutdown service for Linux,
+ goetia-shutdown service for FreeBSD,
+ etc.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ user-db compiles the + source directories + of the + user configuration directory + into the compiled format. + This format can then be used by init and + user-rc + to set up and control a + user supervision tree. +
++ user-db is a wrapper around the more general + compile-db + making it target the user supervision tree. +
+user-db+
USER environment variable,
+ if it is empty it exits 100.
+ USERTREE environment variable,
+ if it is empty it exits 100.
+ HOME environment variable,
+ if it is empty it exits 100.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ user-init starts a user supervision tree for
+ the user defined in the USER
+ environment variable.
+
user-init+
USER environment variable,
+ if it is empty it exits 100.
+ USERTREE environment variable,
+ if it is empty it exits 100.
+ BUNDLE environment variable,
+ defaulting to default if empty.
+ PATH environment variable,
+ defaulting to
+ /command:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/libexec:/usr/local/libexec
+ if empty.
+ ${USER}/${USERTREE} subdirectory of the
+ runtime directory
+ olready existis, it exits 100.
+ HOME environment variable based on the result of
+ homeof.
+ ${HOME}/.local/bin: to the PATH
+ environment variable.
+ UID, GID and GIDLIST
+ environment variables using
+ s6-envuidgid.
+ prepare-svscan
+ with the proper arguments.
+ s6-svscan
+ on the scandir represented by the
+ ${USER}/${USERTREE}/service
+ subdirectory of the
+ user runtime directory.
+ + More information about user supervision trees + themselves can be found on the + user supervision tree + page. +
+ + diff --git a/doc/bin/user-ml.html b/doc/bin/user-ml.html new file mode 100644 index 0000000..d6d7e2e --- /dev/null +++ b/doc/bin/user-ml.html @@ -0,0 +1,104 @@ + + + + + + +
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ user-ml automatically creates logging service + source directories + for longrun services of the + user configuration directory. + To create the logging service source directories, + user-ml uses + longrun-make internally. +
+user-ml+
USER environment variable,
+ if it is empty it exits 100.
+ USERTREE environment variable,
+ if it is empty it exits 100.
+ HOME environment variable,
+ if it is empty it exits 100.
+ ${USERTREE}/src/generated-logger subdirectory
+ of the user configuration subdirectory.
+ ${USERTREE}/src subdirectory
+ of the user configuration subdirectory
+ for longrun services.
+ no-ml.
+ If this file exits, this longrun is skipped in the subsequent logger generation.
+ ${USERTREE}/src/generated-logger/@longrun@-log
+ in parallel for each longrun @longrun@-srv it found
+ in the user configuration subdirectory.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ The user-rc program is a thin convenience wrapper around + s6-rc + doing nothing more then pointing it to the right livedir. +
++ Read the page of + s6-rc + to understand what this utility does. +
+user-rc ... see s6-rc ...+
USER environment variable,
+ if it is empty it exits 100.
+ USERTREE environment variable,
+ if it is empty it exits 100.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ The user-run program allows + to hand over the execution of commands to the + user supervision tree. +
+user-run prog...+
USER environment variable,
+ if it is empty it exits 100.
+ USERTREE environment variable,
+ if it is empty it exits 100.
+ prog... is then transferred
+ to and executed by goetia-runner.
+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ The user-shutdown program is used to tear down + user supervision trees. +
+user-shutdown+
+ goetia-base
+
+ goetia
+
+ Software
+
+ 0x53.net
+
+ The user-tmpfs program prepares
+ a user owned tmpfs for
+ the user defined in the USER
+ environment variable.
+ The user owned tmpfs is created at
+ @tmpfsdir@/@usrrundir@/${USER}.
+
user-tmpfs+
USER environment variable,
+ if it is empty it exits 100.
+ USER_TMPFSDIR_SIZE environment variable,
+ defaulting to 64m if undefined.
+ @tmpfsdir@/@usrrundir@/${USER}.
+ USER_TMPFSDIR_SIZE
+ with its root owned bi USER
+ and mode 0755
+ at @tmpfsdir@/@usrrundir@/${USER}.
+ + user-tmpfs is intended to be used in a boot time + system supervision tree + oneshot service to prepare the + user runtime directory + of a user. + For each user who should have a user runtime directory, + there should be a distinct oneshot running user-tmpfs. +
++ Alternatively, user-tmpfs could be run by a login manager + after login, but befor initiating the first + user supervision tree. +
+ + -- cgit v1.2.3