commit 24bdfb3b50c8388d7a1d08a073c0b5b482bbe0b4
parent fb16bcc72207bf3fdab0e93681bed106e48b4bdb
Author: Friedel Schön <[email protected]>
Date: Tue, 30 May 2023 14:32:18 +0200
add inline converting
Diffstat:
5 files changed, 362 insertions(+), 359 deletions(-)
diff --git a/Makefile b/Makefile
@@ -12,6 +12,7 @@ TEMPL_DIR := src/docs
DOCS_DIR := docs
ASSETS_DIR := assets
DOC_AST_DIR := docs/assets
+MAKE_DOCS := make-docs.py
# Compiler Options
CC ?= gcc
@@ -37,8 +38,8 @@ 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))
+TEMPL_FILES := $(wildcard $(TEMPL_DIR)/*.txt)
+DOCS_FILES := $(patsubst $(TEMPL_DIR)/%.txt,$(DOCS_DIR)/%.html,$(TEMPL_FILES))
# Intermediate directories
INTERMED_DIRS := $(BIN_DIR) $(BUILD_DIR) $(ROFF_DIR) $(DOCS_DIR)
@@ -85,8 +86,8 @@ $(BIN_DIR)/%: $(EXEC_DIR)/%.sh | $(BIN_DIR)
$(BIN_DIR)/%: $(EXEC_DIR)/%.lnk | $(BIN_DIR)
ln -sf $(shell cat $<) $@
-$(DOCS_DIR)/%.html: $(TEMPL_DIR)/%.html $(DOC_AST_DIR) | $(DOCS_DIR)
- $(SED) 's/%VERSION%/$(VERSION)/' $< | $(PYTHON) make-docs.py > $@
+$(DOCS_DIR)/%.html: $(TEMPL_DIR)/%.txt $(DOC_AST_DIR) | $(DOCS_DIR)
+ $(SED) 's/%VERSION%/$(VERSION)/' $< | $(PYTHON) $(MAKE_DOCS) > $@
# Manual targets
diff --git a/docs/index.html b/docs/index.html
@@ -14,7 +14,7 @@
<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> (_Friedel's Initialization and Service Supervision_). <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>
--------------------------------------------------------------------------------
@@ -44,7 +44,7 @@ After the initialization is done, services must be started. A service is a long-
- <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>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><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>
@@ -55,7 +55,7 @@ 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>
@@ -120,7 +120,7 @@ Usually your service runs in the foreground, in this case you can create a run e
| [ -r ./conf ] && . ./conf |
| |
| exec myservice $ARGS |
-+----------------------------------------------------------------------------+This example sources conf in the service-directory if present and executes myservice with <u>$ARGS</u>. </li>
++----------------------------------------------------------------------------+This example sources conf in the service-directory if present and executes myservice with <i>$ARGS</i>. </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 |
@@ -132,14 +132,9 @@ This file describes environment-variables for run. This is as params a newline-d
| 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'. |
-+----------------------------------------------------------------------------+
++----------------------------------------------------------------------------+</li>
+<li><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>
@@ -187,8 +182,4 @@ If this file is present, the services will be started automatically and restarte
<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>
-
+<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>
diff --git a/make-docs.py b/make-docs.py
@@ -1,4 +1,5 @@
import sys
+import re
WIDTH = 80
HEADER_CHAR = '='
@@ -25,6 +26,15 @@ SUFFIX = """
</html>
"""
+HEADER_TEMPLATE = "<span class=header><a class=title id=top href=#top>{text}</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>"
+TITLE_TEMPLATE = "<a class=title id={id} href=#{id}>{text}</a>"
+
+def inline_convert(text):
+ text = re.sub(r'\*(.+?)\*', r'<b>\1</b>', text)
+ text = re.sub(r'_(.+?)_', r'<i>\1</i>', text)
+ text = re.sub(r'\[(.*?)\]\((.*?)\)', r'<a href="\2">\1</a>', text)
+ return text
+
in_code = False
in_list = False
@@ -36,11 +46,11 @@ for line in sys.stdin:
# 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_TEMPLATE.format(text=text))
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_TEMPLATE.format(id=id, text=text))
print(TITLE_CHAR * WIDTH)
elif line.startswith("@code"):
width = WIDTH -2
@@ -69,9 +79,9 @@ for line in sys.stdin:
padding = 0
print('| ' + line + ' ' * padding + ' |')
elif line.endswith('~'):
- print(line[:-1])
+ print(inline_convert(line[:-1]))
elif line:
- sys.stdout.write(line + ' ')
+ sys.stdout.write(inline_convert(line) + ' ')
elif in_list: # is empty but in line
sys.stdout.write("</li>\n<li>")
else: # is empty
diff --git a/src/docs/index.html b/src/docs/index.html
@@ -1,333 +0,0 @@
-@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
diff --git a/src/docs/index.txt b/src/docs/index.txt
@@ -0,0 +1,334 @@
+@header fiss
+
+Aloha! You somehow landed on the website of *fiss* (_Friedel's Initialization and
+Service Supervision_). *fiss* is a supervision suite for Unix and Unix-like systems
+with the power off system initialization. This project is based on *runit* and
+other *daemontools*-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 _/sbin/init_ 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 *runit*, a *daemontools*-derivate with initialization.
+Unlike *SystemD*, *runit* is a fine in-between: minimal but feature-rich. Bit too
+minimal so I thought of making *fiss*!
+
+
+@title why Why fiss tho?
+
+*fiss* 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. *fiss* support all the features to
+make services efficient running. It can be compatible with *runit* and *daemontools*
+utilities and is highly customizable at runtime to make *fiss* fit your needs.
+
+
+@title compare fiss vs runit
+
+*runit* is a good init-system and is lovely to use but there are some features
+which are just missing.
+
+@list
+*fiss* has service-ordering (aka. dependencies), thus if _service-b_ depends on
+_service-a_, you can configure it as a dependency and *fiss* will keep _service-a_
+running as long as _service-b_ is running.
+
+*fiss* has background-services, some services just won't let you run them in
+foreground. *runit* solves this problem with *pause*, 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.
+
+*runit* 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. *fiss* 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.
+
+*runit*'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. *runit*'s _down_-file method seems more like a hack.
+*fiss* supports enabling and once-enabling by default. If you like *sv*'s
+simplicity or its helpers like *vsv* or *rsv*, there is a compatibility-layer for
+*runit* or *daemontools*
+
+finit and fsvc directly call the service executable. That means there is no
+process-chaining as *runit* does. If you are running *runit* as init (runit-init):~
+- kernel executes *runit-init*~
+- this executes *runit*~
+- *runit* forks and executes _/etc/runit/{1,2,3}_~
+- _/etc/runit/2_ executes *runsvdir*~
+- *runsvdir* forks and executes *runsv*~
+- and finally *runsv* executes the underlying service executable
+
+Every fork and execute causes an overhead. Also *runsvdir* is decentralized,
+thus no central control unit can be used and every *runsv* 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.
+
+*fiss* and *runit* 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.
+
+*fiss* is written from scratch using the libc implementaions, this results in a
+readable code thus easier for contributers to dive into the codebase.
+*runit* and *daemontools* 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 *fiss*, you first have to compile it.
+
+To compile make sure you have installed the dependencies.~
+- C compiler like *gcc* or *clang* which supports the _gnu99_-standard~
+- POSIX-compliant shell like dash or bash~
+- GNU make~
+- [md2man](https://github.com/sunaku/md2man) to make the manuals
+
+If running *fiss*, you require to have following dependencies installed:~
+- POSIX-compliant shell like dash or bash~
+- GNU *awk*
+
+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
+
+
+*fiss* 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
+
+*fiss* 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
+_/usr/share/fiss/start_~
+This is the entry point of your system (similar to _/etc/runit/1_). By default
+this script sources files in unix-order inside _/etc/start.d/*.sh_.
+
+_/etc/service.d/*_~
+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.
+
+_/usr/share/fiss/stop_~
+This is the ending point of your system-lifetime (similar to _/etc/runit/3_). By
+default this script sources file in unix-order inside _/etc/stop.d/*.sh_.
+@endlist
+
+*zzz* is a utility shipped with *fiss* to suspend your system, following files are
+executed by *zzz*.
+@list
+_/usr/share/fiss/suspend_~
+This file is executed before suspending, by default this script sources
+files in unix-order inside _/etc/zzz.d/suspend/*.sh_.
+
+_/usr/share/fiss/resume_~
+This file is executed after suspending (thus before resuming), by default this script sources
+files in unix-order inside _/etc/zzz.d/resume/*.sh_.
+@endlist
+
+@title service How to create a service?
+
+Services are usually placed into _/etc/service.d_, 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 *fiss* plays its role.
+
+@list
+_./run_~
+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 *fiss* 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 _$ARGS_.
+
+_./params_~
+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'
+
+_./env_~
+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
+@endcode
+
+_./user_~
+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.
+
+_./start_~
+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
+
+_./pid_~
+This is a plain-text file containing just the PID of the service in decimal.
+
+_./stop_~
+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
+
+_./depends_~
+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
+
+_./setup_~
+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
+
+_./finish_~
+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
+
+_./log_~
+If this file is present, *fiss* will write the stdout and stderr of run to it.
+This will be done without any modifications.
+
+_./log/_ 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.
+
+_./no-log_~
+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 _log_, _log/_ or _no-log_ is not present, the output of will be redirected to
+/run/fiss/log/<service>.
+
+_./up-<runlevel>_~
+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.
+
+_./once-<runlevel>_~
+If this file is present, the services will be started automatically but not
+restarted if this services dies.
+@endlist
+
+To be a valid service, _run_, _start_ or _depends_ 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.
+
+_start_, _stop_, _setup_ and _finish_ are executed as the same user as *fsvs* or *finit* is
+started, thus root in the most cased. _user_, _env_, _params_ 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
