index.txt (15062B) download
1@header fiss %VERSION%
2
3Aloha! 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
4with the power off system initialization. This project is based on *runit* and
5other *daemontools*-based utilities.
6
7@title manuals fiss' manuals
8
9@list
10[*chpst(8)*](chpst.8.html) - runs a program with a changed process state
11
12[*finit(8)*](finit.8.html) - a UNIX process no 1
13
14[*fsvc(8)*](fsvc.8.html) - fiss' service controller
15
16[*fsvs(8)*](fsvs.8.html) - fiss' service superviser
17
18[*halt(8)*](halt.8.html) - halts the system
19
20[*reboot(8)*](halt.8.html) - reboots the system
21
22[*poweroff(8)*](halt.8.html) - stop the system
23
24[*modules-load(8)*](modules-load.8.html) - configure kernel modules at boot
25
26[*shutdown(8)*](shutdown.8.html) – bring down the system
27
28[*sigremap(8)*](sigremap.8.html) - catches signals and redirects mapped signal to executable
29
30[*vlogger(8)*](vlogger.8.html) - log messages to syslog or an arbitrary executable
31
32[*zzz(8)*](zzz.8.html) - suspend or hibernate your system
33@endlist
34
35@title init What does an init-system do?
36
37After the kernel has loaded all the hardware stuff and setting up a working
38environment, it executes _/sbin/init_ by default which mounts pseude-drives, the
39root-drive read-writable and more. This depends on your system, the package does
40include start and stop scripts and basic agetty services.
41
42After the initialization is done, services must be started. A service is a long-
43running process, which needs to be restarted if it suddenly terminates. FreeBSD
44and other BSD's as far as I know, are handling services pretty rudimentally with
45plain shell scripts and without supervision. The most Linux distributions are
46shipped with SystemD which is the opposite of FreeBSD's rc.d idea. SystemD is
47one massive and bulky project with a lot of (useless) features. I've used Void
48Linux which is shipped with *runit*, a *daemontools*-derivate with initialization.
49Unlike *SystemD*, *runit* is a fine in-between: minimal but feature-rich. Bit too
50minimal so I thought of making *fiss*!
51
52@title why Why fiss tho?
53
54*fiss* is a lightweight and easy-to-use tool for initializing and supervising
55long-running services on Unix-like systems. It provides a simple and reliable
56way to start, stop, and monitor services. It supports automatic restarts,
57logging, and customizable startup options. It's no fork and uses the standard
58POSIX libc without other runtime dependencies. *fiss* support all the features to
59make services efficient running. It can be compatible with *runit* and *daemontools*
60utilities and is highly customizable at runtime to make *fiss* fit your needs.
61
62@title compare fiss vs runit
63
64*runit* is a good init-system and is lovely to use but there are some features
65which are just missing.
66
67@list
68*fiss* has service-ordering (aka. dependencies), thus if _service-b_ depends on
69_service-a_, you can configure it as a dependency and *fiss* will keep _service-a_
70running as long as _service-b_ is running.
71
72*fiss* has background-services, some services just won't let you run them in
73foreground. *runit* solves this problem with *pause*, a little program which just
74waits on an incoming signal. But this solution requires extra resources and
75a process-slot. It's bearly possible to hit the process-roof but for every
76process, the kernel needs to reserve memory and manage cpu-time.
77
78*runit* has no built-in environment settings, it always runs services with a
79clear environment and you can modify it with chpst. That extends the process
80chain and cost more start-up time. *fiss* has build-in environment options for
81changing the user and group, the arguments, argv[0] or environment-variables.
82This project also includes a simplified and rewritten version of chpst, for
83compatibility use.
84
85*runit*'s controller sv is really basic. It does not need to be very beautiful
86or feature-rich, but enabling services and enabling services once (one time
87after boot) is not possible. *runit*'s _down_-file method seems more like a hack.
88*fiss* supports enabling and once-enabling by default. If you like *sv*'s
89simplicity or its helpers like *vsv* or *rsv*, there is a compatibility-layer for
90*runit* or *daemontools*
91
92finit and fsvc directly call the service executable. That means there is no
93process-chaining as *runit* does. If you are running *runit* as init (runit-init):~
94- kernel executes *runit-init*~
95- this executes *runit*~
96- *runit* forks and executes _/etc/runit/{1,2,3}_~
97- _/etc/runit/2_ executes *runsvdir*~
98- *runsvdir* forks and executes *runsv*~
99- and finally *runsv* executes the underlying service executable
100
101Every fork and execute causes an overhead. Also *runsvdir* is decentralized,
102thus no central control unit can be used and every *runsv* has its own control
103unit.
104
105On the other hand this results in more security, if a executable failes due to
106a bug, the underlying executable will catch this (if implemented). Which
107implementation is better is up to yourself.
108
109*fiss* and *runit* are entirely written in C, init has to be minimal and a garbage
110collector would only slow down the whole system. With C you have direct
111control of the operating system.
112
113*fiss* is written from scratch using the libc implementaions, this results in a
114readable code thus easier for contributers to dive into the codebase.
115*runit* and *daemontools* are written using the djb-library which is an
116alternative general library. It's completely fine to use the library and maybe
117it is even faster than your libc-implementation (glibc, musl, freebsd-libc).
118@endlist
119
120@title install Installation
121
122Now that you are really hyped to install *fiss*, you first have to compile it.
123
124To compile make sure you have installed the dependencies.~
125- C compiler like *gcc* or *clang* which supports the _gnu99_-standard~
126- POSIX-compliant shell like dash or bash~
127- GNU make~
128- [md2man](https://github.com/sunaku/md2man) to make the manuals
129
130If running *fiss*, you require to have following dependencies installed:~
131- POSIX-compliant shell like dash or bash~
132- GNU *awk*
133
134Download the last release from GitHub or clone this project with git to build
135from HEAD.
136
137@code
138git clone https://github.com/friedelschoen/fiss.git
139cd fiss/
140@endcode
141
142Then you have to compile the project with make.
143
144@code
145make binary # to compile the executables
146make manual # to compile the manuals
147@endcode
148
149Executables are now stored in ./bin, standard configuration-files are stored in
150./etc, runtime-required files are in ./share and manuals in ./man.
151
152@title voidlinux Installation on Void Linux
153
154If you don't have the source-tree yet, clone and bootstrap it with git.
155
156@code
157git clone https://github.com/void-linux/void-packages.git
158cd void-packages/
159./xbps-src binary-bootstrap
160@endcode
161
162*fiss* is not a official package yet, as it's too unstable to include, but you can
163add my void-packages as remote and compile.
164
165@code
166git remote add fiss https://github.com/friedelschoen/void-packages.git
167git pull fiss fiss
168./xbps-src pkg fiss
169xi fiss # if xtools is installed
170sudo xbps-install -R hostdir/binpkgs fiss # if xtools is not installed
171@endcode
172
173@title convert-runit Convert runit services
174
175The very most runit-service should work with fsvc but some not very efficient, thats why converting them is handy.
176Because runit (and fiss) only execute the _./run_ script, these scripts _can_ be pretty bulky.
177
178
179All services installed by *xbps*, thus available in [*void-packages*](https://github.com/void-linux/void-packages.git) follow
180some unwritten rules (unwritten as I haven't found them yet but services tent to follow some similarities).
181
182Services tent to follow this structure:
183
184@code
185#!/bin/sh (1)
186
187[ -r ./conf ] && . .conf (2)
188exec chpst -u user:group service -p $PORT $OPTS (3)
189@endcode
190
191(1) The _./run_-file always is a shell-executable, which executes the actual service.
192
193(2) If _./conf_ exist in the service-directory, it is sourced.
194
195(3) *chpst* is executed with some parameters like _-u_ which executes as user. *chpst* then executes service with modified state and
196predefined parameters from _./conf_.
197
198This is a foreground service, it means that the executable does not exit til the service is stopped. If the executable exits,
199you can expect the service to be down.~
200*fiss* also includes a stripped-down version of *chpst* for compability use, *fiss* includes a basic state management.
201
202You can extract the chpst-part to _./user_ and _./env_ (see below).
203
204If you executable has static parameters, thus no _./conf_ and no environment-variables, you can also pass the parameters in _./params_
205and sym-link the executable directly to _./run_.
206
207Void Linux packages always comes with a symbolic link _./supervise_ to _/run/runit/supervise.<service>_,
208which is meant for read-only systems running runit (expecting _/run/_ to be a temporary filesystem). If you are running a writable system,
209you can remove the link and *fiss* will create a directory. If you are running a read-only system you can either create
210the directory _/run/runit/_ and don't have to mess with runit-services or at an other location and sym-link the supervise-directories
211by yourself.
212
213
214If your _./run_ execute looks like the following, stressing the *pause*...
215
216@code
217#!/bin/sh
218
219service -p 990 start
220exec chpst -b service pause
221@endcode
222
223... and you _./finish_ like that...
224
225@code
226#!/bin/sh
227
228service stop
229@endcode
230
231... it's a runit-_background_ service which should be converted to a fiss-service.
232The service executable exits immediately, the actual service is running in the background.
233
234*pause* is a runit-hack, a program which just suspends until it is signaled by runit. It blocks a process-slot and
235the kernel still needs to care about it. *fiss* handles background-services different by calling _./start_ and _./stop_.
236
237You can safely remove the last exec line and rename _./run_ to _./start_ and _./finish_ to _./stop_ and it should work.
238
239@title getting-started Getting Started
240
241*fiss* does not parse any configuration file, everything is configured through
242different files inside for example /etc/service.d.
243
244Following files are executed by finit:
245
246@list
247_/usr/share/fiss/start_~
248This is the entry point of your system (similar to _/etc/runit/1_). By default
249this script sources files in unix-order inside _/etc/start.d/*.sh_.
250
251_/etc/service.d/*_~
252In this directory the services are stored, underneath is descripted how a
253service is constructed. The utility fsvs is written to supervise a service-
254directory without issuing start and stop mechanisms.
255
256_/usr/share/fiss/stop_~
257This is the ending point of your system-lifetime (similar to _/etc/runit/3_). By
258default this script sources file in unix-order inside _/etc/stop.d/*.sh_.
259@endlist
260
261*zzz* is a utility shipped with *fiss* to suspend your system, following files are
262executed by *zzz*.
263@list
264_/usr/share/fiss/suspend_~
265This file is executed before suspending, by default this script sources
266files in unix-order inside _/etc/zzz.d/suspend/*.sh_.
267
268_/usr/share/fiss/resume_~
269This file is executed after suspending (thus before resuming), by default this script sources
270files in unix-order inside _/etc/zzz.d/resume/*.sh_.
271@endlist
272
273@title service How to create a service?
274
275Services are usually placed into _/etc/service.d_, a services is a long-running
276executable like for example sshd, which should be running the whole lifetime of
277your system. Sadly do some services terminate before your system halts because
278of an error or signaling, this is where *fiss* plays its role.
279
280@list
281_./run_~
282Usually your service runs in the foreground, in this case you can create a run
283executable, either linked to the actual binary or as a script that executes
284the service. run is meant to be running the whole time in the foreground and
285must not daemonize itself into the background as *fiss* would restart it.
286@code
287#!/bin/sh
288
289[ -r ./conf ] && . ./conf
290
291exec myservice $ARGS
292@endcode
293This example sources conf in the service-directory if present and executes
294myservice with _$ARGS_.
295
296_./start_~
297If your services cannot be run in the foreground, you should execute link it
298to start, start is a short-running executable, if start exits it is considered
299as running. To supervise your services, it's handy to provide a pid-file
300inside your service as some services provide print its process-id to the
301console. If no pid-file is found you must implement a stop file.
302@code
303#!/bin/sh
304
305myserver --print-pid > ./pid
306@endcode
307
308_./pid_~
309This is a plain-text file containing just the PID of the service in decimal.
310
311_./stop_~
312This script is meant to stop the service, if this file exits the service is
313considered inactive. This file must not coexist with pid.
314@code
315#!/bin/sh
316
317myserver2 --stop
318@endcode
319
320_./depends_~
321This file contains newline-demilitered service-names which are dependencies of
322the service. dependencies are started before the service will be started and
323stopped if no enabled and no other service depend on it. Dependencies are just
324started, no consideration will be done that the dependency is actually active.
325
326@code
327dbus
328networking
329@endcode
330
331_./setup_~
332If this file is present and executable, it will be executed before run or
333start, it is meant for example to create files or directories.
334@code
335#!/bin/sh
336
337mkdir /var/myserver
338@endcode
339
340_./finish_~
341If this file is present and executable, it will be executed after run has
342exited or after stop was executed. This is meant to remove unnessasary files
343or directories.
344
345@code
346#!/bin/sh
347
348rm -rf /var/myserver
349@endcode
350
351_./log_~
352If this file is present, *fiss* will write the stdout and stderr of run to it.
353This will be done without any modifications.
354
355_./log/_ service~
356If this directory is present and a valid service-directory, stdout and stderr
357of your service will be redirected to the run of the log-service. This is done
358with a internal pipe, thus no data will be lost of either services failes.
359
360_./no-log_~
361If this file is present, no logging will be done at all. This is meant for
362very verbose services, which would overflout the system.~
363If _log_, _log/_ or _no-log_ is not present, the output of will be redirected to
364/run/fiss/log/<service>.
365
366_./up-<runlevel>_~
367If this file is present, the services will be started automatically and
368restarted if this services dies. On other systems, this is called 'enabling'
369a service.
370
371_./once-<runlevel>_~
372If this file is present, the services will be started automatically but not
373restarted if this services dies.
374@endlist
375
376To be a valid service, _run_, _start_ or _depends_ must be present. If only depends is
377present, this service is a dummy service thus no actual action will be taken but
378starting and stopping dependencies.
379
380_start_, _stop_, _setup_ and _finish_ are executed as the same user as *fsvs* or *finit* is
381started, thus root in the most cased. _user_, _env_, _params_ are not read when
382handling a background-service. Every file will be executed in the services
383directory, reading a file like './conf' will be read out of the service
384directory.