diff options
Diffstat (limited to 'doc')
38 files changed, 2796 insertions, 0 deletions
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 @@ +<!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>compile-db</title> + <meta name="Description" content="A helper script for compiling s6-rc databases." /> + <meta name="Keywords" content="goetia s6-rc s6-rc-compile source directory" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 compile-db program</h1> + <p> + compile-db is a helper script for use by other software + that compiles a general <code><em>confdir</em></code> + tries to use the result to update a general + <code><em>livedir</em></code>. + </p> + <h2>Interface</h2> + <pre> compile-db <em>confdir</em> <em>livedir</em></pre> + <ul> + <li> + compile-db runs + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html">s6-rc-compile</a> + on <code><em>confdir</em>/src/*</code>. + </li> + <li> + This creates a new <code><em>confdir</em>/<var>@xyz@</var>_db</code> + file with <code><var>@xyz@</var></code> based on the current UNIX time. + </li> + <li> + If <code><em>livedir</em></code> exists, that is, + a goetia based supervision tree is running, + compile-db the tries to update the live state at <code><em>livedir</em></code> + to <code><var>@xyz@</var>_db</code> using + <a href="https://skarnet.org/software/s6-rc/s6-rc-update.html">s6-rc-update</a>. + </li> + <li> + If it succeeds, it updates the symlink + <code><em>confdir</em>/compiled</code> + to point to + <code><em>confdir</em>/<var>@xyz@</var>_db</code> + and deletes the old database + <code><em>confdir</em>/<var>@abc@</var>_db</code>. + </li> + <li> + If it does <em>not</em> succeed, + it runs s6-rc-update to switch back to + <code><em>confdir</em>/compiled</code> + which points to + <code><em>confdir</em>/<var>@abc@</var>_db</code>. + Followed by deleting + <code><em>confdir</em>/<var>@xyz@</var>_db</code>. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 0: success + </li> + <li> + Since compile-db is an + <a href="https://skarnet.org/software/execline/">execline</a> + script, it exits with an approximation + of employed program that failed. + </li> + <li> + compile-db 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 otions to compile-db. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/longrun-make.html b/doc/bin/longrun-make.html new file mode 100644 index 0000000..0c5d8c4 --- /dev/null +++ b/doc/bin/longrun-make.html @@ -0,0 +1,141 @@ +<!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>longrun-make</title> + <meta name="Description" content="Helper script to generate s6-rc longrun source directories from a commandline." /> + <meta name="Keywords" content="goetia s6-rc longrun source directory" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 longrun-make program</h1> + <p> + longrun-make contains boilerplate code + required to create the + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directory</a> + of a longrun service + based on strings. + </p> + <h2>Interface</h2> + <pre> longrun-make <em>workingdir</em> <em>name</em> <em>type</em> <em>script</em> <em>dependencies</em></pre> + <ul> + <li> + <code><em>type</em></code> can only be one of <code>log | srv</code>. + </li> + <li> + <code><em>dependencies</em></code> can only be one of <code>"dependency1 dependency2 ..." | none</code>. + </li> + <li> + longrun-make creates the directory <code><em>workingdir</em>/<em>name</em>-<em>type</em></code>. + </li> + <li> + It creates the file <code><em>workingdir</em>/<em>name</em>-<em>type</em>/type</code> + (literal "<code>type</code>") and writes the line <code>longrun</code> to it. + </li> + <li> + It creates the file <code><em>workingdir</em>/<em>name</em>-<em>type</em>/notification-fd</code> + and writes the line <code>3</code> to it. + </li> + <li> + It creates the file <code><em>workingdir</em>/<em>name</em>-<em>type</em>/run</code> + and writes <code><em>script</em></code> to it. + </li> + <li> + If <code><em>type</em></code> is <code>log</code> <em>and</em> the file + <code><em>workingdir</em>/<em>name</em>-<em>type</em>/consumer-for</code> + does <em>not</em> contain the string <code><em>name</em></code>: + <ul> + <li> + longrun-make aquires a lock on the file + <code><em>workingdir</em>/<em>name</em>-<em>type</em>/consumer-for</code> + using + <a href="https://skarnet.org/software/s6/s6-setlock.html">s6-setlock</a>. + </li> + <li> + It appends the string <code><em>name</em>-srv</code> to the file + <code><em>workingdir</em>/<em>name</em>-<em>type</em>/consumer-for</code> + creating it if it does not exist. + </li> + <li> + It creates a file <code><em>workingdir</em>/<em>name</em>-<em>type</em>/pipeline-name</code>, + truncating it if it does exist and adds the string <code><em>name</em></code>. + </li> + </ul> + </li> + <li> + If <code><em>type</em></code> is <code>srv</code>: + <ul> + <li> + The file + <code><em>workingdir</em>/<em>name</em>-<em>type</em>/producer-for</code> + is created, truncated and the string <code><em>name</em>-log</code> is added. + </li> + </ul> + </li> + <li> + If <code><em>dependencies</em></code> is not <code>none</code>: + <ul> + <li> + The directory + <code><em>workingdir</em>/<em>name</em>-<em>type</em>/dependencies.d</code> + is created. + </li> + <li> + For each word <code>"dependency1 dependency2 ..."</code> in + <code><em>dependencies</em></code> separated by spaces, + a file + <code><em>workingdir</em>/<em>name</em>-<em>type</em>/dependencies.d/<em>dependency</em></code> + is created. + </li> + </ul> + </li> + </ul> + <p> + longrun-make is, by means of locking and checking for duplicates, + specifically designed to allow parallel creation of logging + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a>. + </p> + <h2>Exit codes</h2> + <ul> + <li> + 0: success + </li> + <li> + Since longrun-make is an + <a href="https://skarnet.org/software/execline/">execline</a> + script, it exits with an approximation + of employed program that failed. + </li> + <li> + longrun-make 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 otions to longrun-make. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/oneshot-make.html b/doc/bin/oneshot-make.html new file mode 100644 index 0000000..1b285c6 --- /dev/null +++ b/doc/bin/oneshot-make.html @@ -0,0 +1,101 @@ +<!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>oneshot-make</title> + <meta name="Description" content="Helper script to generate s6-rc oneshot source directories from a commandline." /> + <meta name="Keywords" content="goetia s6-rc oneshot source directory" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 oneshot-make program</h1> + <p> + oneshot-make contains boilerplate code + required to create the + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directory</a> + of a oneshot service + based on strings. + </p> + <h2>Interface</h2> + <pre> oneshot-make <em>workingdir</em> <em>name</em> <em>upscript</em> <em>downscript</em> <em>dependencies</em></pre> + <ul> + <li> + <code><em>dependencies</em></code> can only be one of <code>"dependency1 dependency2 ..." | none</code>. + </li> + <li> + oneshot-make creates the directory <code><em>workingdir</em>/<em>name</em></code> + </li> + <li> + it creates the file <code><em>workingdir</em>/<em>name</em>/type</code> + and writes the line <code>oneshot</code> to it. + </li> + <li> + it creates the file <code><em>workingdir</em>/<em>name</em>/up</code> + and writes <code><em>upscript</em></code> to it. + </li> + <li> + it creates the file <code><em>workingdir</em>/<em>name</em>/down</code> + and writes <code><em>downscript</em></code> to it. + </li> + <li> + If <code><em>dependencies</em></code> is not <code>none</code>: + <ul> + <li> + The directory + <code><em>workingdir</em>/<em>name</em>/dependencies.d</code> + is created. + </li> + <li> + For each word <code>"dependency1 dependency2 ..."</code> in + <code><em>dependencies</em></code> separated by spaces, + a file + <code><em>workingdir</em>/<em>name</em>/dependencies.d/<em>dependency</em></code> + is created. + </li> + </ul> + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 0: success + </li> + <li> + Since oneshot-make is an + <a href="https://skarnet.org/software/execline/">execline</a> + script, it exits with an approximation + of employed program that failed. + </li> + <li> + oneshot-make 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 otions to oneshot-make. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/prepare-svscan.html b/doc/bin/prepare-svscan.html new file mode 100644 index 0000000..6b82bd5 --- /dev/null +++ b/doc/bin/prepare-svscan.html @@ -0,0 +1,120 @@ +<!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>prepare-svscan</title> + <meta name="Description" content="Helper script to initialize a supervision tree." /> + <meta name="Keywords" content="goetia s6 s6-rc supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 prepare-svscan program</h1> + <p> + prepare-svscan does generic preparation of the + <a href="//0x53.net/software/goetia/supervisiontree.html">supervision tree</a>. + It is also used in system-init and + <a href="./user-init.html">user-init</a>. + </p> + <h2>Interface</h2> + <pre> prepare-svscan <em>workingdir</em> <em>rundir</em> <em>bundle</em> <em>prog...</em></pre> + <ul> + <li> + prepare-svscan sets its standard input to <code>/dev/null</code>. + </li> + <li> + It sets the umask to <code>0022</code>. + </li> + <li> + It creates the directory <code><em>rundir</em></code>. + </li> + <li> + It copies all contents of <code><em>workingdir</em>/run-image/.</code> + to <code><em>rundir</em>/</code>. + </li> + <li> + It changes its standard output to <code><em>rundir</em>/service/s6-svscan-log/fifo</code>. + </li> + <li> + prepare-svscan then forks a background process that: + <ul> + <li> + waits for a reading end at <code><em>rundir</em>/service/s6-svscan-log/fifo</code>. + </li> + <li> + Once the above is given, if <code><em>rundir</em>/s6-rc</code> does <em>not</em> exist, + </li> + <li> + it initiates <a href="https://skarnet.org/software/s6-rc/">s6-rc</a> on + <code><em>rundir</em>/service</code> using + <a href="https://skarnet.org/software/s6-rc/s6-rc-init.html">s6-rc-init</a> + and starts the bundle <code><em>bundle</em></code> using s6-rc. + </li> + </ul> + </li> + <li> + It copies stderr to stdout. + </li> + <li> + If available, the directory <code><em>workingdir</em>/env</code> is sourced using + <a href="https://skarnet.org/software/s6/s6-envdir.html">s6-env</a>. + </li> + <li> + prepare-svscan executest into <code><em>prog...</em></code>, + which is usually directly or indirectly + <a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>. + </li> + </ul> + <p> + Once s6-svscan is launched it will start an + <a href="https://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a> + process on <code><em>rundir</em>/service/s6-svscan-log</code> which starts + <a href="https://skarnet.org/software/s6/s6-log.html">s6-log</a> reading + from <code><em>rundir</em>/service/s6-svscan-log/fifo</code>. + This in turn triggers the forked background process to continue with its second step. + </p> + <h2>Exit codes</h2> + <ul> + <li> + prepare-svscan 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 prepare-svscan is an + <a href="https://skarnet.org/software/execline/">execline</a> + script, it exits with an approximation + of employed program that failed. + </li> + <li> + prepare-svscan 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 otions to prepare-svscan. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/system-db.html b/doc/bin/system-db.html new file mode 100644 index 0000000..056f5b7 --- /dev/null +++ b/doc/bin/system-db.html @@ -0,0 +1,67 @@ +<!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-db</title> + <meta name="Description" content="Script to compile the system supervision tree database." /> + <meta name="Keywords" content="goetia compile-db s6-rc s6-rc-compile system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-db program</h1> + <p> + system-db compiles the + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a> + of the + <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a> + into the <em>compiled</em> format. + This format can then be used by init and + <a href="./system-rc.html">system-rc</a> + to set up and control a + <a href="//0x53.net/software/goetia/supervisiontree.html#system">system supervision tree</a>. + </p> + <p> + system-db is a wrapper around the more general + <a href="./compile-db.html">compile-db</a> + making it target the system supervision tree. + </p> + <h2>Interface</h2> + <pre> system-db</pre> + <ul> + <li> + system-db takes no arguments. + </li> + <li> + It runs compile-db supplementing it with the + <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a> + and + <a href="//0x53.net/software/goetia/rundir.html#system">system runtime directory</a>. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + Since system-db is a wrapper around compile-db, it + <a href="./compile-db.html">behaves exactly like it</a>. + </li> + </ul> + <h2>Options</h2> + <ul> + <li> + There are no options to system-db. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/system-ml.html b/doc/bin/system-ml.html new file mode 100644 index 0000000..bc487a9 --- /dev/null +++ b/doc/bin/system-ml.html @@ -0,0 +1,96 @@ +<!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-ml</title> + <meta name="Description" content="Script to autogenerate loggers for the system supervision tree." /> + <meta name="Keywords" content="goetia longrun-make s6-rc logger log system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-ml program</h1> + <p> + system-ml automatically creates logging service + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a> + for longrun services in the + <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a>. + To create the logging service source directories, + system-ml uses + <a href="./longrun-make.html">longrun-make</a> internally. + </p> + <h2>Interface</h2> + <pre> system-ml</pre> + <ul> + <li> + system-ml takes no arguments. + </li> + <li> + It deletes the <code>src/generated-logger</code> subdirectory of the + <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a>. + </li> + <li> + It scans the <code>src</code> subdirecotry of the + <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a> + for longrun services. + </li> + <li> + It checks for each longrun it detects, + whether its source directory contains a file <code>no-ml</code>. + If this file exits, this longrun is skipped in the subsequent logger generation. + </li> + <li> + It generates a logging service source directory at + <code>src/generated-logger/<var>@longrun@</var>-log</code> + in the <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a>. + It does so in parallel for each longrun <code><var>@longrun@</var>-srv</code> it found. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + Since system-ml 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-ml 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-ml. + </li> + </ul> + <h2>Notes</h2> + <p> + The logger services created by this script + will drop privileges to + <code><var>@loguser@</var></code>, + which must exist at runtime. + (see <a href="//0x53.net/software/goetia/logdir.html">log directory</a>). + </p> + </body> +</html> diff --git a/doc/bin/system-rc.html b/doc/bin/system-rc.html new file mode 100644 index 0000000..f6e48db --- /dev/null +++ b/doc/bin/system-rc.html @@ -0,0 +1,63 @@ +<!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-rc</title> + <meta name="Description" content="Convenience wrapper around s6-rc to control the system supervision tree." /> + <meta name="Keywords" content="goetia s6-rc system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-rc program</h1> + <p> + system-rc is a thin convenience wrapper around + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + doing nothing more then pointing it to the right livedir. + </p> + <p> + Read the page of + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + to understand what this utility does. + </p> + <h2>Interface</h2> + <pre> system-rc ... <a href="https://skarnet.org/software/s6-rc/s6-rc.html">see s6-rc</a> ...</pre> + <ul> + <li> + It runs + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + with the appropriate livedir option. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + Since system-rc is a thin wrapper around + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + it behaves almost exactly like it. + </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> + system-rc takes exactly the same options as + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a>. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/system-run.html b/doc/bin/system-run.html new file mode 100644 index 0000000..465cee4 --- /dev/null +++ b/doc/bin/system-run.html @@ -0,0 +1,67 @@ +<!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-run</title> + <meta name="Description" content="Run little scripts from the system supervision tree, providing reliability." /> + <meta name="Keywords" content="goetia s6 system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-run program</h1> + <p> + system-run allows + to hand over the execution of commands to the + <a href="//0x53.net/software/goetia/supervisiontree.html#system">system supervision tree</a>. + </p> + <h2>Interface</h2> + <pre> system-run <em>prog...</em></pre> + <ul> + <li> + Internally, system-run invokes + <a href="https://skarnet.org/software/s6/s6-sudo.html">s6-sudo</a> + to connect to an + <a href="https://skarnet.org/software/s6/s6-sudod.html">s6-sudod</a> + instance provided by the system + <a href="//0x53.net/software/goetia/service/system/goetia-runner.html">goetia-runner</a>. + </li> + <li> + <code><em>prog...</em></code> is then transferred + to and executed by goetia-runner. + </li> + <li> + See + <a href="https://skarnet.org/software/s6/s6-sudo.html">s6-sudo</a> + and + <a href="https://skarnet.org/software/s6/s6-sudod.html">s6-sudod</a> + for configuration options and detailed information. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + system-run behaves exactly as + <a href="https://skarnet.org/software/s6/s6-sudo.html">s6-sudo</a>. + </li> + </ul> + <h2>Options</h2> + <ul> + <li> + system-run takes the exact same options as + <a href="https://skarnet.org/software/s6/s6-sudoc.html">s6-sudoc</a>. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/system-shutdown-daemon.html b/doc/bin/system-shutdown-daemon.html new file mode 100644 index 0000000..82493b6 --- /dev/null +++ b/doc/bin/system-shutdown-daemon.html @@ -0,0 +1,123 @@ +<!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-daemon</title> + <meta name="Description" content="The kernel indepentent part of the goetia shutdown procedure." /> + <meta name="Keywords" content="goetia s6 s6-rc system supervision tree shutdown" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-daemon program</h1> + <p> + system-shutdown-daemon contains the Kernel independent + part of the shutdown sequence. + It is invoked by the Kernel specifict goetia-shutdown service, + e.g. + <a href="//0x53.net/software/goetia/goetia-linux-init/service/system/goetia-shutdown.html">goetia-shutdown service for Linux</a> + or + <a href="//0x53.net/software/goetia/goetia-freebsd-init/service/system/goetia-shutdown.html">goetia-shutdown service for FreeBSD</a>. + 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. + <a href="//0x53.net/software/goetia/goetia-linux">goetia-linux</a> + or + <a href="//0x53.net/software/goetia/goetia-freebsd">goetia-freebsd</a>. + </p> + <h2>Interface</h2> + <pre> system-shutdown-daemon</pre> + <ul> + <li> + system-shutdown-daemon takes no arguments. + </li> + <li> + It tries to execute <code>./stage3b</code>, + which is by default not executable. + If it can not execute <code>./stage3b</code>, + and <em>only</em> in this case, + it continues with the following. + </li> + <li> + All services managed by + <a href="https://skarnet.org/software/s6-rc/">s6-rc</a> + are stopped. + This means, all services defined in + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a> + at the <code>src</code> subdirectory of the + <a href="//0x53.net/software/goetia/confdir.html#system">system configuration directory</a>. + </li> + <li> + Next, all leftover services <em>except</em> + s6-svscan-log, goetia-shutdown and goetia-rescue, are stopped. + </li> + <li> + The file <code>stage3b</code>, expected to exist in the current working directory + is made executable. + This file is part of the Kernel secific service directories. + (see e.g. <a href="//0x53.net/software/goetia/goetia-linux-init/service/system/goetia-shutdown.html">goetia-shutdown</a>) + </li> + <li> + all uncaught system logs are copied from the + <code>log/uncaught-logs</code> + subdirectory of the + <a href="//0x53.net/software/goetia/rundir.html#system">system runtime directory</a>. + to the + <code>uncaught-logs</code> + subdirectory of the + <a href="//0x53.net/software/goetia/logdir.html#">system log directory</a>. + </li> + <li> + SIGTERM is sent to all processes but PID 1. + </li> + <li> + This also stops the system-shutdown-daemon process. + It is automatically restarted by the system supervision tree, + but this time, the file <code>./stage3b</code> is executable + and executed instead of what is described above. + What happens in <code>./stage3b</code> is Kernel specific, + and documented on + <a href="//0x53.net/software/goetia/goetia-linux-init/service/goetia-shutdown.html">goetia-shutdown service for Linux</a>, + <a href="//0x53.net/software/goetia/goetia-freebsd-init/service/goetia-shutdown.html">goetia-shutdown service for FreeBSD</a>, + etc. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + Since system-shutdown-daemon 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-daemon 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-shutdown-daemon. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/user-db.html b/doc/bin/user-db.html new file mode 100644 index 0000000..26ef310 --- /dev/null +++ b/doc/bin/user-db.html @@ -0,0 +1,82 @@ +<!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>user-db</title> + <meta name="Description" content="Script to compile the user supervision tree database." /> + <meta name="Keywords" content="goetia compile-db s6-rc user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-db program</h1> + <p> + user-db compiles the + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a> + of the + <a href="//0x53.net/software/goetia/confdir.html#user">user configuration directory</a> + into the <em>compiled</em> format. + This format can then be used by init and + <a href="./user-rc.html">user-rc</a> + to set up and control a + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a>. + </p> + <p> + user-db is a wrapper around the more general + <a href="./compile-db.html">compile-db</a> + making it target the user supervision tree. + </p> + <h2>Interface</h2> + <pre> user-db</pre> + <ul> + <li> + user-db takes no arguments. + </li> + <li> + It reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USERTREE</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>HOME</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It runs compile-db supplementing it the correct + <a href="//0x53.net/software/goetia/confdir.html#user">user configuration directory</a> + and + <a href="//0x53.net/software/goetia/rundir.html#user">user runtime directory</a>. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 100 if a critical environment variable is missing. + </li> + <li> + Since user-db is a wrapper around compile-db, it + <a href="./compile-db.html">behaves exactly like it</a>. + </li> + </ul> + <h2>Options</h2> + <ul> + <li> + There are no options to user-db. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/user-init.html b/doc/bin/user-init.html new file mode 100644 index 0000000..c96c3ae --- /dev/null +++ b/doc/bin/user-init.html @@ -0,0 +1,128 @@ +<!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>user-init</title> + <meta name="Description" content="Script to initialize a user supervision tree." /> + <meta name="Keywords" content="goetia prepare-svscan s6 s6-rc user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-init program</h1> + <p> + user-init starts a user supervision tree for + the user defined in the <code>USER</code> + environment variable. + </p> + <h2>Interface</h2> + <pre> user-init</pre> + <ul> + <li> + user-init takes no arguments. + </li> + <li> + It reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USERTREE</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>BUNDLE</code> environment variable, + defaulting to <code>default</code> if empty. + </li> + <li> + It reads the <code>PATH</code> environment variable, + defaulting to + <code>/command:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/libexec:/usr/local/libexec</code> + if empty. + </li> + <li> + if <code>${USER}/${USERTREE}</code> subdirectory of the + <a href="//0x53.net/software/goetia/rundir.html">runtime directory</a> + olready existis, it exits 100. + </li> + <li> + It sets the <code>HOME</code> environment variable based on the result of + <a href="https://skarnet.org/software/execline/homeof.html">homeof</a>. + </li> + <li> + It prepends <code>${HOME}/.local/bin:</code> to the <code>PATH</code> + environment variable. + </li> + <li> + It sets the <code>UID</code>, <code>GID</code> and <code>GIDLIST</code> + environment variables using + <a href="https://skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a>. + </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>${USER}/${USERTREE}/service</code> + subdirectory of the + <a href="//0x53.net/software/goetia/rundir.html#user">user runtime directory</a>. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 100 if a critical environment variable is missing. + </li> + <li> + user-init usually executes into + <a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> + which exits according to its documentation. + </li> + <li> + Since user-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> + user-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 documentation. + </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 otions to user-init. + </li> + </ul> + <h2>Notes</h2> + <p> + More information about user supervision trees + themselves can be found on the + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a> + page. + </p> + </body> +</html> 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 @@ +<!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>user-ml</title> + <meta name="Description" content="Script to autogenerate loggers for the user supervision tree." /> + <meta name="Description" content="A policy for s6 and s6-rc" /> + <meta name="Keywords" content="goetia longrun-make s6-rc logger log user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-ml program</h1> + <p> + user-ml automatically creates logging service + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a> + for longrun services of the + <a href="//0x53.net/software/goetia/confdir.html#user">user configuration directory</a>. + To create the logging service source directories, + user-ml uses + <a href="./longrun-make.html">longrun-make</a> internally. + </p> + <h2>Interface</h2> + <pre> user-ml</pre> + <ul> + <li> + user-ml takes no arguments. + </li> + <li> + It reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USERTREE</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>HOME</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It deletes the <code>${USERTREE}/src/generated-logger</code> subdirectory + of the <a href="//0x53.net/software/goetia/confdir.html#user">user configuration subdirectory</a>. + </li> + <li> + It scans the <code>${USERTREE}/src</code> subdirectory + of the <a href="//0x53.net/software/goetia/confdir.html#user">user configuration subdirectory</a> + for longrun services. + </li> + <li> + It checks for each longrun it detects, + whether its source directory contains a file <code>no-ml</code>. + If this file exits, this longrun is skipped in the subsequent logger generation. + </li> + <li> + It generates a logging service source directory + <code>${USERTREE}/src/generated-logger/<var>@longrun@</var>-log</code> + in parallel for each longrun <code><var>@longrun@</var>-srv</code> it found + in the <a href="//0x53.net/software/goetia/confdir.html#user">user configuration subdirectory</a>. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 100 if a critical environment variable is missing. + </li> + <li> + Since user-ml is an + <a href="https://skarnet.org/software/execline/">execline</a> + script, it exits with an approximation + of employed program that failed. + </li> + <li> + user-ml 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 user-ml. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/user-rc.html b/doc/bin/user-rc.html new file mode 100644 index 0000000..3bad0c5 --- /dev/null +++ b/doc/bin/user-rc.html @@ -0,0 +1,74 @@ +<!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>user-rc</title> + <meta name="Description" content="Convenience wrapper around s6-rc to control the user supervision tree." /> + <meta name="Keywords" content="goetia s6-rc user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-rc program</h1> + <p> + The user-rc program is a thin convenience wrapper around + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + doing nothing more then pointing it to the right livedir. + </p> + <p> + Read the page of + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + to understand what this utility does. + </p> + <h2>Interface</h2> + <pre> user-rc ... <a href="https://skarnet.org/software/s6-rc/s6-rc.html">see s6-rc</a> ...</pre> + <ul> + <li> + user-rc reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USERTREE</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It runs + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + with the appropriate livedir option. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 100 if a critical environment variable is missing. + </li> + <li> + Since user-rc is a thin wrapper around + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a> + it behaves almost exactly like it. + </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> + user-rc takes exactly the same options as + <a href="https://skarnet.org/software/s6-rc/s6-rc.html">s6-rc</a>. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/user-run.html b/doc/bin/user-run.html new file mode 100644 index 0000000..924849c --- /dev/null +++ b/doc/bin/user-run.html @@ -0,0 +1,78 @@ +<!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>user-run</title> + <meta name="Description" content="Run little scripts from the user supervision tree, providing reliability." /> + <meta name="Keywords" content="goetia s6 user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-run program</h1> + <p> + The user-run program allows + to hand over the execution of commands to the + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a>. + </p> + <h2>Interface</h2> + <pre> user-run <em>prog...</em></pre> + <ul> + <li> + user-rc reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USERTREE</code> environment variable, + if it is empty it exits 100. + </li> + <li> + Internally, user-run invokes + <a href="https://skarnet.org/software/s6/s6-sudo.html">s6-sudo</a> + to connect to an + <a href="https://skarnet.org/software/s6/s6-sudod.html">s6-sudod</a> + instance provided by the user + <a href="//0x53.net/software/goetia/service/user/goetia-runner.html">goetia-runner</a>. + </li> + <li> + <code><em>prog...</em></code> is then transferred + to and executed by goetia-runner. + </li> + <li> + See + <a href="https://skarnet.org/software/s6/s6-sudo.html">s6-sudo</a> + and + <a href="https://skarnet.org/software/s6/s6-sudod.html">s6-sudod</a> + for configuration options and detailed information. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 100 if a critical environment variable is missing. + </li> + <li> + user-run behaves exactly as + <a href="https://skarnet.org/software/s6/s6-sudo.html">s6-sudo</a>. + </li> + </ul> + <h2>Options</h2> + <ul> + <li> + user-run takes the exact same options as + <a href="https://skarnet.org/software/s6/s6-sudoc.html">s6-sudoc</a>. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/user-shutdown.html b/doc/bin/user-shutdown.html new file mode 100644 index 0000000..6a52db8 --- /dev/null +++ b/doc/bin/user-shutdown.html @@ -0,0 +1,68 @@ +<!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>user-shutdown</title> + <meta name="Description" content="Script to tear down a user supervision tree." /> + <meta name="Keywords" content="goetia s6 s6-rc shutdown user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-shutdown program</h1> + <p> + The user-shutdown program is used to tear down + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision trees</a>. + </p> + <h2>Interface</h2> + <pre> user-shutdown</pre> + <ul> + <li> + user-shutdown takes no arguments. + </li> + <li> + It starts the user + <a href="//0x53.net/software/goetia/goetia-base/service/user/goetia-shutdown.html">goetia-shutdown</a> + service. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + Since user-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> + user-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>Options</h2> + <ul> + <li> + There are no options to user-shutdown. + </li> + </ul> + </body> +</html> diff --git a/doc/bin/user-tmpfs.html b/doc/bin/user-tmpfs.html new file mode 100644 index 0000000..3c22c57 --- /dev/null +++ b/doc/bin/user-tmpfs.html @@ -0,0 +1,104 @@ +<!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>user-tmpfs</title> + <meta name="Description" content="Script to prepare a user owned tmpfs to house a user supervision tree." /> + <meta name="Keywords" content="goetia tmpfs user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user-tmpfs program</h1> + <p> + The user-tmpfs program prepares + a user owned tmpfs for + the user defined in the <code>USER</code> + environment variable. + The user owned tmpfs is created at + <code><var>@tmpfsdir@</var>/<var>@usrrundir@</var>/<var>${USER}</var></code>. + </p> + <h2>Interface</h2> + <pre> user-tmpfs</pre> + <ul> + <li> + user-tmpfs takes no arguments. + </li> + <li> + It reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USER_TMPFSDIR_SIZE</code> environment variable, + defaulting to <code>64m</code> if undefined. + </li> + <li> + It creates the directory + <code><var>@tmpfsdir@</var>/<var>@usrrundir@</var>/<var>${USER}</var></code>. + </li> + <li> + It mounts a tmpfs + of size <code>USER_TMPFSDIR_SIZE</code> + with its root owned bi <code>USER</code> + and mode <code>0755</code> + at <code><var>@tmpfsdir@</var>/<var>@usrrundir@</var>/<var>${USER}</var></code>. + </li> + </ul> + <h2>Exit codes</h2> + <ul> + <li> + 100 if a critical environment variable is missing. + </li> + <li> + Since user-tmpfs is an + <a href="https://skarnet.org/software/execline/">execline</a> + script, it exits with an approximation + of employed program that failed. + </li> + <li> + user-tmpfs 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 documentation. + </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 otions to user-tmpfs. + </li> + </ul> + <h2>Notes</h2> + <p> + user-tmpfs is intended to be used in a boot time + <a href="//0x53.net/software/goetia/supervisiontree.html#system">system supervision tree</a> + oneshot service to prepare the + <a href="//0x53.net/software/goetia/rundir.html#user">user runtime directory</a> + of a user. + For each user who should have a user runtime directory, + there should be a distinct oneshot running user-tmpfs. + </p> + <p> + Alternatively, user-tmpfs could be run by a login manager + after login, but befor initiating the first + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a>. + </p> + </body> +</html> diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..fe07e2b --- /dev/null +++ b/doc/index.html @@ -0,0 +1,413 @@ +<!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-base</title> + <meta name="Description" content="goetia-base contains kernel independent basic building blocks of goetia." /> + <meta name="Keywords" content="goetia base" /> + </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-base</h1> + <h2>What is it?</h2> + <p> + goetia-base contains scripts to manage + <a href="//0x53.net/software/goetia/supervisiontree.html#system">system</a>. + and + <a href="//0x53.net/software/goetia/supervisiontree.html#user">system supervision trees</a>. + Additionally, it contains kernel independant + <a href="https://skarnet.org/software/s6/servicedir.html">service directories</a> + and + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directories</a> + for the system and user supervision tree. + </p> + <hr> + <h2>Installation</h2> + <h3>Requirements</h3> + <ul> + <li> + A set of POSIX tools as described in the general + <a href="//0x53.net/software/requirements.html">requirements</a> + </li> + <li> + A POSIX-compliant implementation of make, or GNU make + </li> + <li> + Additional per-service dependencies, + e.g. the daemon itself the service corresponds to, + are listed on the respective page of the service. + </li> + </ul> + <h3>Licensing</h3> + <p> + goetia-base 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-base is + <a href="./goetia-base-0.0.1.0.tar.gz">0.0.1.0</a>. + You can access its checksum + <a href="./goetia-base-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-base">goetia-base git repository</a>: + <pre>git clone git://git.0x53.net/goetia-base</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. + Most of these commands are thin wrappers + around tools from + <a href="https://skarnet.org/software/s6/">s6</a> + and + <a href="https://skarnet.org/software/s6-rc/">s6-rc</a>. + They do not do much more than supplement the former + with the right paths and default options. + The utility scripts, however, + contain their own logic that is used + in some of the other scripts. + </p> + <h4>Managing system supervision trees</h4> + <ul> + <li> + <a href="./bin/system-db.html">system-db</a> + </li> + <li> + <a href="./bin/system-ml.html">system-ml</a> + </li> + <li> + <a href="./bin/system-rc.html">system-rc</a> + </li> + <li> + <a href="./bin/system-run.html">system-run</a> + </li> + </ul> + <h4>Managing user supervision trees</h4> + <ul> + <li> + <a href="./bin/user-db.html">user-db</a> + </li> + <li> + <a href="./bin/user-ml.html">user-ml</a> + </li> + <li> + <a href="./bin/user-rc.html">user-rc</a> + </li> + <li> + <a href="./bin/user-run.html">user-run</a> + </li> + <li> + <a href="./bin/user-init.html">user-init</a> + </li> + <li> + <a href="./bin/user-shutdown.html">user-shutdown</a> + </li> + <li> + <a href="./bin/user-tmpfs.html">user-tmpfs</a> + </li> + </ul> + <h4>Utility scripts</h4> + <ul> + <li> + <a href="./bin/compile-db.html">compile-db</a> + </li> + <li> + <a href="./bin/longrun-make.html">longrun-make</a> + </li> + <li> + <a href="./bin/oneshot-make.html">oneshot-make</a> + </li> + <li> + <a href="./bin/prepare-svscan.html">prepare-svscan</a> + </li> + <li> + <a href="./bin/system-shutdown-daemon.html">system-shutdown-daemon</a> + </li> + </ul> + </section> + <section id="service"> + <h3>Service directories</h3> + <p> + Service directories for early and basic services, + used without + <a href="https://skarnet.org/software/s6-rc/">s6-rc</a>. + Service directories in this package are used independent + of the kernel in use. + </p> + <h4>System service directories</h4> + <ul> + <li> + <a href="./service/system/goetia-runner.html">goetia-runner</a> + </li> + <li> + <a href="./service/system/s6-svscan-log.html">s6-svscan-log</a> + </li> + <li> + <a href="./service/system/s6-svscan-log-console.html">s6-svscan-log-console</a> + </li> + </ul> + <h4>User service directories</h4> + <ul> + <li> + <a href="./service/user/.s6-svscan.html">.s6-svscan</a> + </li> + <li> + <a href="./service/user/goetia-runner.html">goetia-runner</a> + </li> + <li> + <a href="./service/user/goetia-shutdown.html">goetia-shutdown</a> + </li> + <li> + <a href="./service/user/s6-svscan-log.html">s6-svscan-log</a> + </li> + </ul> + </section> + <section id="source"> + <h3>Source directories</h3> + <p> + Following is a list of included + source directories. + Note that some daemons are so modular + and configurable, it would be nonsense + to provide a "stock" source directory. + How to set those up is explained in + an according + <a href="//0x53.net/software/goetia/tutorials/">tutorial page</a>. + </p> + <h4>System source directories</h4> + <h5>bundle</h5> + <p> + Some services can be provided by multiple different implementations. + Those are abstracted by bundles, + which can be filled with the desired implementation. + For the + <a href="//0x53.net/software/goetia/supervisiontree.html#system">system supervision tree</a> + the bundles used and provided by default in goetia are: + </p> + <ul> + <li> + <a href="./source/system/bundles/default.html">default</a> + </li> + <li> + <a href="./source/system/bundles/mount.html">mount</a> + </li> + <li> + <a href="./source/system/bundles/udev.html">udev</a> + </li> + <li> + <a href="./source/system/bundles/seat-manager.html">seat-manager</a> + </li> + <li> + <a href="./source/system/bundles/system-bus.html">system-bus</a> + </li> + <li> + <a href="./source/system/bundles/networking.html">networking</a> + </li> + <li> + <a href="./source/system/bundles/firewall.html">firewall</a> + </li> + </ul> + <h5>cron</h5> + <ul> + <li> + dcron + </li> + </ul> + <h5>db</h5> + <ul> + <li> + mariadb + </li> + <li> + mysqld + </li> + </ul> + <h5>net</h5> + <ul> + <li> + dhcpcd + </li> + <li> + wpa_supplicant + </li> + </ul> + <h5>ntp</h5> + <ul> + <li> + chronyd + </li> + </ul> + <h5>web</h5> + <ul> + <li> + gate + </li> + <li> + nginx + </li> + <li> + radicale + </li> + </ul> + <h5>other</h5> + <ul> + <li> + cupsd + </li> + <li> + dbus-daemon + </li> + <li> + <a href="./source/system/admin/seatd.html">seatd</a> + </li> + <li> + sshd + </li> + </ul> + <h4>User source directories</h4> + <h5>bundle</h5> + <p> + Some services can be provided by multiple different implementations. + Those are abstracted by bundles, + which can be filled with the desired implementation. + For the + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a> + the bundles used and provided by default in goetia are: + </p> + <ul> + <li> + <a href="./source/user/bundle/default.html">default</a> + </li> + <li> + <a href="./source/user/bundle/audio.html">audio</a> + </li> + <li> + <a href="./source/user/bundle/compositor.html">compositor</a> + </li> + <li> + <a href="./source/user/bundle/session-bus.html">session-bus</a> + </li> + </ul> + <h5>audio-daemon</h5> + <ul> + <li> + pipewire + </li> + <li> + pipewire-pulse + </li> + <li> + wireplumber + </li> + </ul> + <h5>clipboard-manager</h5> + <ul> + <li> + wl-clip-persist + </li> + </ul> + <h5>compositor</h5> + <ul> + <li> + Hyprland + </li> + </ul> + <h5>desktop-widget</h5> + <ul> + <li> + waybar + </li> + <li> + yambar + </li> + </ul> + <h5>notification-daemon</h5> + <ul> + <li> + dunst + </li> + <li> + fnott + </li> + <li> + mako + </li> + <li> + swaync + </li> + </ul> + <h5>wallpaper-daemon</h5> + <ul> + <li> + hyprpaper + </li> + </ul> + <h5>xdg</h5> + <ul> + <li> + xdg-desktop-portal-hyprland + </li> + <li> + xdg-desktop-portal + </li> + <li> + xdg-document-portal + </li> + <li> + xdg-permission-store + </li> + <li> + <a href="./source/user/xdg/xdg-runtime-dir.html">xdg-runtime-dir</a> + </li> + </ul> + <h5>other</h5> + <ul> + <li> + at-spi-bus-launcher + </li> + <li> + at-spi2-registryd + </li> + <li> + <a href="./source/user/other/dbus-daemon.html">dbus-daemon</a> + </li> + <li> + dconf-service + </li> + <li> + foot + </li> + <li> + mpd + </li> + </ul> + </section> + </body> +</html> diff --git a/doc/service/system/goetia-runner.html b/doc/service/system/goetia-runner.html new file mode 100644 index 0000000..16abb52 --- /dev/null +++ b/doc/service/system/goetia-runner.html @@ -0,0 +1,44 @@ +<!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 goetia-runner</title> + <meta name="Description" content="System service for running little scripts from the system supervision tree." /> + <meta name="Keywords" content="goetia s6 service run system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 goetia-runner service</h1> + <p> + This service allows to hand of execution of a commandline to the + <a href="//0x53.net/software/goetia/supervisiontree.html#system">system supervision tree</a>. + It is the "server side" counterpart to + <a href="//0x53.net/software/goetia/goetia-base/bin/system-run.html">system-run</a>. + To achieve that, + goetia-runner makes use of + <a href="https://skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a> + and + <a href="https://skarnet.org/software/s6/s6-sudod.html">s6-sudod</a>. + </p> + <p> + An example would be the + <a href="//0x53.net/software/goetia/goetia-base/bin/system-rc.html">system-rc</a> + command invoking state transitions that might bring down + the user interface + (thus aborting mid-transition, + since the controlling terminal dies). + </p> + </body> +</html> diff --git a/doc/service/system/s6-svscan-log-console.html b/doc/service/system/s6-svscan-log-console.html new file mode 100644 index 0000000..eff7b14 --- /dev/null +++ b/doc/service/system/s6-svscan-log-console.html @@ -0,0 +1,50 @@ +<!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-log-console</title> + <meta name="Description" content="System service for catch-all-logging that duplicates logs to /dev/console." /> + <meta name="Keywords" content="goetia s6 log console system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-log-console service</h1> + <p> + This service writes all messages + that arrive at the + <a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> + process, as well as the stdout + of s6-svscan itself to a directory of the logdir format + (see <a href="https://skarnet.org/software/s6/s6-log.html">s6-log</a> + and + <a href="//0x53.net/software/goetia/logdir.html">logging directory</a>). + It writes them to the <code>system/logs/uncaught-logs</code> subdirectory + of the <a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>. + </p> + <p> + Additionally, all logs are duplicated to + <code>/dev/console</code>. + </p> + <section id="requirements"> + <h2>Requirements</h2> + <ul> + <li> + The file <code>/dev/console</code> + must be tha appropriate device node. + </li> + </ul> + </section> + </body> +</html> diff --git a/doc/service/system/s6-svscan-log.html b/doc/service/system/s6-svscan-log.html new file mode 100644 index 0000000..9d034dc --- /dev/null +++ b/doc/service/system/s6-svscan-log.html @@ -0,0 +1,37 @@ +<!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-log</title> + <meta name="Description" content="System service for catch-all-logging the system supervision tree." /> + <meta name="Keywords" content="goetia s6 log system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-log service</h1> + <p> + This service writes all messages + that arrive at the + <a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> + process, as well as the stdout + of s6-svscan itself to a directory of the logdir format + (see <a href="https://skarnet.org/software/s6/s6-log.html">s6-log</a> + and + <a href="//0x53.net/software/goetia/logdir.html">logging directory</a>). + It writes them to the <code>system/logs/uncaught-logs</code> subdirectory + of the <a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>. + </p> + </body> +</html> diff --git a/doc/service/user/.s6-svscan.html b/doc/service/user/.s6-svscan.html new file mode 100644 index 0000000..c861e00 --- /dev/null +++ b/doc/service/user/.s6-svscan.html @@ -0,0 +1,48 @@ +<!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>user .s6-svscan</title> + <meta name="Description" content="Configuration directory for s6-svscan for the user supervision tree" /> + <meta name="Keywords" content="goetia s6 s6-svscan user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user .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 + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a> + using: + </p> + <ul> + <li> + <a href="//0x53.net/software/goetia/goetia-base/bin/user-shutdown.html">user-shutdown</a> + upon receiving SIGTERM. + </li> + <li> + Deleting the <a href="//0x53.net/software/goetia/rundir.html">runtime directory</a> + of the user supervision tree in the <code>finish</code> script. + </li> + </ul> + <p> + The .s6-svscan directory is easily overlooked, + do not forget to symlink/copy it! + </p> + </body> +</html> diff --git a/doc/service/user/goetia-runner.html b/doc/service/user/goetia-runner.html new file mode 100644 index 0000000..1e6591c --- /dev/null +++ b/doc/service/user/goetia-runner.html @@ -0,0 +1,36 @@ +<!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>user goetia-runner</title> + <meta name="Description" content="User service for running little scripts from the user supervision tree." /> + <meta name="Keywords" content="goetia s6 service run user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user goetia-runner service</h1> + <p> + This service allows to hand of execution of a commandline to the + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a>. + It is the "server side" counterpart to + <a href="//0x53.net/software/goetia/goetia-base/bin/user-run.html">user-run</a>. + To achieve that, + goetia-runner makes user of + <a href="https://skarnet.org/software/s6/s6-ipcserver.html">s6-ipcserver</a> + and + <a href="https://skarnet.org/software/s6/s6-sudod.html">s6-sudod</a>. + </p> + </body> +</html> diff --git a/doc/service/user/goetia-shutdown.html b/doc/service/user/goetia-shutdown.html new file mode 100644 index 0000000..5652923 --- /dev/null +++ b/doc/service/user/goetia-shutdown.html @@ -0,0 +1,67 @@ +<!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>user goetia-shutdown</title> + <meta name="Description" content="Script to tear down a user supervision tree." /> + <meta name="Keywords" content="goetia s6 s6-rc shutdown user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user goetia-shutdown service</h1> + <p> + The user goetia-shutdown service is used to tear down + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision trees</a>. + Upon being started it: + <ul> + <li> + It reads the <code>USER</code> environment variable, + if it is empty it exits 100. + </li> + <li> + It reads the <code>USERTREE</code> environment variable, + If it is empty it exits 100. + </li> + <li> + It checks whether the subdirectory + <code>${USER}/${USERTREE}</code> + of the + <a href="//0x53.net/software/goetia/rundir.html#user">user runtime directory</a> + exists. If not, meaning no user supervision tree is running, it exits 0. + </li> + <li> + It makes all of its stdout and stderr go to the + <a href="//0x53.net/software/goetia/goetia-base/service/user/s6-svscan-log.html">s6-svscan-log</a> + of the user supervision tree. + </li> + <li> + It stops all services managed by + <a href="https://skarnet.org/software/s6-rc/">s6-rc</a>. + </li> + <li> + It sends SIGHUP to s6-svscan-log of the user supervision tree. + This is important, since s6-svscan will keep the fifo open, + waiting for s6-svscan-log to exit, which in turn waits for + EOF before exiting itself. + SIGHUP tells s6-svscan-log to immediatly exit. + </li> + <li> + It tells + <a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> + to stop all remaining services and exit. + </li> + </ul> + </body> +</html> diff --git a/doc/service/user/s6-svscan-log.html b/doc/service/user/s6-svscan-log.html new file mode 100644 index 0000000..f434517 --- /dev/null +++ b/doc/service/user/s6-svscan-log.html @@ -0,0 +1,39 @@ +<!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>user s6-svscan-log</title> + <meta name="Description" content="User service for catch-all-logging a user supervision tree." /> + <meta name="Keywords" content="goetia s6 log user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 user s6-svscan-log service</h1> + <p> + This service writes all messages + that arrive at the + <a href="https://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a> + process, as well as the stdout + of s6-svscan itself to a directory of the logdir format + (see <a href="https://skarnet.org/software/s6/s6-log.html">s6-log</a> + and + <a href="//0x53.net/software/goetia/logdir.html">logging directory</a>). + This is + <code>${XDG_STATE_HOME}/log/uncaught-logs</code>, + if <code>${XDG_STATE_HOME}</code> is unset it defaults to + <code>${HOME}/.local/state/log/uncaught-logs</code> + </p> + </body> +</html> diff --git a/doc/source/system/admin/seatd.html b/doc/source/system/admin/seatd.html new file mode 100644 index 0000000..6303835 --- /dev/null +++ b/doc/source/system/admin/seatd.html @@ -0,0 +1,42 @@ +<!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>seatd</title> + <meta name="Description" content="Seatd mediates access to hardware like a GPU or input devices to compositors." /> + <meta name="Keywords" content="goetia s6-rc seat seatd system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 seatd service</h1> + <p> + Seatd is a seat manager. + This means that it mediates access to + hardware like a GPU or input devices to the compositor. + </p> + <p> + This service makes the socket have + <code>seat</code> group permissions. + Thus the group <code>seat</code> must exist + and users intending to run a compositor need to + be part of that group. + </p> + <p> + The service does not change the socket location, + by default it usually resides at + <code>/run/seatd.sock</code>. + </p> + </body> +</html> diff --git a/doc/source/system/bundles/default.html b/doc/source/system/bundles/default.html new file mode 100644 index 0000000..80b58c0 --- /dev/null +++ b/doc/source/system/bundles/default.html @@ -0,0 +1,37 @@ +<!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>default system bundle</title> + <meta name="Description" content="System bundle that is by default started during boot." /> + <meta name="Keywords" content="goetia s6-rc bundle system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 default system bundle</h1> + <p> + This bundle is started on boot and everything that is + desired to be autostarted should be part of it. + Minimize the amount of services in this bundle. + <a href="https://skarnet.org/software/s6-rc">s6-rc</a> + will automatically start (and stop) all dependencies. + Add only what should be unconditionally there. + An example of this would be a service to mount a storage device + containing photos. No other service will probably depend on + this, since none needs the photos, but the user still needs + this to be mounted. + </p> + </body> +</html> diff --git a/doc/source/system/bundles/firewall.html b/doc/source/system/bundles/firewall.html new file mode 100644 index 0000000..ecfe00e --- /dev/null +++ b/doc/source/system/bundles/firewall.html @@ -0,0 +1,29 @@ +<!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>firewall system bundle</title> + <meta name="Description" content="System bundle depended upon by services that should be started after the firewall is configured." /> + <meta name="Keywords" content="goetia s6-rc bundle system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 firewall system bundle</h1> + <p> + Some services might require a frirewall to be ready + when started, those shall depend on this bundle. + </p> + </body> +</html> diff --git a/doc/source/system/bundles/mount.html b/doc/source/system/bundles/mount.html new file mode 100644 index 0000000..c295d49 --- /dev/null +++ b/doc/source/system/bundles/mount.html @@ -0,0 +1,48 @@ +<!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>mount system bundle</title> + <meta name="Description" content="System bundle that is by default depended upon by program that need to read/write from/to disk." /> + <meta name="Keywords" content="goetia s6-rc bundle system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 mount system bundle</h1> + <p> + This bundle is by default a declared dependency of many + services provided by goetia. + Most importantly, it is a dependency of all autogenerated + loggers. + It should thus contain the mount services for all drives + that are used for + <a href="//0x53.net/software/goetia/logdir.html">logging</a>. + </p> + <p> + In most cases, the <code>remount-root</code> + <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html#source">source directory</a> + should be added to this bundle. + This source directory is part of the kernel specific packages, + like + <a href="//0x53.net/software/goetia/goetia-linux/">goetia-linux</a>. + </p> + <h2>See also</h2> + <ul> + <li> + <a href="//0x53.net/software/goetia/tutorials/base/mount.html">Mount tutorial</a> + </li> + </ul> + </body> +</html> diff --git a/doc/source/system/bundles/networking.html b/doc/source/system/bundles/networking.html new file mode 100644 index 0000000..0e3e18b --- /dev/null +++ b/doc/source/system/bundles/networking.html @@ -0,0 +1,35 @@ +<!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>networking system bundle</title> + <meta name="Description" content="System bundle that is depended upon by services requiring the correct network configuration to be applied." /> + <meta name="Keywords" content="goetia s6-rc bundle system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 networking system bundle</h1> + <p> + Services requiring networking to be set up + will depend on this. + </p> + <h2>See also</h2> + <ul> + <li> + <a href="//0x53.net/software/goetia/tutorials/base/networking.html">Networking tutorial</a> + </li> + </ul> + </body> +</html> diff --git a/doc/source/system/bundles/seat-manager.html b/doc/source/system/bundles/seat-manager.html new file mode 100644 index 0000000..eab3d26 --- /dev/null +++ b/doc/source/system/bundles/seat-manager.html @@ -0,0 +1,31 @@ +<!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>seat-manager system bundle</title> + <meta name="Description" content="System bundle that is depended upon by services requiring a seat manager to be running." /> + <meta name="Keywords" content="goetia s6-rc bundle system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 seat-manager system bundle</h1> + <p> + Refer to the + <a href="//0x53.net/software/goetia/tutorials/ui/seatsession.html">seat and session management</a> + tutorial, to understand the purpose of seat managers. + This bundle abstracts over the choices one has here. + </p> + </body> +</html> diff --git a/doc/source/system/bundles/system-bus.html b/doc/source/system/bundles/system-bus.html new file mode 100644 index 0000000..4efd015 --- /dev/null +++ b/doc/source/system/bundles/system-bus.html @@ -0,0 +1,34 @@ +<!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-bus system bundle</title> + <meta name="Description" content="System bundle depended upon by services requiring a system bus to be up." /> + <meta name="Keywords" content="goetia s6-rc bundle bus system-bus dbus system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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-bus system bundle</h1> + <p> + Some software requires a system-bus + implementing - usually the dbus interface. + The only currently available implementation + of this interface is + <a href="https://www.freedesktop.org/wiki/Software/dbus/">dbus-daemon</a>. + The source directory is part of + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</a>. + </p> + </body> +</html> diff --git a/doc/source/system/bundles/udev.html b/doc/source/system/bundles/udev.html new file mode 100644 index 0000000..835f04b --- /dev/null +++ b/doc/source/system/bundles/udev.html @@ -0,0 +1,36 @@ +<!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>udev system bundle</title> + <meta name="Description" content="System bundle that is depended upon by services requiring the userspace device manager to be up." /> + <meta name="Keywords" content="goetia s6-rc bundle system supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 udev system bundle</h1> + <p> + Some software depends on userspace device management software + to setup device permissions, symlinks and more. + The corresponding services will depend on this bundle. + </p> + <h2>See also</h2> + <ul> + <li> + <a href="//0x53.net/software/goetia/tutorials/base/udev.html">Udev tutorial</a> + </li> + </ul> + </body> +</html> diff --git a/doc/source/user/bundle/audio.html b/doc/source/user/bundle/audio.html new file mode 100644 index 0000000..687926e --- /dev/null +++ b/doc/source/user/bundle/audio.html @@ -0,0 +1,31 @@ +<!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>audio user bundle</title> + <meta name="Description" content="User bundle depended upon by services that need an audio server to be up." /> + <meta name="Keywords" content="goetia s6-rc bundle user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 audio user bundle</h1> + <p> + This bundle abstracts over the different + autio daemon implementations, + so services requiring a running audion daemon + can depend on this. + </p> + </body> +</html> diff --git a/doc/source/user/bundle/compositor.html b/doc/source/user/bundle/compositor.html new file mode 100644 index 0000000..9d10e89 --- /dev/null +++ b/doc/source/user/bundle/compositor.html @@ -0,0 +1,33 @@ +<!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>compositor user bundle</title> + <meta name="Description" content="User bundle depended upon by services that need a wayland compositor to be up." /> + <meta name="Keywords" content="goetia s6-rc bundle user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 compositor user bundle</h1> + <p> + This bundle shall contain the service corresponding to the + main compositing program, e.g. the + <a href="https://wayland.freedesktop.org/">Wayland</a> + compositor or + <a href="https://www.x.org/releases/X11R7.7/doc/index.html">X11</a>. + instance. + </p> + </body> +</html> diff --git a/doc/source/user/bundle/default.html b/doc/source/user/bundle/default.html new file mode 100644 index 0000000..2192a15 --- /dev/null +++ b/doc/source/user/bundle/default.html @@ -0,0 +1,39 @@ +<!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>default user bundle</title> + <meta name="Description" content="User bundle started upon starting the user supervision tree." /> + <meta name="Keywords" content="goetia s6-rc bundle user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 default user bundle</h1> + <p> + This bundle is started when the + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a> + is started and everything that is + desired to be autostarted should be part of it. + Minimize the amount of services in this bundle. + <a href="https://skarnet.org/software/s6-rc">s6-rc</a> + will automatically start (and stop) all dependencies. + Add only what should be unconditionally there. + An example of this would be a service + starting a wallpaper daemon, no other service + will probably depend on this but the user + wants the wallpaper to be there. + </p> + </body> +</html> diff --git a/doc/source/user/bundle/session-bus.html b/doc/source/user/bundle/session-bus.html new file mode 100644 index 0000000..8984b80 --- /dev/null +++ b/doc/source/user/bundle/session-bus.html @@ -0,0 +1,34 @@ +<!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>session-bus user bundle</title> + <meta name="Description" content="User bundle that is depended upon by services that need a session-bus to be up." /> + <meta name="Keywords" content="goetia s6-rc bundle bus session-bus dbus user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 session-bus user bundle</h1> + <p> + Some software requires a session-bus + - usually implementing the dbus interface. + The only currently available implementation + of this interface is + <a href="https://www.freedesktop.org/wiki/Software/dbus/">dbus-daemon</a>. + The source directory is part of + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</a>. + </p> + </body> +</html> diff --git a/doc/source/user/other/dbus-daemon.html b/doc/source/user/other/dbus-daemon.html new file mode 100644 index 0000000..f5290c8 --- /dev/null +++ b/doc/source/user/other/dbus-daemon.html @@ -0,0 +1,44 @@ +<!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>dbus-daemon</title> + <meta name="Description" content="User longrun to start the dbus session-bus" /> + <meta name="Keywords" content="goetia s6-rc bundle bus session-bus dbus user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 dbus-daemon service</h1> + <p> + This service starts a session + <a href="https://gitlab.freedesktop.org/dbus/dbus">dbus-daemon</a>. + It is important to set the environment variable + <code>DBUS_SESSION_BUS_ADDRESS</code>, + so other services depending on dbus-daemon can find it. + </p> + <p> + The <code>DBUS_SESSION_BUS_ADDRESS</code> environment variable + should be set at + <code>${HOME}/<var>@userconfdir@</var>/<var>@USERTREE@</var>/env/DBUS_SESSION_BUS_ADDRESS</code>, + by writing the address into this file + (see <a href="//0x53.net/software/goetia/confdir.html">configuration directory</a>). + It is recomended to set + <code>${HOME}/<var>@userconfdir@</var>/<var>@USERTREE@</var>/env/DBUS_SESSION_BUS_ADDRESS</code>, + to + <code><var>@tmpusdir@</var>/<var>@usrrundir@</var>/<var>@USER@</var>/<var>@USERTREE@</var>/session-bus</code> + (see <a href="//0x53.net/software/goetia/rundir.html">runtime directory</a>). + </p> + </body> +</html> diff --git a/doc/source/user/xdg/xdg-runtime-dir.html b/doc/source/user/xdg/xdg-runtime-dir.html new file mode 100644 index 0000000..3b17d8b --- /dev/null +++ b/doc/source/user/xdg/xdg-runtime-dir.html @@ -0,0 +1,75 @@ +<!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>xdg-runtime-dir</title> + <meta name="Description" content="User oneshot to create and remove the XDG_RUNTIME_DIR." /> + <meta name="Keywords" content="goetia s6-rc bundle xdg runtime directory user supervision tree" /> + </head> + <header> + <p> + <a href="//0x53.net/software/goetia/goetia-base">goetia-base</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 xdg-runtime-dir service</h1> + <p> + This service dynamically creates the directory + specified in the environment variable + <code>XDG_RUNTIME_DIR</code>. + </p> + <p> + Starting this service creates the directory + and sets the proper permissions, + stopping it deletes it. + </p> + <p> + It is recommended to set + <code>XDG_RUNTIME_DIR</code> + to the + <code><var>@USER@</var>/<var>@USERTREE@</var>/xdg-runtime-dir</code> + subdirectory of the + <a href="//0x53.net/software/goetia/rundir.html#user">user runtime directory</a>. + This allows to follow the + <a href="https://specifications.freedesktop.org/basedir-spec/latest/">XDG Base Directory Specification</a>. + </p> + <p> + If more than one + <a href="//0x53.net/software/goetia/supervisiontree.html#user">user supervision tree</a> + <em>per user</em> is used to have multiple + <a href="//0x53.net/software/goetia/tutorials/ui/seatsession.html">sessions</a> + with a distinct UI server, audio server, etc. + It makes sense for each session to have its own, + distinct <code>xdg-runtime-dir</code>, + since it is often used for sockets and temporary files + of said UI server, audio server, etc. + Setting + <code>XDG_RUNTIME_DIR</code> + as described above, allows for this. + Note, however, that this deviates from the + <a href="https://specifications.freedesktop.org/basedir-spec/latest/">XDG Base Directory Specification</a>. + </p> + <p> + All user services writing to or reading from + <code>XDG_RUNTIME_DIR</code> + should depend on this service. + </p> + <h2>See also</h2> + <ul> + <li> + <a href="//0x53.net/software/goetia/tutorials/ui/seatsession.html">seat and session management</a> + </li> + <li> + <a href="https://specifications.freedesktop.org/basedir-spec/latest/">XDG Base Directory Specification</a>. + </li> + </ul> + </body> +</html> |