fiss

index.txt (15062B)

---

 @header fiss %VERSION%
 
 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 manuals fiss' manuals
 
 @list
 [*chpst(8)*](chpst.8.html) - runs a program with a changed process state
 
 [*finit(8)*](finit.8.html) - a UNIX process no 1
 
 [*fsvc(8)*](fsvc.8.html) - fiss' service controller
 
 [*fsvs(8)*](fsvs.8.html) - fiss' service superviser
 
 [*halt(8)*](halt.8.html) - halts the system
 
 [*reboot(8)*](halt.8.html) - reboots the system
 
 [*poweroff(8)*](halt.8.html) - stop the system
 
 [*modules-load(8)*](modules-load.8.html) - configure kernel modules at boot
 
 [*shutdown(8)*](shutdown.8.html) – bring down the system
 
 [*sigremap(8)*](sigremap.8.html) - catches signals and redirects mapped signal to executable
 
 [*vlogger(8)*](vlogger.8.html) - log messages to syslog or an arbitrary executable
 
 [*zzz(8)*](zzz.8.html) - suspend or hibernate your system
 @endlist
 
 @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-src pkg fiss
 xi fiss                                     # if xtools is installed
 sudo xbps-install -R hostdir/binpkgs fiss   # if xtools is not installed
 @endcode
 
 @title convert-runit Convert runit services
 
 The very most runit-service should work with fsvc but some not very efficient, thats why converting them is handy.
 Because runit (and fiss) only execute the _./run_ script, these scripts _can_ be pretty bulky.
 
 
 All services installed by *xbps*, thus available in [*void-packages*](https://github.com/void-linux/void-packages.git) follow
 some unwritten rules (unwritten as I haven't found them yet but services tent to follow some similarities).
 
 Services tent to follow this structure:
 
 @code
 #!/bin/sh (1)
 
 [ -r ./conf ] && . .conf (2)
 exec chpst -u user:group service -p $PORT $OPTS (3)
 @endcode
 
 (1) The _./run_-file always is a shell-executable, which executes the actual service.
 
 (2) If _./conf_ exist in the service-directory, it is sourced.
 
 (3) *chpst* is executed with some parameters like _-u_ which executes as user. *chpst* then executes service with modified state and
 predefined parameters from _./conf_.
 
 This is a foreground service, it means that the executable does not exit til the service is stopped. If the executable exits,
 you can expect the service to be down.~
 *fiss* also includes a stripped-down version of *chpst* for compability use, *fiss* includes a basic state management.
 
 You can extract the chpst-part to _./user_ and _./env_ (see below).
 
 If you executable has static parameters, thus no _./conf_ and no environment-variables, you can also pass the parameters in _./params_
 and sym-link the executable directly to _./run_.
 
 Void Linux packages always comes with a symbolic link _./supervise_ to _/run/runit/supervise.<service>_,
 which is meant for read-only systems running runit (expecting _/run/_ to be a temporary filesystem). If you are running a writable system,
 you can remove the link and *fiss* will create a directory. If you are running a read-only system you can either create
 the directory _/run/runit/_ and don't have to mess with runit-services or at an other location and sym-link the supervise-directories
 by yourself.
 
 
 If your _./run_ execute looks like the following, stressing the *pause*...
 
 @code
 #!/bin/sh
 
 service -p 990 start
 exec chpst -b service pause
 @endcode
 
 ... and you _./finish_ like that...
 
 @code
 #!/bin/sh
 
 service stop
 @endcode
 
 ... it's a runit-_background_ service which should be converted to a fiss-service.
 The service executable exits immediately, the actual service is running in the background.
 
 *pause* is a runit-hack, a program which just suspends until it is signaled by runit. It blocks a process-slot and
 the kernel still needs to care about it. *fiss* handles background-services different by calling _./start_ and _./stop_.
 
 You can safely remove the last exec line and rename _./run_ to _./start_ and _./finish_ to _./stop_ and it should work.
 
 @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_.
 
 _./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.