commit 126bf98416bcdc8e0c7bf7b2b026a1914632dd1e
parent e593be39c1150bb8330ab741141810b4130aedd2
Author: Friedel Schön <[email protected]>
Date: Tue, 30 May 2023 10:56:07 +0200
add documentation generator
Diffstat:
22 files changed, 700 insertions(+), 990 deletions(-)
diff --git a/Makefile b/Makefile
@@ -5,16 +5,21 @@ SRC_DIR := src
BUILD_DIR := build
INCLUDE_DIR := include
BIN_DIR := bin
-EXEC_DIR := $(SRC_DIR)/exec
+EXEC_DIR := src/exec
MAN_DIR := src/man
ROFF_DIR := man
+TEMPL_DIR := src/docs
+DOCS_DIR := docs
+ASSETS_DIR := assets
+DOC_AST_DIR := docs/assets
# Compiler Options
-CC ?= clang
+CC ?= gcc
CFLAGS += -I$(INCLUDE_DIR) -DVERSION=\"$(VERSION)\" -g -std=gnu99 -Wall -Wextra -Wpedantic -Wno-gnu-zero-variadic-macro-arguments
LDFLAGS += -fPIE
SED ?= sed
+PYTHON ?= python3
# Executable-specific flags
finit_FLAGS := -static
@@ -31,18 +36,21 @@ INCLUDE_FILES := $(wildcard $(INCLUDE_DIR)/*.h)
MAN_FILES := $(wildcard $(MAN_DIR)/*)
ROFF_FILES := $(patsubst $(MAN_DIR)/%.md,$(ROFF_DIR)/%,$(MAN_FILES)) \
$(patsubst $(MAN_DIR)/%.roff,$(ROFF_DIR)/%,$(MAN_FILES))
+
+TEMPL_FILES := $(wildcard $(TEMPL_DIR)/*.html)
+DOCS_FILES := $(patsubst $(TEMPL_DIR)/%.html,$(DOCS_DIR)/%.html,$(TEMPL_FILES))
# Intermediate directories
-INTERMED_DIRS := $(BIN_DIR) $(BUILD_DIR) $(ROFF_DIR)
+INTERMED_DIRS := $(BIN_DIR) $(BUILD_DIR) $(ROFF_DIR) $(DOCS_DIR)
# Magic targets
-.PHONY: all clean manual binary
-
+.PHONY: all clean manual binary documentation
+
.PRECIOUS: $(OBJ_FILES)
# Default target
-all: compile_flags.txt binary manual
+all: compile_flags.txt binary manual documentation
# Clean target
clean:
@@ -52,9 +60,15 @@ binary: $(BIN_FILES)
manual: $(ROFF_FILES)
+documentation: $(DOCS_FILES)
+
# Directory rules
$(INTERMED_DIRS):
mkdir -p $@
+
+$(DOC_AST_DIR): $(ASSETS_DIR) | $(DOCS_DIR)
+ cp -rv $< $@
+
# Object rules
$(BUILD_DIR)/%.o: $(SRC_DIR)/%.c $(INCLUDE_FILES) | $(BUILD_DIR)
@@ -69,7 +83,10 @@ $(BIN_DIR)/%: $(EXEC_DIR)/%.sh | $(BIN_DIR)
chmod +x $@
$(BIN_DIR)/%: $(EXEC_DIR)/%.lnk | $(BIN_DIR)
- ln -sf $(shell cat $<) $@
+ ln -sf $(shell cat $<) $@
+
+$(DOCS_DIR)/%.html: $(TEMPL_DIR)/%.html $(DOC_AST_DIR) | $(DOCS_DIR)
+ $(SED) 's/%VERSION%/$(VERSION)/' $< | $(PYTHON) make-docs.py > $@
# Manual targets
diff --git a/assets/github-mark-white.svg b/assets/github-mark-white.svg
@@ -0,0 +1 @@
+<svg width="98" height="96" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#fff"/></svg>
+\ No newline at end of file
diff --git a/assets/github-mark.svg b/assets/github-mark.svg
@@ -0,0 +1 @@
+<svg width="98" height="96" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg>
+\ No newline at end of file
diff --git a/assets/style.css b/assets/style.css
@@ -0,0 +1,91 @@
+@import url('https://fonts.googleapis.com/css2?family=Source+Code+Pro:wght@400;700&display=swap');
+
+body {
+ background: #eee;
+ color: #222;
+}
+
+body.dark {
+ background: #222;
+ color: #eee;
+}
+
+@media(max-width:999px) {
+ body {
+ font-size: 1.94vw
+ }
+}
+
+#toggle_dark {
+ background: #3c3836;
+ color: #eee;
+ cursor: pointer;
+}
+
+.dark #toggle_dark {
+ background: #eee;
+ color: #3c3836;
+}
+
+a {
+ color: inherit;
+ text-decoration: underline;
+}
+
+a:hover {
+ font-weight: bold;
+}
+
+.title {
+ color: #772121;
+ font-weight: bold;
+ text-decoration: none;
+ font-size: 14pt;
+}
+
+.title:hover {
+ text-decoration: underline;
+}
+
+.dark .title {
+ color: #ba3333;
+}
+
+#wrapper {
+ overflow-x: hidden;
+ width: 80ch;
+ font: 12pt 'Source Code Pro', monospace;
+ margin: 20px auto;
+ white-space: pre-wrap;
+}
+
+#github {
+ height: 1em;
+}
+
+ul {
+ list-style: none;
+ padding: 0;
+ margin: 0;
+}
+
+li {
+ margin-left: 2ch;
+ text-indent: -2ch;
+}
+
+li::before {
+ content: '* ';
+}
+
+.header {
+
+}
+
+.header .title {
+ float:left;
+}
+
+.header .right {
+ float: right;
+}
+\ No newline at end of file
diff --git a/assets/toggle-dark.js b/assets/toggle-dark.js
@@ -0,0 +1,20 @@
+function toggle_dark() {
+ var githubImage = document.getElementById('github');
+ var toggleButton = document.getElementById('toggle_dark');
+ if (document.body.classList.toggle('dark')) {
+ // is dark
+ githubImage.src = 'assets/github-mark-white.svg';
+ toggleButton.innerHTML = ' turn the lights on ';
+ } else {
+ // is light
+ githubImage.src = 'assets/github-mark.svg';
+ toggleButton.innerHTML = ' turn the lights off ';
+ }
+}
+
+document.addEventListener('readystatechange', function (state) {
+ if (document.readyState == 'complete')
+ if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+ toggle_dark();
+ }
+});
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/assets/style.css b/docs/assets/style.css
@@ -47,17 +47,7 @@ a:hover {
text-decoration: underline;
}
-.subtitle {
- color: #772121;
- text-decoration: underline;
-}
-
-.header {
- font-size: 18pt;
-}
-
-.dark a.title,
-.dark a.header {
+.dark .title {
color: #ba3333;
}
@@ -66,28 +56,36 @@ a:hover {
width: 80ch;
font: 12pt 'Source Code Pro', monospace;
margin: 20px auto;
- white-space: pre;
+ white-space: pre-wrap;
}
#github {
height: 1em;
}
-#me {
- max-width: 100%;
+ul {
+ list-style: none;
+ padding: 0;
+ margin: 0;
+}
+
+li {
+ margin-left: 2ch;
+ text-indent: -2ch;
}
-#contact-div {
- display: flex;
- align-items: flex-start;
+li::before {
+ content: '* ';
}
+.header {
+
+}
-#contact-img {
- flex-basis: 20%;
+.header .title {
+ float:left;
}
-#contact-text {
- flex-basis: 80%;
- padding-right: 20px;
-}
-\ No newline at end of file
+.header .right {
+ float: right;
+}
+\ No newline at end of file
diff --git a/docs/index.html b/docs/index.html
@@ -11,152 +11,77 @@
<body>
<div id=wrapper>
-<a class='header title' href='/fiss'>fiss</a> <span id=toggle_dark onclick=toggle_dark()> turn the lights on </span> <a href=https://github.com/friedelschoen/fiss><img id=github alt=GitHub src=assets/github-mark.svg /></a>
+<span class=header><a class=title id=top href=#top>fiss</a><span class=right><span id=toggle_dark onclick=toggle_dark()> turn the lights on </span> <a href=https://github.com/friedelschoen/fiss><img id=github alt=GitHub src=assets/github-mark.svg /></a></span></span>
================================================================================
-Aloha! You somehow landed on the website of <b>fiss</b> (<i>Friedel's Initialization and
-Service Supervision</i>). <b>fiss</b> is a supervision suite for Unix and Unix-like systems
-with the power off system initialization. This project is based on <b>runit</b> and
-other <b>daemontools</b>-based utilities.
+Aloha! You somehow landed on the website of <b>fiss</b> (<i>Friedel's Initialization and Service Supervision</i>). <b>fiss</b> is a supervision suite for Unix and Unix-like systems with the power off system initialization. This project is based on <b>runit</b> and other <b>daemontools</b>-based utilities.
<a class=title id=init href=#init>What does an init-system do?</a>
--------------------------------------------------------------------------------
-After the kernel has loaded all the hardware stuff and setting up a working
-environment, it executes <i>/sbin/init</i> by default which mounts pseude-drives, the
-root-drive read-writable and more. This depends on your system, the package does
-include start and stop scripts and basic agetty services.
-
-After the initialization is done, services must be started. A service is a long-
-running process, which needs to be restarted if it suddenly terminates. FreeBSD
-and other BSD's as far as I know, are handling services pretty rudimentally with
-plain shell scripts and without supervision. The most Linux distributions are
-shipped with SystemD which is the opposite of FreeBSD's rc.d idea. SystemD is
-one massive and bulky project with a lot of (useless) features. I've used Void
-Linux which is shipped with <b>runit</b>, a <b>daemontools</b>-derivate with initialization.
-Unlike <b>SystemD</b>, <b>runit</b> is a fine in-between: minimal but feature-rich. Bit too
-minimal so I thought of making <b>fiss</b>!
-
+After the kernel has loaded all the hardware stuff and setting up a working environment, it executes <i>/sbin/init</i> by default which mounts pseude-drives, the root-drive read-writable and more. This depends on your system, the package does include start and stop scripts and basic agetty services.
+After the initialization is done, services must be started. A service is a long- running process, which needs to be restarted if it suddenly terminates. FreeBSD and other BSD's as far as I know, are handling services pretty rudimentally with plain shell scripts and without supervision. The most Linux distributions are shipped with SystemD which is the opposite of FreeBSD's rc.d idea. SystemD is one massive and bulky project with a lot of (useless) features. I've used Void Linux which is shipped with <b>runit</b>, a <b>daemontools</b>-derivate with initialization. Unlike <b>SystemD</b>, <b>runit</b> is a fine in-between: minimal but feature-rich. Bit too minimal so I thought of making <b>fiss</b>!
<a class=title id=why href=#why>Why fiss tho?</a>
--------------------------------------------------------------------------------
-<b>fiss</b> is a lightweight and easy-to-use tool for initializing and supervising
-long-running services on Unix-like systems. It provides a simple and reliable
-way to start, stop, and monitor services. It supports automatic restarts,
-logging, and customizable startup options. It's no fork and uses the standard
-POSIX libc without other runtime dependencies. <b>fiss</b> support all the features to
-make services efficient running. It can be compatible with <b>runit</b> and <b>daemontools</b>
-utilities and is highly customizable at runtime to make <b>fiss</b> fit your needs.
-
+<b>fiss</b> is a lightweight and easy-to-use tool for initializing and supervising long-running services on Unix-like systems. It provides a simple and reliable way to start, stop, and monitor services. It supports automatic restarts, logging, and customizable startup options. It's no fork and uses the standard POSIX libc without other runtime dependencies. <b>fiss</b> support all the features to make services efficient running. It can be compatible with <b>runit</b> and <b>daemontools</b> utilities and is highly customizable at runtime to make <b>fiss</b> fit your needs.
<a class=title id=compare href=#compare>fiss vs runit</a>
--------------------------------------------------------------------------------
-<b>runit</b> is a good init-system and is lovely to use but there are some features
-which are just missing.
-
-* <b>fiss</b> has service-ordering (aka. dependencies), thus if <i>service-b</i> depends on
- <i>service-a</i>, you can configure it as a dependency and <b>fiss</b> will keep <i>service-a</i>
- running as long as <i>service-b</i> is running.
-
-* <b>fiss</b> has background-services, some services just won't let you run them in
- foreground. <b>runit</b> solves this problem with <b>pause</b>, a little program which just
- waits on an incoming signal. But this solution requires extra resources and
- a process-slot. It's bearly possible to hit the process-roof but for every
- process, the kernel needs to reserve memory and manage cpu-time.
-
-* <b>runit</b> has no built-in environment settings, it always runs services with a
- clear environment and you can modify it with chpst. That extends the process
- chain and cost more start-up time. <b>fiss</b> has build-in environment options for
- changing the user and group, the arguments, argv[0] or environment-variables.
- This project also includes a simplified and rewritten version of chpst, for
- compatibility use.
-
-* <b>runit</b>'s controller sv is really basic. It does not need to be very beautiful
- or feature-rich, but enabling services and enabling services once (one time
- after boot) is not possible. <b>runit</b>'s <i>down</i>-file method seems more like a hack.
- <b>fiss</b> supports enabling and once-enabling by default. If you like <b>sv</b>'s
- simplicity or its helpers like <b>vsv</b> or <b>rsv</b>, there is a compatibility-layer for
- <b>runit</b> or <b>daemontools</b>.
-
-* finit and fsvc directly call the service executable. That means there is no
- process-chaining as <b>runit</b> does. If you are running <b>runit</b> as init (runit-init):
- - kernel executes <b>runit-init</b>
- - this executes <b>runit</b>
- - <b>runit</b> forks and executes <i>/etc/runit/{1,2,3}</i>
- - <i>/etc/runit/2</i> executes <b>runsvdir</b>
- - <b>runsvdir</b> forks and executes <b>runsv</b>
- - and finally <b>runsv</b> executes the underlying service executable
-
- Every fork and execute causes an overhead. Also <b>runsvdir</b> is decentralized,
- thus no central control unit can be used and every <b>runsv</b> has its own control
- unit.
-
- On the other hand this results in more security, if a executable failes due to
- a bug, the underlying executable will catch this (if implemented). Which
- implementation is better is up to yourself.
-
-* <b>fiss</b> and <b>runit</b> are entirely written in C, init has to be minimal and a garbage
- collector would only slow down the whole system. With C you have direct
- control of the operating system.
-
-* <b>fiss</b> is written from scratch using the libc implementaions, this results in a
- readable code thus easier for contributers to dive into the codebase.
- <b>runit</b> and <b>daemontools</b> are written using the djb-library which is an
- alternative general library. It's completely fine to use the library and maybe
- it is even faster than your libc-implementation (glibc, musl, freebsd-libc).
-
-
+<b>runit</b> is a good init-system and is lovely to use but there are some features which are just missing.
+<ul>
+<li><b>fiss</b> has service-ordering (aka. dependencies), thus if <i>service-b</i> depends on <i>service-a</i>, you can configure it as a dependency and <b>fiss</b> will keep <i>service-a</i> running as long as <i>service-b</i> is running. </li>
+<li><b>fiss</b> has background-services, some services just won't let you run them in foreground. <b>runit</b> solves this problem with <b>pause</b>, a little program which just waits on an incoming signal. But this solution requires extra resources and a process-slot. It's bearly possible to hit the process-roof but for every process, the kernel needs to reserve memory and manage cpu-time. </li>
+<li><b>runit</b> has no built-in environment settings, it always runs services with a clear environment and you can modify it with chpst. That extends the process chain and cost more start-up time. <b>fiss</b> has build-in environment options for changing the user and group, the arguments, argv[0] or environment-variables. This project also includes a simplified and rewritten version of chpst, for compatibility use. </li>
+<li><b>runit</b>'s controller sv is really basic. It does not need to be very beautiful or feature-rich, but enabling services and enabling services once (one time after boot) is not possible. <b>runit</b>'s <i>down</i>-file method seems more like a hack. <b>fiss</b> supports enabling and once-enabling by default. If you like <b>sv</b>'s simplicity or its helpers like <b>vsv</b> or <b>rsv</b>, there is a compatibility-layer for <b>runit</b> or <b>daemontools</b> </li>
+<li>finit and fsvc directly call the service executable. That means there is no process-chaining as <b>runit</b> does. If you are running <b>runit</b> as init (runit-init):
+- kernel executes <b>runit-init</b>
+- this executes <b>runit</b>
+- <b>runit</b> forks and executes <i>/etc/runit/{1,2,3}</i>
+- <i>/etc/runit/2</i> executes <b>runsvdir</b>
+- <b>runsvdir</b> forks and executes <b>runsv</b>
+- and finally <b>runsv</b> executes the underlying service executable </li>
+<li>Every fork and execute causes an overhead. Also <b>runsvdir</b> is decentralized, thus no central control unit can be used and every <b>runsv</b> has its own control unit. </li>
+<li>On the other hand this results in more security, if a executable failes due to a bug, the underlying executable will catch this (if implemented). Which implementation is better is up to yourself.</li> </li>
+<li><b>fiss</b> and <b>runit</b> are entirely written in C, init has to be minimal and a garbage collector would only slow down the whole system. With C you have direct control of the operating system. </li>
+<li><b>fiss</b> is written from scratch using the libc implementaions, this results in a readable code thus easier for contributers to dive into the codebase. <b>runit</b> and <b>daemontools</b> are written using the djb-library which is an alternative general library. It's completely fine to use the library and maybe it is even faster than your libc-implementation (glibc, musl, freebsd-libc). </li></ul>
<a class=title id=install href=#install>Installation</a>
--------------------------------------------------------------------------------
-Now that you are really hyped to install <b>fiss</b>, you first have to compile it.
-
+Now that you are really hyped to install <b>fiss</b>, you first have to compile it.
To compile make sure you have installed the dependencies.
-
- C compiler like <b>gcc</b> or <b>clang</b> which supports the <i>gnu99</i>-standard
- POSIX-compliant shell like dash or bash
- GNU make
-- <a href='https://github.com/sunaku/md2man'>md2man</a> to make the manuals
-
+- <a href='https://github.com/sunaku/md2man'>md2man</a> to make the manuals
If running <b>fiss</b>, you require to have following dependencies installed:
-
- POSIX-compliant shell like dash or bash
-- GNU <b>awk</b>
-
-Download the last release from GitHub or clone this project with git to build
-from HEAD.
-
+- GNU <b>awk</b>
+Download the last release from GitHub or clone this project with git to build from HEAD.
+------------------------------------------------------------------------------+
| git clone https://github.com/friedelschoen/fiss.git |
| cd fiss/ |
+------------------------------------------------------------------------------+
-
-Then you have to compile the project with make.
-
+Then you have to compile the project with make.
+------------------------------------------------------------------------------+
| make binary # to compile the executables |
| make manual # to compile the manuals |
+------------------------------------------------------------------------------+
+Executables are now stored in ./bin, standard configuration-files are stored in ./etc, runtime-required files are in ./share and manuals in ./man.
-Executables are now stored in ./bin, standard configuration-files are stored in
-./etc, runtime-required files are in ./share and manuals in ./man.
-
-
-<a class=title id=install href=#install>Installation on Void Linux</a>
+<a class=title id=voidlinux href=#voidlinux>Installation on Void Linux</a>
--------------------------------------------------------------------------------
-If you don't have the source-tree yet, clone and bootstrap it with git.
-
+If you don't have the source-tree yet, clone and bootstrap it with git.
+------------------------------------------------------------------------------+
| git clone https://github.com/void-linux/void-packages.git |
| cd void-packages/ |
| ./xbps-src binary-bootstrap |
+------------------------------------------------------------------------------+
-<b>fiss</b> is not a official package yet, as it's too unstable to include, but you can
-add my void-packages as remote and compile.
+<b>fiss</b> is not a official package yet, as it's too unstable to include, but you can add my void-packages as remote and compile.
+------------------------------------------------------------------------------+
| git remote add fiss https://github.com/friedelschoen/void-packages.git |
@@ -166,256 +91,104 @@ add my void-packages as remote and compile.
| sudo xbps-install -R hostdir/binpkgs fiss # if xtools is not installed |
+------------------------------------------------------------------------------+
-
<a class=title id=getting-started href=#getting-started>Getting Started</a>
--------------------------------------------------------------------------------
-<b>fiss</b> does not parse any configuration file, everything is configured through
-different files inside for example /etc/service.d.
-
-Following files are executed by finit:
-
-- <i>/usr/share/fiss/start</i>
- This is the entry point of your system (similar to <i>/etc/runit/1</i>). By default
- this script sources files in unix-order inside <i>/etc/start.d/*.sh</i>.
-
-- <i>/etc/service.d/*</i>
- In this directory the services are stored, underneath is descripted how a
- service is constructed. The utility fsvs is written to supervise a service-
- directory without issuing start and stop mechanisms.
-
-- <i>/usr/share/fiss/stop</i>
- This is the ending point of your system-lifetime (similar to <i>/etc/runit/3</i>). By
- default this script sources file in unix-order inside <i>/etc/stop.d/*.sh</i>.
-
-<b>zzz</b> is a utility shipped with <b>fiss</b> to suspend your system, following files are
-executed by <b>zzz</b>.
-
-- <i>/usr/share/fiss/suspend</i>
- This file is executed before suspending, by default this script sources
- files in unix-order inside <i>/etc/zzz.d/suspend/*.sh</i>.
-
-- <i>/usr/share/fiss/resume</i>
- This file is executed after suspending (thus before resuming), by default this script sources
- files in unix-order inside <i>/etc/zzz.d/resume/*.sh</i>.
-
-
+<b>fiss</b> does not parse any configuration file, everything is configured through different files inside for example /etc/service.d.
+Following files are executed by finit:
+<ul>
+<li><i>/usr/share/fiss/start</i>
+This is the entry point of your system (similar to <i>/etc/runit/1</i>). By default this script sources files in unix-order inside <i>/etc/start.d/*.sh</i>. </li>
+<li><i>/etc/service.d/*</i>
+In this directory the services are stored, underneath is descripted how a service is constructed. The utility fsvs is written to supervise a service- directory without issuing start and stop mechanisms. </li>
+<li><i>/usr/share/fiss/stop</i>
+This is the ending point of your system-lifetime (similar to <i>/etc/runit/3</i>). By default this script sources file in unix-order inside <i>/etc/stop.d/*.sh</i>. </li></ul>
+<b>zzz</b> is a utility shipped with <b>fiss</b> to suspend your system, following files are executed by <b>zzz</b>. <ul>
+<li><i>/usr/share/fiss/suspend</i>
+This file is executed before suspending, by default this script sources files in unix-order inside <i>/etc/zzz.d/suspend/*.sh</i>. </li>
+<li><i>/usr/share/fiss/resume</i>
+This file is executed after suspending (thus before resuming), by default this script sources files in unix-order inside <i>/etc/zzz.d/resume/*.sh</i>. </li></ul>
<a class=title id=service href=#service>How to create a service?</a>
--------------------------------------------------------------------------------
-Services are usually placed into <i>/etc/service.d</i>, a services is a long-running
-executable like for example sshd, which should be running the whole lifetime of
-your system. Sadly do some services terminate before your system halts because
-of an error or signaling, this is where <b>fiss</b> plays its role.
-
-- <i>./run</i>
- Usually your service runs in the foreground, in this case you can create a run
- executable, either linked to the actual binary or as a script that executes
- the service. run is meant to be running the whole time in the foreground and
- must not daemonize itself into the background as <b>fiss</b> would restart it.
-
- +----------------------------------------------------------------------------+
- | #!/bin/sh |
- | |
- | [ -r ./conf ] && . ./conf |
- | |
- | exec myservice $ARGS |
- +----------------------------------------------------------------------------+
-
- This example sources conf in the service-directory if present and executes
- myservice with <u>$ARGS</u>.
-
-- <i>./params</i>
- run often needs parameters, these can be defined inside params. Your
- arguments must be newline-demilitered. Usually the 0th argument is not
- included and defaults to './run', but if you want to define the 0th argument
- you can prefix the first line with '%' and the argument counting starts at 0.
- No shell-substitution will be done.
-
- +----------------------------------------------------------------------------+
- | %fiss-service |
- | -L |
- | -p 8000 |
- +----------------------------------------------------------------------------+
-
- In this example, run would be executed with 'fiss-service' as 0th argument and
- '-L' '-p 8000'
-
-- <i>./env</i>
- This file describes environment-variables for run. This is as params a
- newline-demilitered file with key=value pairs. As for params, there is no
- shell-substitution done.
-
- +----------------------------------------------------------------------------+
- | HOME=/home/foo |
- | XDG_CONFIG_DIRS=/etc/ |
- | PATH=/bin:/sbin:/usr/bin:/usr/sbin |
- +----------------------------------------------------------------------------+
-
-- <i>./user</i>
- If this file is present, run will be executes as defined user and group(s).
- You can define your user as 'user' and the group will be the user group or you
- explicitly define 'user:group'. You can add multiple groups with
- 'user:group:group2:group3', if user is prefixed with a colon (':'), users and
- groups will be parsed as numeric thus ':1000:1000:1001'.
-
- +----------------------------------------------------------------------------+
- | foo:foo:mysql |
- +----------------------------------------------------------------------------+
-
- In this example, run would be executed as 'foo' and als 'foo' as group with
- 'mysql' as additional group.
-
-- <i>./start</i>
- If your services cannot be run in the foreground, you should execute link it
- to start, start is a short-running executable, if start exits it is considered
- as running. To supervise your services, it's handy to provide a pid-file
- inside your service as some services provide print its process-id to the
- console. If no pid-file is found you must implement a stop file.
-
- +----------------------------------------------------------------------------+
- | #!/bin/sh |
- | |
- | myserver --print-pid > ./pid |
- +----------------------------------------------------------------------------+
-
-- <i>./pid</i>
- This is a plain-text file containing just the PID of the service in decimal.
-
-- <i>./stop</i>
- This script is meant to stop the service, if this file exits the service is
- considered inactive. This file must not coexist with pid.
-
- +----------------------------------------------------------------------------+
- | #!/bin/sh |
- | |
- | myserver2 --stop |
- +----------------------------------------------------------------------------+
-
-- <i>./depends</i>
- This file contains newline-demilitered service-names which are dependencies of
- the service. dependencies are started before the service will be started and
- stopped if no enabled and no other service depend on it. Dependencies are just
- started, no consideration will be done that the dependency is actually active.
-
- +----------------------------------------------------------------------------+
- | dbus |
- | networking |
- +----------------------------------------------------------------------------+
-
-- <i>./setup</i>
- If this file is present and executable, it will be executed before run or
- start, it is meant for example to create files or directories.
-
- +----------------------------------------------------------------------------+
- | #!/bin/sh |
- | |
- | mkdir /var/myserver |
- +----------------------------------------------------------------------------+
-
-- <i>./finish</i>
- If this file is present and executable, it will be executed after run has
- exited or after stop was executed. This is meant to remove unnessasary files
- or directories.
-
- +----------------------------------------------------------------------------+
- | #!/bin/sh |
- | |
- | rm -rf /var/myserver |
- +----------------------------------------------------------------------------+
-
-- <i>./log</i>
- If this file is present, <b>fiss</b> will write the stdout and stderr of run to it.
- This will be done without any modifications.
-
-- <i>./log/</i> service
- If this directory is present and a valid service-directory, stdout and stderr
- of your service will be redirected to the run of the log-service. This is done
- with a internal pipe, thus no data will be lost of either services failes.
-
-- <i>./no-log</i>
- If this file is present, no logging will be done at all. This is meant for
- very verbose services, which would overflout the system.
-
- If <i>log</i>, <i>log/</i> or <i>no-log</i> is not present, the output of will be redirected to
- /run/fiss/log/<service>.
-
-- <i>./up-<runlevel></i>
- If this file is present, the services will be started automatically and
- restarted if this services dies. On other systems, this is called 'enabling'
- a service.
-
-- <i>./once-<runlevel></i>
- If this file is present, the services will be started automatically but not
- restarted if this services dies.
-
-To be a valid service, <i>run</i>, <i>start</i> or <i>depends</i> must be present. If only depends is
-present, this service is a dummy service thus no actual action will be taken but
-starting and stopping dependencies.
-
-<i>start</i>, <i>stop</i>, <i>setup</i> and <i>finish</i> are executed as the same user as <b>fsvs</b> or <b>finit</b> is
-started, thus root in the most cased. <i>user</i>, <i>env</i>, <i>params</i> are not read when
-handling a background-service. Every file will be executed in the services
-directory, reading a file like './conf' will be read out of the service
-directory.
-
-
-<a class=title id=control href=#control>Controlling Services</a>
---------------------------------------------------------------------------------
-
-To control a service, you can use <b>fsvc</b>. <b>fsvc</b> connects to the control-socket and
-controls the services. How a command and a serialized service is defined is
-stated in <i>docs/internal/</i>.
-
-<b>fiss</b> supports <b>runit</b> or <b>daemontools</b>' <b>sv</b>, if you are used to your fancy <b>sv</b>-
-implementation, you still can but keep in mind that even <b>runit</b>'s <b>sv</b> only has
-limited functionality compared to <b>fsvc</b>.
-
-Following commands are present:
-
-- status <u>[--short]</u> <u>[--check]</u> <u>[service]</u>
- Use this command to query a service. If service is omitted, every services
- is printed. If issued with check, nothing will be printed and the return-code
- is 0 if the service is active, otherwise 1. If issued with short, a table will
- be printed rather than a list. Wildcards can be used with '*' for variable-
- length and '%' for any character.
-
-- start <u>[--pin]</u> <u><service></u>
- With start, you obviously start a service but if your service is not enabled
- it will stop if it failes. You can pin this services as enabled manually,
- the services will be restarted for this session only.
-
-- stop <u>[--pin]</u> <u><service></u>
- You stop a services, but if you services is already enabled (either manually
- or through a <i>up-*</i> file) or is a dependency of something, it will be restarted
- instantly. To force this services as down, you must pin it.
-
-- enable <u>[--once]</u> <u><service></u> and disable <u>[--once]</u> <u><service></u>
- This is a helper for creating <i>up-<runlevel></i> or <i>once-<runlevel></i>. If issued
- without <u>once</u>, a <i>up-*</i> file will be created. If issued with <u>once</u>, a <i>once-*</i> file
- will be created. The service directory should be refreshed a moment after.
-
-- kill <u><service></u> <u><signal></u>
- With this command, you can send a signal to the service executable. No
- consideration will be done, thus sending SIGSTOP will not set the pause-flag.
- As a signal, you can use the number (9 as SIGKILL), the unix identifier like
- KILL or prefixed with 'SIG' thus SIGKILL.
-
-- pause <u><service></u> and resume <u><service></u>
- This pauses or resumes a services, SIGSTOP or SIGCONT will be sent to the
- executable and the pause-flag is set.
-
-- switch <u>[--reset]</u> <u><service></u>
- This switches the runlevel, all services that are enabled by file will be
- stopped. If issued with reset also all services will be stopped that were
- enabled manually with <u>start --pin</u>.
-
-
-================================================================================
-
- -*- <i>This website is based on <a href=https://kisslinux.org/>Kiss Linux</a>' website (MIT gelicenseerd)</i> -*-
-
+Services are usually placed into <i>/etc/service.d</i>, a services is a long-running executable like for example sshd, which should be running the whole lifetime of your system. Sadly do some services terminate before your system halts because of an error or signaling, this is where <b>fiss</b> plays its role.
+<ul>
+<li><i>./run</i>
+Usually your service runs in the foreground, in this case you can create a run executable, either linked to the actual binary or as a script that executes the service. run is meant to be running the whole time in the foreground and must not daemonize itself into the background as <b>fiss</b> would restart it. +----------------------------------------------------------------------------+
+| #!/bin/sh |
+| |
+| [ -r ./conf ] && . ./conf |
+| |
+| exec myservice $ARGS |
++----------------------------------------------------------------------------+This example sources conf in the service-directory if present and executes myservice with <u>$ARGS</u>. </li>
+<li><i>./params</i>
+run often needs parameters, these can be defined inside params. Your arguments must be newline-demilitered. Usually the 0th argument is not included and defaults to './run', but if you want to define the 0th argument you can prefix the first line with '%' and the argument counting starts at 0. No shell-substitution will be done. +----------------------------------------------------------------------------+
+| %fiss-service |
+| -L |
+| -p 8000 |
++----------------------------------------------------------------------------+In this example, run would be executed with 'fiss-service' as 0th argument and '-L' '-p 8000' </li>
+<li><i>./env</i>
+This file describes environment-variables for run. This is as params a newline-demilitered file with key=value pairs. As for params, there is no shell-substitution done. +----------------------------------------------------------------------------+
+| HOME=/home/foo |
+| XDG_CONFIG_DIRS=/etc/ |
+| PATH=/bin:/sbin:/usr/bin:/usr/sbin |
+| |
+| <i>./user</i>~ |
+| If this file is present, run will be executes as defined user and group(s). |
+| You can define your user as 'user' and the group will be the user group or you |
+| explicitly define 'user:group'. You can add multiple groups with |
+| 'user:group:group2:group3', if user is prefixed with a colon (':'), users and |
+| groups will be parsed as numeric thus ':1000:1000:1001'. |
++----------------------------------------------------------------------------+
+| foo:foo:mysql |
++----------------------------------------------------------------------------+In this example, run would be executed as 'foo' and als 'foo' as group with 'mysql' as additional group. </li>
+<li><i>./start</i>
+If your services cannot be run in the foreground, you should execute link it to start, start is a short-running executable, if start exits it is considered as running. To supervise your services, it's handy to provide a pid-file inside your service as some services provide print its process-id to the console. If no pid-file is found you must implement a stop file. +----------------------------------------------------------------------------+
+| #!/bin/sh |
+| |
+| myserver --print-pid > ./pid |
++----------------------------------------------------------------------------+</li>
+<li><i>./pid</i>
+This is a plain-text file containing just the PID of the service in decimal. </li>
+<li><i>./stop</i>
+This script is meant to stop the service, if this file exits the service is considered inactive. This file must not coexist with pid. +----------------------------------------------------------------------------+
+| #!/bin/sh |
+| |
+| myserver2 --stop |
++----------------------------------------------------------------------------+</li>
+<li><i>./depends</i>
+This file contains newline-demilitered service-names which are dependencies of the service. dependencies are started before the service will be started and stopped if no enabled and no other service depend on it. Dependencies are just started, no consideration will be done that the dependency is actually active. </li>
+<li>+----------------------------------------------------------------------------+
+| dbus |
+| networking |
++----------------------------------------------------------------------------+</li>
+<li><i>./setup</i>
+If this file is present and executable, it will be executed before run or start, it is meant for example to create files or directories. +----------------------------------------------------------------------------+
+| #!/bin/sh |
+| |
+| mkdir /var/myserver |
++----------------------------------------------------------------------------+</li>
+<li><i>./finish</i>
+If this file is present and executable, it will be executed after run has exited or after stop was executed. This is meant to remove unnessasary files or directories. </li>
+<li>+----------------------------------------------------------------------------+
+| #!/bin/sh |
+| |
+| rm -rf /var/myserver |
++----------------------------------------------------------------------------+</li>
+<li><i>./log</i>
+If this file is present, <b>fiss</b> will write the stdout and stderr of run to it. This will be done without any modifications. </li>
+<li><i>./log/</i> service
+If this directory is present and a valid service-directory, stdout and stderr of your service will be redirected to the run of the log-service. This is done with a internal pipe, thus no data will be lost of either services failes. </li>
+<li><i>./no-log</i>
+If this file is present, no logging will be done at all. This is meant for very verbose services, which would overflout the system.
+If <i>log</i>, <i>log/</i> or <i>no-log</i> is not present, the output of will be redirected to /run/fiss/log/<service>. </li>
+<li><i>./up-<runlevel></i>
+If this file is present, the services will be started automatically and restarted if this services dies. On other systems, this is called 'enabling' a service. </li>
+<li><i>./once-<runlevel></i>
+If this file is present, the services will be started automatically but not restarted if this services dies. </li></ul>
+To be a valid service, <i>run</i>, <i>start</i> or <i>depends</i> must be present. If only depends is present, this service is a dummy service thus no actual action will be taken but starting and stopping dependencies.
+<i>start</i>, <i>stop</i>, <i>setup</i> and <i>finish</i> are executed as the same user as <b>fsvs</b> or <b>finit</b> is started, thus root in the most cased. <i>user</i>, <i>env</i>, <i>params</i> are not read when handling a background-service. Every file will be executed in the services directory, reading a file like './conf' will be read out of the service directory.
</div>
</body>
+</html>
-</html>
-\ No newline at end of file
diff --git a/docs/internal/command.txt b/internal/command.txt
diff --git a/docs/internal/serialize.txt b/internal/serialize.txt
diff --git a/make-docs.py b/make-docs.py
@@ -0,0 +1,80 @@
+import sys
+
+WIDTH = 80
+HEADER_CHAR = '='
+TITLE_CHAR = '-'
+HEADER_SUFFIX = "<span class=right><span id=toggle_dark onclick=toggle_dark()> turn the lights on </span> <a href=https://github.com/friedelschoen/fiss><img id=github alt=GitHub src=assets/github-mark.svg /></a></span>"
+
+PREFIX = """<!doctype html>
+<html lang=en>
+
+<head>
+ <title>Friedel's Initialization and Service Supervision</title>
+ <meta charset=utf-8 />
+ <meta name=viewport content='width=device-width,initial-scale=1' />
+ <link rel=stylesheet href=assets/style.css />
+ <script type=text/javascript src=assets/toggle-dark.js></script>
+</head>
+
+<body>
+<div id=wrapper>"""
+
+SUFFIX = """
+</div>
+</body>
+</html>
+"""
+
+in_code = False
+in_list = False
+
+print(PREFIX)
+
+for line in sys.stdin:
+ line = line.strip()
+
+ # is control
+ if line.startswith("@header"):
+ _, text = line.split(" ", 1)
+ print(f"<span class=header><a class=title id=top href=#top>{text}</a>{HEADER_SUFFIX}</span>")
+ print(HEADER_CHAR * WIDTH)
+ elif line.startswith("@title"):
+ _, id, text = line.split(" ", 2)
+ print(f"<a class=title id={id} href=#{id}>{text}</a>")
+ print(TITLE_CHAR * WIDTH)
+ elif line.startswith("@code"):
+ width = WIDTH -2
+ if in_list:
+ width -= 2
+ print('+' + '-' * width + '+')
+ in_code = True
+ elif line.startswith("@endcode"):
+ width = WIDTH -2
+ if in_list:
+ width -= 2
+ sys.stdout.write('+' + '-' * width + '+')
+ in_code = False
+ elif line.startswith("@list"):
+ sys.stdout.write("<ul>\n<li>")
+ in_list = True
+ elif line.startswith("@endlist"):
+ sys.stdout.write("</li></ul>")
+ in_list = False
+
+ elif in_code:
+ padding = WIDTH - 4 - len(line)
+ if in_list:
+ padding -= 2
+ if padding < 0:
+ padding = 0
+ print('| ' + line + ' ' * padding + ' |')
+ elif line.endswith('~'):
+ print(line[:-1])
+ elif line:
+ sys.stdout.write(line + ' ')
+ elif in_list: # is empty but in line
+ sys.stdout.write("</li>\n<li>")
+ else: # is empty
+ print()
+
+print(SUFFIX)
+\ No newline at end of file
diff --git a/man/chpst.8 b/man/chpst.8
@@ -1,83 +0,0 @@
-.TH chpst 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCchpst\fR \- runs a program with a changed process state
-.SH SYNOPSIS
-.PP
-\fB\fCchpst\fR [\fB\fC\-vP012\fR] [\fB\fC\-u\fR user] [\fB\fC\-U\fR user] [\fB\fC\-b\fR argv0] [\fB\fC\-e\fR dir] [\fB\fC\-/\fR root] [\fB\fC\-n\fR inc] [\fB\fC\-l\fR|\fB\fC\-L\fR lock] [\fB\fC\-m\fR bytes] [\fB\fC\-d\fR bytes] [\fB\fC\-o\fR n] [\fB\fC\-p\fR n] [\fB\fC\-f\fR bytes] [\fB\fC\-c\fR bytes] prog [arguments...]
-.SH DESCRIPTION
-.PP
-\fB\fC\-u [:]user[:group]\fR
-.PP
-setuidgid. Set uid and gid to the user's uid and gid, as found in /etc/passwd. If user is followed by a colon and a group, set the gid to group's gid, as found in /etc/group, instead of user's gid. If group consists of a colon\-separated list of group names, chpst sets the group ids of all listed groups. If user is prefixed with a colon, the user and all group arguments are interpreted as uid and gids respectivly, and not looked up in the password or group file. All initial supplementary groups are removed.
-.PP
-\fB\fC\-U [:]user[:group]\fR
-.PP
-envuidgid. Set the environment variables $UID and $GID to the user's uid and gid, as found in /etc/passwd. If user is followed by a colon and a group, set $GID to the group's gid, as found in /etc/group, instead of user's gid. If user is prefixed with a colon, the user and group arguments are interpreted as uid and gid respectivly, and not looked up in the password or group file.
-.PP
-\fB\fC\-b argv0\fR
-Run prog with argv0 as the 0th argument.
-.PP
-\fB\fC\-/ root\fR
-Change the root directory to root before starting prog.
-.PP
-\fB\fC\-C pwd\fR
-Change the working directory to pwd before starting prog. When combined with \-/, the working directory is changed after the chroot.
-.PP
-\fB\fC\-n inc\fR
-Add inc to the
-.BR nice (2)
-value before starting prog. inc must be an integer, and may start with a minus or plus.
-.PP
-\fB\fC\-l lock\fR
-Open the file lock for writing, and obtain an exclusive lock on it. lock will be created if it does not exist. If lock is locked by another process, wait until a new lock can be obtained.
-.PP
-\fB\fC\-L lock\fR
-The same as \-l, but fail immediately if lock is locked by another process.
-.PP
-\fB\fC\-P\fR
-Run prog in a new process group.
-.PP
-\fB\fC\-0\fR
-Close standard input before starting prog.
-.PP
-\fB\fC\-1\fR
-Close standard output before starting prog.
-.PP
-\fB\fC\-2\fR
-Close standard error before starting prog.
-.SH NOT IMPLEMENTED
-.PP
-Following options are defined in runit's chpst but are ignored by fiss' implementation.
-.PP
-\fB\fC\-e dir\fR
-Set various environment variables as specified by files in the directory dir: If dir contains a file named k whose first line is v, chpst removes the environment variable k if it exists, and then adds the environment variable k with the value v. The name k must not contain =. Spaces and tabs at the end of v are removed, and nulls in v are changed to newlines. If
-the file k is empty (0 bytes long), chpst removes the environment variable k if it exists, without adding a new variable.
-.PP
-\fB\fC\-m bytes\fR
-Limit the data segment, stack segment, locked physical pages, and total of all segment per process to bytes bytes each.
-.PP
-\fB\fC\-d bytes\fR
-limit data segment. Limit the data segment per process to bytes bytes.
-.PP
-\fB\fC\-o n\fR
-Limit the number of open file descriptors per process to n.
-.PP
-\fB\fC\-p n\fR
-Limit the number of processes per uid to n.
-.PP
-\fB\fC\-f bytes\fR
-Limit the output file size to bytes bytes.
-.PP
-\fB\fC\-c bytes\fR
-Limit the core file size to bytes bytes.
-.PP
-\fB\fC\-v\fR
-Print verbose messages to standard error. This includes warnings about limits unsupported by the system.
-.SH EXIT CODES
-.PP
-chpst exits 100 when called with wrong options. It prints an error message and exits 111 if it has trouble changing the process state. Otherwise its exit code is the same as that of prog.
-.SH AUTHOR
-.PP
-Based on the implementation by Gerrit Pape \[la][email protected]\[ra],
-rewritten by Friedel Schon \[la][email protected]\[ra]
diff --git a/man/finit.8 b/man/finit.8
@@ -1,55 +0,0 @@
-.TH finit 8 "MAY 2023" "01.0" "fiss man page"
-.SH NAME
-.PP
-fiss \- a UNIX process no 1
-.SH SYNOPSIS
-.PP
-\fB\fCfsvc\fR
-when running as PID 0 (as init)
-.PP
-\fB\fCfsvc\fR <0|6>
-when running regulary to controll init
-.SH CONTROLLING
-.PP
-If \fB\fCfinit\fR is invoked by any other user than \fIroot\fP, it failes.
-.PP
-\fB\fCfinit\fR 0
-halts the system
-.PP
-\fB\fCfinit\fR 6
-reboots the system
-.SH DESCRIPTION
-.PP
-\fB\fCfiss\fR must be run as Unix process no 1 if invoked without arguments and handles the boot process in user\-land.
-.PP
-This happens in three stages:
-.SH STAGE 1
-.PP
-\fB\fCfiss\fR runs \fI/etc/fiss/start\fP and waits for it to terminate. The system's one time tasks are done here. \fI/etc/fiss/start\fP has full control of \fI/dev/console\fP to be able to start an emergency shell if the one time initialization tasks fail. If \fI/etc/fiss/start\fP crashes, \fB\fCfinit\fR will skip stage 2 and enter stage 3.
-.SH STAGE 2
-.PP
-\fB\fCfiss\fR starts all services in \fI/etc/fiss/service.d\fP which should not return until system shutdown; if it crashes, it will be restarted.
-.SH STAGE 3
-.PP
-If \fB\fCfiss\fR is told to shutdown the system, it terminates stage 2 if it is running, and runs \fI/etc/fiss/stop\fP\&. The systems tasks to shutdown and possibly halt or reboot the system are done here. If stage 3 returns, \fB\fCfinit\fR checks if the file
-.SH SIGNALS
-.PP
-\fB\fCfinit\fR only accepts signals in stage 2.
-.PP
-If \fB\fCfinit\fR receives a CONT signal and the file \fB\fCfinit\fR
-is told to shutdown the system.
-.PP
-if \fB\fCfinit\fR receives an INT signal, \fB\fCfinit\fR restarts the system.
-.SH SEE ALSO
-.PP
-.BR fiss-init (8),
-.BR runsvdir (8),
-.BR runsvchdir (8),
-.BR sv (8),
-.BR runsv (8),
-.BR chpst (8),
-.BR utmpset (8),
-.BR svlogd (8)
-.SH AUTHOR
-.PP
-Friedel Schön <\[la][email protected]\[ra]>
diff --git a/man/fsvc.8 b/man/fsvc.8
@@ -1,100 +0,0 @@
-.TH fsvc 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCfsvc\fR \- fiss' service controller
-.SH SYNOPSIS
-.PP
-\fB\fCfsvc\fR \fB\fCstart\fR [\fIoptions\fP] [\fB\fC\-\-pin_\fR] <service>
-.PP
-\fB\fCfsvc\fR \fB\fCstop\fR [\fIoptions\fP] [\fB\fC\-\-pin\fR] <service>
-.PP
-\fB\fCfsvc\fR \fB\fCenable\fR [\fIoptions\fP] [\fB\fC\-\-once\fR] <service>
-.PP
-\fB\fCfsvc\fR \fB\fCdisable\fR [\fIoptions\fP] [\fB\fC\-\-once\fR] <service>
-.PP
-\fB\fCfsvc\fR \fB\fCkill\fR [\fIoptions\fP] <service> <signal|signo>
-.PP
-\fB\fCfsvc\fR \fB\fCstatus\fR [\fIoptions\fP] [\fB\fC\-\-check\fR] [<service>]
-.PP
-\fB\fCfsvc\fR \fB\fCpause\fR [\fIoptions\fP] <service>
-.PP
-\fB\fCfsvc\fR \fB\fCresume\fR [\fIoptions\fP] <service>
-.PP
-\fB\fCfsvc\fR \fB\fCswitch\fR [\fIoptions\fP] [\fB\fC\-\-reset\fR] <runlevel>
-.SH DESCRIPTION
-.PP
-\fB\fCfsvc\fR is a command line tool for controlling services on a fiss system. It provides various commands for starting, stopping, enabling, disabling, sending signals to, checking the status of, pausing, resuming, and switching the runlevel of services.
-.SH OPTIONS
-.PP
-The following options are available for every command:
-.PP
-\fB\fC\-q, \-\-short\fR
-Will print brief information about the service.
-.PP
-\fB\fC\-r, \-\-runlevel <runlevel>\fR
-Will use \[rs]fBrunlevel\[rs]fB instead of \fIdefault\fP\&.
-.PP
-\fB\fC\-s, \-\-service\-dir <path>\fR
-Will use \fB\fCpath\fR as service directory instead of \fI/etc/fiss/service.d\fP\&.
-.PP
-\fB\fC\-v, \-\-verbose\fR
-Prints verbose information.
-.PP
-\fB\fC\-V, \-\-version\fR
-Prints the version and exits.
-.PP
-The following options are available per command:
-.PP
-\fB\fC\-p, \-\-pin\fR
-Pins the state. If issued with \fB\fCstart\fR it will cause the service to restart.
-If issued with \fB\fCstop\fR it will cause the service to be hold down.
-.PP
-\fB\fC\-o, \-\-once\fR
-Specifies that the service should only be enabled/disabled once and not automatically started/stopped on subsequent bootups.
-.PP
-\fB\fC\-c, \-\-check\fR
-Command will return \fI0\fP if the specified service is active otherwise \fI1\fP
-.PP
-\fB\fC\-r, \-\-reset\fR
-Specifies that the switch command should reset all running services (if manually set to up/down)
-.SH COMMANDS
-.PP
-The following commands are available:
-.PP
-\fB\fCstart\fR
-Starts the specified service. A synonym is \fB\fCup\fR\&.
-.PP
-\fB\fCstop\fR
-Stops the specified service. A synonym is \fB\fCdown\fR\&.
-.PP
-\fB\fCenable\fR
-Enables the specified service, causing it to automatically start on subsequent bootups.
-.PP
-\fB\fCdisable\fR
-Disables the specified service, causing it to not start automatically on subsequent bootups.
-.PP
-\fB\fCkill\fR
-Sends the specified signal or signal number to the specified service. A synonym is \fB\fCsend\fR\&.
-.PP
-\fB\fCstatus\fR
-Displays the status of the specified service. If no service is specified, displays the status of all services.
-.PP
-\fB\fCpause\fR
-Pauses the specified service.
-.PP
-\fB\fCresume\fR
-Resumes the specified service.
-.PP
-\fB\fCswitch\fR
-Switches the runlevel to the specified value.
-.SH SEE ALSO
-.PP
-.BR finit (1),
-.BR fsvc (8),
-.BR fsvs (8),
-.BR halt (8),
-.BR modules-load (8),
-.BR shutdown (8),
-.SH AUTHOR
-.PP
-Friedel Schön <\[la][email protected]\[ra]>
diff --git a/man/fsvs.8 b/man/fsvs.8
@@ -1,26 +0,0 @@
-.TH fsvs 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCfsvs\fR \- friedel's service superviser
-.SH SYNOPSIS
-.PP
-\fB\fCfsvs\fR [options] service\-dir runlevel
-.SH DESCRIPTION
-.PP
-\fB\fCfsvs\fR is the superviser called by \fB\fCfinit\fR but without initialization.
-.PP
-Following options are available:
-.PP
-\fB\fC\-v, \-\-verbose\fR
-Prints more information, easier to debug problems
-.PP
-\fB\fC\-f, \-\-force\fR
-Forces the socket if existing, if called without \fB\fC\-f\fR and the socket already exists, it failes.
-.PP
-\fB\fC\-V, \-\-version\fR
-Prints the version and exits.
-.PP
-Services can be controlled with \fB\fCfsvc 8\fR
-.SH AUTHORS
-.PP
-Friedel Schon \[la][email protected]\[ra]
diff --git a/man/halt.8 b/man/halt.8
@@ -1,38 +0,0 @@
-.TH halt 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-halt, reboot, poweroff \- stop the system
-.SH SYNOPSIS
-.PP
-\fB\fCpoweroff\fR [\fB\fC\-n\fR] [\fB\fC\-f\fR] [\fB\fC\-d\fR] [\fB\fC\-w\fR] [\fB\fC\-b\fR]
-.PP
-\fB\fCreboot\fR [\fB\fC\-n\fR] [\fB\fC\-f\fR] [\fB\fC\-d\fR] [\fB\fC\-w\fR] [\fB\fC\-b\fR]
-.PP
-\fB\fChalt\fR [\fB\fC\-n\fR] [\fB\fC\-f\fR] [\fB\fC\-d\fR] [\fB\fC\-w\fR] [\fB\fC\-b\fR]
-.SH DESCRIPTION
-.PP
-\fB\fCpoweroff\fR / \fB\fCreboot\fR / \fB\fChalt\fR tells \fB\fCinit\fR to stop running services and stop the system. Invoked without \fB\fC\-f\fR, it is a shortcut for \fB\fCinit <0|6>\fR
-.SH OPTIONS
-.PP
-\fB\fC\-n\fR
-Don't sync devices, this doensn't imply that the kernel is not synced already
-.PP
-\fB\fC\-f\fR
-Forces halt / reboot without notifying \fB\fCinit\fR\&. Forcing the system to halt should be the last hope and can be dangerous, you should not try it
-.PP
-\fB\fC\-d\fR
-Don't write the \fIwtmp\fP record
-.PP
-\fB\fCw\fR
-Only write the wtmp record, no further action
-.SH SEE ALSO
-.PP
-.BR finit (1),
-.BR fsvc (8),
-.BR fsvs (8),
-.BR halt (8),
-.BR modules-load (8),
-.BR shutdown (8),
-.SH AUTHOR
-.PP
-Based on the version of Leah Neukirchen <\[la][email protected]\[ra]>, rewritten by Friedel Schön <\[la][email protected]\[ra]>
diff --git a/man/modules-load.8 b/man/modules-load.8
@@ -1,37 +0,0 @@
-.TH modules\-load 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCmodules\-load\fR \- configure kernel modules at boot
-.SH SYNOPSIS
-.PP
-\fB\fCmodules\-load\fR [\fB\fC\-nv\fR]
-.SH DESCRIPTION
-.PP
-modules\-load reads files which contain kernel modules to load during boot from the list of locations below.
-.PP
-\fB\fC\-n\fR
-dry\-run mode. This option does everything but actually insert or
-delete the modules.
-.PP
-\fB\fC\-v\fR
-verbose mode. Print messages about what the program is doing.
-.SH FILES
-.PP
-Configuration files are read from the following locations:
-.PP
-\fI/etc/modules\-load.d/*\&.conf\fP
-.PP
-\fI/run/modules\-load.d/*\&.conf\fP
-.PP
-\fI/usr/lib/modules\-load.d/*\&.conf\fP
-.PP
-The configuration files should simply contain a list of kernel module
-names to load, separated by newlines. Empty lines and lines whose first
-non\-whitespace character is # or ; are ignored.
-.SH HISTORY
-.PP
-This program is a replacement for the modules\-load utility provided by
-systemd.
-.SH AUTHOR
-.PP
-Leah Neukirchen, \[la][email protected]\[ra]\&.
diff --git a/man/shutdown.8 b/man/shutdown.8
@@ -1,82 +0,0 @@
-.TH shutdown 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCshutdown\fR – bring down the system
-.SH SYNOPSIS
-.PP
-\fB\fCshutdown\fR [\fB\fC\-rhP\fR] [\fB\fC\-fF\fR] [now | +mins] [message ...]
-.SH DESCRIPTION
-.PP
-shutdown brings the system down in a secure way. All logged\-in users are notified that the system is going down, and
-.BR login (1)
-is blocked.
-.PP
-By default, shutdown puts the system into single user mode. Rebooting and halting the system can be done using the following options:
-.PP
-\fB\fC\-c\fR
-Cancel an ongoing shutdown.
-.PP
-\fB\fC\-f\fR
-Enable fast booting; skip
-.BR fsck (8)
-on next boot.
-.PP
-\fB\fC\-F\fR
-Force run of
-.BR fsck (8)
-on next boot.
-.PP
-\fB\fC\-h\fR
-Halt the system.
-.PP
-\fB\fC\-k\fR
-Don't really shutdown; only send the warning messages to everybody.
-.PP
-\fB\fC\-P\fR
-Poweroff the system.
-.PP
-\fB\fC\-r\fR
-Reboot the system.
-.PP
-\fB\fCnow\fR
-Shutdown without further waiting.
-.PP
-\fB\fC+mins\fR
-Wait mins minutes before shutting down.
-.PP
-\fB\fCmessage\fR
-.PP
-Message displayed to all users, defaults to "system is going down".
-.SH UNSUPPORTED OPTIONS
-.PP
-This version of shutdown is based on
-.BR runit (8),
-the following features are not supported:
-.PP
-\fB\fC\-t secs\fR
-to wait secs seconds between SIGKILL and SIGTERM on shutdown is silently ignored.
-.PP
-\fB\fC\-a\fR
-Use /etc/shutdown.allow.
-.PP
-\fB\fC\-H\fR
-Drop into boot monitor.
-.PP
-\fB\fC\-n\fR
-Don't call
-.BR init (8).
-.PP
-\fB\fChh:mm\fR
-Absolute time specification is not implemented.
-.SH SEE ALSO
-.PP
-.BR fsck (8),
-.BR halt (8),
-.BR init (8),
-.BR poweroff (8),
-.BR reboot (8),
-.BR fiss (8),
-.BR runsvchdir (8)
-.SH AUTHOR
-.PP
-Leah Neukirchen, \[la][email protected]\[ra]\&.
diff --git a/man/sigremap.8 b/man/sigremap.8
@@ -1,28 +0,0 @@
-.TH sigremap 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCsigremap\fR \- a minimal init system for Linux containers
-.SH SYNOPSIS
-.PP
-\fB\fCsigremap\fR [option] [old\-signal=new\-signal...] command [arguments ...]
-.SH DESCRIPTION
-.PP
-\fB\fCsigremap\fR is a simple process supervisor that forwards signals to children. It is designed to run as PID1 in minimal container environments.
-.PP
-Optional arguments:
-.PP
-\fB\fC\-c, \-\-single\fR
-Run in single\-child mode. In this mode, signals are only proxied to the direct child and not any of its descendants.
-.PP
-\fB\fC\-v, \-\-verbose\fR
-Print debugging information to stderr.
-.PP
-\fB\fC\-V, \-\-version\fR
-Print the current version and exit.
-.PP
-\fB\fCold\-signal=new\-signal...\fR
-Rewrite received signal s to new signal r before proxying. To ignore (not proxy) a signal, rewrite it to 0. This option can be specified multiple times.
-.SH AUTHORS
-.PP
-\fB\fCsigremap\fR is based on dumb\-init by Yelp.
-Rewritten by Friedel Schon \[la][email protected]\[ra]
diff --git a/man/vlogger.1 b/man/vlogger.1
@@ -1,115 +0,0 @@
-.TH vlogger 1 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-\fB\fCvlogger\fR \- log messages to syslog or an arbitrary executable
-.SH SYNOPSIS
-.PP
-\fB\fCvlogger\fR [\fB\fC\-isS\fR] [\fB\fC\-f\fR file] [\fB\fC\-p\fR pri] [\fB\fC\-t\fR tag] [message ...]
-.SH DESCRIPTION
-.PP
-The vlogger utility writes messages to the system log or an arbitrary executable.
-.PP
-If vlogger is executed as logger it will always use the system log and behave like the regular
-.BR logger (1).
-.PP
-Without message arguments vlogger reads messages from stdin or the file specified with the \-f flag. If the /etc/vlogger executable exists vlogger executes it with tag, level and facility as arguments, replacing
-the vlogger process.
-.PP
-If vlogger is executed as a log service for
-.BR fiss (8)
-or another daemontools like supervision suite it uses the service name as default tag. As example if vlogger is linked to /var/service/foo/log/run it uses “foo” as tag and “daemon.notice” as pri.
-.PP
-The options are as follows:
-.PP
-\fB\fC\-f file\fR
-Read lines from the specified file. This option cannot be combine message arguments.
-.PP
-\fB\fC\-i\fR
-Log the PID of the vlogger process. Only supported if
-.BR syslog (3)
-is used.
-.PP
-\fB\fC\-p pri\fR
-The. pri can be facility.level or just facility. See FACILITIES, LEVELS or
-.BR syslog (3).
-The default is “user.notice”.
-.PP
-\fB\fC\-S\fR
-Force vlogger to use
-.BR syslog (3)
-even if /etc/vlogger exists.
-.PP
-\fB\fC\-s\fR
-Output the message to standard error, as well as
-.BR syslog (3).
-Only supported if
-.BR syslog (3)
-is used.
-.PP
-\fB\fC\-t tag\fR
-Defines the
-.BR openlog (3)
-ident which is used as prefix for each log message or passed as first argument to /etc/vlogger. The default is the LOGNAME environment variable.
-.PP
-\fB\fCmessage\fR
-Write the message to the system log.
-.SH FACILITIES
-.PP
-auth
-authpriv
-cron
-daemon
-ftp
-kern can not be used from userspace replaced with daemon.
-lpr
-mail
-news
-syslog
-user
-uucp
-local[0\-7]
-security deprecated synonym for auth.
-.SH LEVELS
-.PP
-emerg
-alert
-crit
-err
-warning
-notice
-info
-debug
-panic deprecated synonym for emerg.
-error deprecated synonym for err.
-warn deprecated synonym for warning.
-.SH FILES
-.PP
-\fB\fC/etc/vlogger\fR
-An optional executable file that is used to handle the messages. It is executed with tag, level and facility as arguments and replaces the vlogger process.
-.SH EXIT STATUS
-.PP
-The vlogger utility exits 0 on success, and >0 if an error occurs.
-.SH EXAMPLES
-.PP
-\fB\fC/etc/vlogger:\fR
-.SH !/bin/sh
-.PP
-exec svlogd /var/log/$1
-.SH SEE ALSO
-.PP
-.BR logger (1),
-.BR syslog (3),
-.BR svlogd (8)
-.SH HISTORY
-.PP
-This program is a replacement for the logger utility provided by util\-linux and forked from daemontools.
-.SH AUTHORS
-.PP
-Duncan Overbruck \[la][email protected]\[ra]
-.SH LICENSE
-.PP
-vlogger is in the public domain.
-.PP
-To the extent possible under law, the creator of this work has waived all copyright and related or neighboring rights to this work.
-.PP
-\[la]http://creativecommons.org/publicdomain/zero/1.0/\[ra]
diff --git a/man/zzz.8 b/man/zzz.8
@@ -1,44 +0,0 @@
-.TH zzz 8 "MAY 2023" "0.3.2" "fiss man page"
-.SH NAME
-.PP
-zzz \- suspend or hibernate your system
-.SH SYNOPSIS
-.PP
-\fB\fCzzz [\-nSzZRH]\fR
-.SH DESCRIPTION
-.PP
-\fB\fCzzz\fR is a simple utility to hibernate or suspend your computer and part of the fiss\-system. It supports suspend/resume\-hooks.
-.PP
-\fB\fC\-n, \-\-noop\fR
-dry\-run, sleep for 5sec instead of actually running ACPI actions.
-.PP
-\fB\fC\-S, \-\-freeze\fR
-enter low\-power idle mode
-.PP
-\fB\fC\-z, \-\-suspend\fR
-suspend to RAM, this is the default behaviour of \fB\fCzzz\fR
-.PP
-\fB\fC\-Z, \-\-hibernate\fR
-hibernate to disk and power off
-.PP
-\fB\fC\-R, \-\-reboot\fR
-hibernate to disk and reboot (useful for switching operating systems)
-.PP
-\fB\fC\-H, \-\-hybrid\fR
-hibernate to disk and suspend
-.SH HOOKS
-.PP
-Before suspending, \fB\fCzzz\fR executes \fI/usr/share/fiss/suspend\fP which intents to execute scripts inside \fI/etc/zzz.d/suspend\fP in alphanumeric order. After resuming, \fB\fCzzz\fR executes \fI/usr/share/fiss/resume\fP which intents to execute scripts inside \fI/etc/zzz.d/resume\fP in alphanumeric order.
-.SH SEE ALSO
-.PP
-.BR fiss-init (8),
-.BR runsvdir (8),
-.BR runsvchdir (8),
-.BR sv (8),
-.BR runsv (8),
-.BR chpst (8),
-.BR utmpset (8),
-.BR svlogd (8)
-.SH AUTHOR
-.PP
-Based on the version of Leah Neukirchen <\[la][email protected]\[ra]>, rewritten by Friedel Schön <\[la][email protected]\[ra]>
diff --git a/src/docs/index.html b/src/docs/index.html
@@ -0,0 +1,333 @@
+@header fiss
+
+Aloha! You somehow landed on the website of <b>fiss</b> (<i>Friedel's Initialization and
+Service Supervision</i>). <b>fiss</b> is a supervision suite for Unix and Unix-like systems
+with the power off system initialization. This project is based on <b>runit</b> and
+other <b>daemontools</b>-based utilities.
+
+
+@title init What does an init-system do?
+
+After the kernel has loaded all the hardware stuff and setting up a working
+environment, it executes <i>/sbin/init</i> by default which mounts pseude-drives, the
+root-drive read-writable and more. This depends on your system, the package does
+include start and stop scripts and basic agetty services.
+
+After the initialization is done, services must be started. A service is a long-
+running process, which needs to be restarted if it suddenly terminates. FreeBSD
+and other BSD's as far as I know, are handling services pretty rudimentally with
+plain shell scripts and without supervision. The most Linux distributions are
+shipped with SystemD which is the opposite of FreeBSD's rc.d idea. SystemD is
+one massive and bulky project with a lot of (useless) features. I've used Void
+Linux which is shipped with <b>runit</b>, a <b>daemontools</b>-derivate with initialization.
+Unlike <b>SystemD</b>, <b>runit</b> is a fine in-between: minimal but feature-rich. Bit too
+minimal so I thought of making <b>fiss</b>!
+
+
+@title why Why fiss tho?
+
+<b>fiss</b> is a lightweight and easy-to-use tool for initializing and supervising
+long-running services on Unix-like systems. It provides a simple and reliable
+way to start, stop, and monitor services. It supports automatic restarts,
+logging, and customizable startup options. It's no fork and uses the standard
+POSIX libc without other runtime dependencies. <b>fiss</b> support all the features to
+make services efficient running. It can be compatible with <b>runit</b> and <b>daemontools</b>
+utilities and is highly customizable at runtime to make <b>fiss</b> fit your needs.
+
+
+@title compare fiss vs runit
+
+<b>runit</b> is a good init-system and is lovely to use but there are some features
+which are just missing.
+
+@list
+<b>fiss</b> has service-ordering (aka. dependencies), thus if <i>service-b</i> depends on
+<i>service-a</i>, you can configure it as a dependency and <b>fiss</b> will keep <i>service-a</i>
+running as long as <i>service-b</i> is running.
+
+<b>fiss</b> has background-services, some services just won't let you run them in
+foreground. <b>runit</b> solves this problem with <b>pause</b>, a little program which just
+waits on an incoming signal. But this solution requires extra resources and
+a process-slot. It's bearly possible to hit the process-roof but for every
+process, the kernel needs to reserve memory and manage cpu-time.
+
+<b>runit</b> has no built-in environment settings, it always runs services with a
+clear environment and you can modify it with chpst. That extends the process
+chain and cost more start-up time. <b>fiss</b> has build-in environment options for
+changing the user and group, the arguments, argv[0] or environment-variables.
+This project also includes a simplified and rewritten version of chpst, for
+compatibility use.
+
+<b>runit</b>'s controller sv is really basic. It does not need to be very beautiful
+or feature-rich, but enabling services and enabling services once (one time
+after boot) is not possible. <b>runit</b>'s <i>down</i>-file method seems more like a hack.
+<b>fiss</b> supports enabling and once-enabling by default. If you like <b>sv</b>'s
+simplicity or its helpers like <b>vsv</b> or <b>rsv</b>, there is a compatibility-layer for
+<b>runit</b> or <b>daemontools</b>
+
+finit and fsvc directly call the service executable. That means there is no
+process-chaining as <b>runit</b> does. If you are running <b>runit</b> as init (runit-init):~
+- kernel executes <b>runit-init</b>~
+- this executes <b>runit</b>~
+- <b>runit</b> forks and executes <i>/etc/runit/{1,2,3}</i>~
+- <i>/etc/runit/2</i> executes <b>runsvdir</b>~
+- <b>runsvdir</b> forks and executes <b>runsv</b>~
+- and finally <b>runsv</b> executes the underlying service executable
+
+Every fork and execute causes an overhead. Also <b>runsvdir</b> is decentralized,
+thus no central control unit can be used and every <b>runsv</b> has its own control
+unit.
+
+On the other hand this results in more security, if a executable failes due to
+a bug, the underlying executable will catch this (if implemented). Which
+implementation is better is up to yourself.</li>
+
+<b>fiss</b> and <b>runit</b> are entirely written in C, init has to be minimal and a garbage
+collector would only slow down the whole system. With C you have direct
+control of the operating system.
+
+<b>fiss</b> is written from scratch using the libc implementaions, this results in a
+readable code thus easier for contributers to dive into the codebase.
+<b>runit</b> and <b>daemontools</b> are written using the djb-library which is an
+alternative general library. It's completely fine to use the library and maybe
+it is even faster than your libc-implementation (glibc, musl, freebsd-libc).
+@endlist
+
+@title install Installation
+
+Now that you are really hyped to install <b>fiss</b>, you first have to compile it.
+
+To compile make sure you have installed the dependencies.~
+- C compiler like <b>gcc</b> or <b>clang</b> which supports the <i>gnu99</i>-standard~
+- POSIX-compliant shell like dash or bash~
+- GNU make~
+- <a href='https://github.com/sunaku/md2man'>md2man</a> to make the manuals
+
+If running <b>fiss</b>, you require to have following dependencies installed:~
+- POSIX-compliant shell like dash or bash~
+- GNU <b>awk</b>
+
+Download the last release from GitHub or clone this project with git to build
+from HEAD.
+
+@code
+git clone https://github.com/friedelschoen/fiss.git
+cd fiss/
+@endcode
+
+Then you have to compile the project with make.
+
+@code
+make binary # to compile the executables
+make manual # to compile the manuals
+@endcode
+
+Executables are now stored in ./bin, standard configuration-files are stored in
+./etc, runtime-required files are in ./share and manuals in ./man.
+
+
+@title voidlinux Installation on Void Linux
+
+If you don't have the source-tree yet, clone and bootstrap it with git.
+
+@code
+git clone https://github.com/void-linux/void-packages.git
+cd void-packages/
+./xbps-src binary-bootstrap
+@endcode
+
+
+<b>fiss</b> is not a official package yet, as it's too unstable to include, but you can
+add my void-packages as remote and compile.
+
+
+@code
+git remote add fiss https://github.com/friedelschoen/void-packages.git
+git pull fiss fiss
+./xbps pkg fiss
+xi fiss # if xtools is installed
+sudo xbps-install -R hostdir/binpkgs fiss # if xtools is not installed
+@endcode
+
+
+@title getting-started Getting Started
+
+<b>fiss</b> does not parse any configuration file, everything is configured through
+different files inside for example /etc/service.d.
+
+Following files are executed by finit:
+
+@list
+<i>/usr/share/fiss/start</i>~
+This is the entry point of your system (similar to <i>/etc/runit/1</i>). By default
+this script sources files in unix-order inside <i>/etc/start.d/*.sh</i>.
+
+<i>/etc/service.d/*</i>~
+In this directory the services are stored, underneath is descripted how a
+service is constructed. The utility fsvs is written to supervise a service-
+directory without issuing start and stop mechanisms.
+
+<i>/usr/share/fiss/stop</i>~
+This is the ending point of your system-lifetime (similar to <i>/etc/runit/3</i>). By
+default this script sources file in unix-order inside <i>/etc/stop.d/*.sh</i>.
+@endlist
+
+<b>zzz</b> is a utility shipped with <b>fiss</b> to suspend your system, following files are
+executed by <b>zzz</b>.
+@list
+<i>/usr/share/fiss/suspend</i>~
+This file is executed before suspending, by default this script sources
+files in unix-order inside <i>/etc/zzz.d/suspend/*.sh</i>.
+
+<i>/usr/share/fiss/resume</i>~
+This file is executed after suspending (thus before resuming), by default this script sources
+files in unix-order inside <i>/etc/zzz.d/resume/*.sh</i>.
+@endlist
+
+@title service How to create a service?
+
+Services are usually placed into <i>/etc/service.d</i>, a services is a long-running
+executable like for example sshd, which should be running the whole lifetime of
+your system. Sadly do some services terminate before your system halts because
+of an error or signaling, this is where <b>fiss</b> plays its role.
+
+@list
+<i>./run</i>~
+Usually your service runs in the foreground, in this case you can create a run
+executable, either linked to the actual binary or as a script that executes
+the service. run is meant to be running the whole time in the foreground and
+must not daemonize itself into the background as <b>fiss</b> would restart it.
+@code
+#!/bin/sh
+
+[ -r ./conf ] && . ./conf
+
+exec myservice $ARGS
+@endcode
+This example sources conf in the service-directory if present and executes
+myservice with <u>$ARGS</u>.
+
+<i>./params</i>~
+run often needs parameters, these can be defined inside params. Your
+arguments must be newline-demilitered. Usually the 0th argument is not
+included and defaults to './run', but if you want to define the 0th argument
+you can prefix the first line with '%' and the argument counting starts at 0.
+No shell-substitution will be done.
+@code
+%fiss-service
+-L
+-p 8000
+@endcode
+In this example, run would be executed with 'fiss-service' as 0th argument and
+'-L' '-p 8000'
+
+<i>./env</i>~
+This file describes environment-variables for run. This is as params a
+newline-demilitered file with key=value pairs. As for params, there is no
+shell-substitution done.
+@code
+HOME=/home/foo
+XDG_CONFIG_DIRS=/etc/
+PATH=/bin:/sbin:/usr/bin:/usr/sbin
+
+<i>./user</i>~
+If this file is present, run will be executes as defined user and group(s).
+You can define your user as 'user' and the group will be the user group or you
+explicitly define 'user:group'. You can add multiple groups with
+'user:group:group2:group3', if user is prefixed with a colon (':'), users and
+groups will be parsed as numeric thus ':1000:1000:1001'.
+@code
+foo:foo:mysql
+@endcode
+In this example, run would be executed as 'foo' and als 'foo' as group with
+'mysql' as additional group.
+
+<i>./start</i>~
+If your services cannot be run in the foreground, you should execute link it
+to start, start is a short-running executable, if start exits it is considered
+as running. To supervise your services, it's handy to provide a pid-file
+inside your service as some services provide print its process-id to the
+console. If no pid-file is found you must implement a stop file.
+@code
+#!/bin/sh
+
+myserver --print-pid > ./pid
+@endcode
+
+<i>./pid</i>~
+This is a plain-text file containing just the PID of the service in decimal.
+
+<i>./stop</i>~
+This script is meant to stop the service, if this file exits the service is
+considered inactive. This file must not coexist with pid.
+@code
+#!/bin/sh
+
+myserver2 --stop
+@endcode
+
+<i>./depends</i>~
+This file contains newline-demilitered service-names which are dependencies of
+the service. dependencies are started before the service will be started and
+stopped if no enabled and no other service depend on it. Dependencies are just
+started, no consideration will be done that the dependency is actually active.
+
+@code
+dbus
+networking
+@endcode
+
+<i>./setup</i>~
+If this file is present and executable, it will be executed before run or
+start, it is meant for example to create files or directories.
+@code
+#!/bin/sh
+
+mkdir /var/myserver
+@endcode
+
+<i>./finish</i>~
+If this file is present and executable, it will be executed after run has
+exited or after stop was executed. This is meant to remove unnessasary files
+or directories.
+
+@code
+#!/bin/sh
+
+rm -rf /var/myserver
+@endcode
+
+<i>./log</i>~
+If this file is present, <b>fiss</b> will write the stdout and stderr of run to it.
+This will be done without any modifications.
+
+<i>./log/</i> service~
+If this directory is present and a valid service-directory, stdout and stderr
+of your service will be redirected to the run of the log-service. This is done
+with a internal pipe, thus no data will be lost of either services failes.
+
+<i>./no-log</i>~
+If this file is present, no logging will be done at all. This is meant for
+very verbose services, which would overflout the system.~
+If <i>log</i>, <i>log/</i> or <i>no-log</i> is not present, the output of will be redirected to
+/run/fiss/log/<service>.
+
+<i>./up-<runlevel></i>~
+If this file is present, the services will be started automatically and
+restarted if this services dies. On other systems, this is called 'enabling'
+a service.
+
+<i>./once-<runlevel></i>~
+If this file is present, the services will be started automatically but not
+restarted if this services dies.
+@endlist
+
+To be a valid service, <i>run</i>, <i>start</i> or <i>depends</i> must be present. If only depends is
+present, this service is a dummy service thus no actual action will be taken but
+starting and stopping dependencies.
+
+<i>start</i>, <i>stop</i>, <i>setup</i> and <i>finish</i> are executed as the same user as <b>fsvs</b> or <b>finit</b> is
+started, thus root in the most cased. <i>user</i>, <i>env</i>, <i>params</i> are not read when
+handling a background-service. Every file will be executed in the services
+directory, reading a file like './conf' will be read out of the service
+directory.
+\ No newline at end of file
