diff options
| -rw-r--r-- | MANUAL | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/MANUAL b/MANUAL new file mode 100644 index 0000000..93a532c --- /dev/null +++ b/MANUAL @@ -0,0 +1,104 @@ + A RVNIT MANUAL + 2022-01-27 + + Overview + +Rvnit is a small but flexible init-system and supervision daemon. + +There are three main applications it is designed for: +- As init for a Linux machine +- As init for a Linux container +- As unprivileged supervision daemon + +Rvnit is configured by a directory of scripts, defaulting to /etc/rvnit. + +In this directory, rvnit looks into executable files (called tasks) +that start with two digits and do not end with ~. + +rvnit distinguishes between several kinds of tasks identfied by the +third letter of the file name: +- 'S': startup scripts +- 'K': shutdown scripts +- 'D': daemons +- 'L': loggers +- 'G': global loggers +- 'E': error handlers + + Modes of operation + +The lifecycle of a machine/container/session using rvnit consists of +three phases. + +First, the system is *booted*, by spawning tasks in order from 00 to 99. +This means that for each level 00 to 99: +- startup scripts are run +- daemons are run +- loggers are run, and connected to daemons +- global loggers are run, and connected to the global log +- if a startup script failed, the first error handler of the same or + lower level is run, then the startup script is run again; + if the error handler returns 111, the startup script is skipped. +- the level is finished when all startup scripts ran successfully. + +After reaching level 99, the system is in the second phase, the *uptime*. +During uptime, rvnit +- respawns daemons that have exited, but no more than once a second +- responds to commands sent by rvnitctl +- waits for a SIGINT, SIGTERM (containers and non-pid 1 only), Ctrl-Alt-Delete, + or rvnitctl command to start the shutdown + +*Shutdown* progresses in levels again, this time from 99 to 00 backwards. +For each level: +- shutdown scripts are run +- daemons are stopped, first by SIGTERM and after 7s by SIGKILL +- loggers are stopped by closing their stdin + +Upon reaching level 0, rvnit will poweroff or reboot the machine/container. + + Controlling rvnit with rvnitctl + +During the uptime of the system, you can remote control rvnit using +the tool rvnitctl. + +Usage: rvnitctl [COMMAND] [SERVICE] + +Only the first letter of command is relevant, but mnemonic: + +- status: show a list of daemons, loggers, and global logger, and + their state, pid, uptime and last exit status. +- up: start SERVICE +- down: stop SERVICE +- p: send signal SIGSTOP to SERVICE +- c: send signal SIGCONT to SERVICE +- h: send signal SIGHUP to SERVICE +- a: send signal SIGALRM to SERVICE +- i: send signal SIGINT to SERVICE +- q: send signal SIGQUIT to SERVICE +- 1: send signal SIGUSR1 to SERVICE +- 2: send signal SIGUSR2 to SERVICE +- t: send signal SIGTERM to SERVICE +- k: send signal SIGKILL to SERVICE +- rescan: re-read /etc/rvnit, start added daemons, stop removed daemons +- Shutdown: shutdown (poweroff) the system +- Reboot: reboot the system + + Logging with rvnit + +Rvnit distinguishes two kinds of logging mechanism: +- Loggers are associated to one daemon and get the daemon stdout as stdin +- The global logger gets logs from all tasks that don't have a custom logger, + as well as rvnit's log output + +Rvnit keeps a global log pipe and associates logged lines with their +origin pid and time. This pipe is filled before the global logger is +started, so the global logger will get all messages since boot time. + +Rvnit keeps the pipes between daemons and loggers open and can respawn +daemons and loggers without loss of data. + + Rvnit as init for Linux + +Rvnit is self-contained and can be booted directly as pid 1. +It will mount /dev and /run when required, everything else +is left to startup scripts. +When receiving Ctrl-Alt-Delete, rvnit triggers an orderly reboot. |