From 588901ee4c98b6263f9d7fe7ad222e8b78171172 Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Wed, 26 Nov 2014 15:56:50 +0100 Subject: [PATCH] Update README to Markdown syntax. Signed-off-by: Joachim Nilsson --- README.md | 343 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 175 insertions(+), 168 deletions(-) diff --git a/README.md b/README.md index 7b494209..316ba84b 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,43 @@ -============================================================================== - Finit | Fast Init Replacement -============================================================================== -|cistatus| -|covstat| +README +====== +[![Build Status](https://travis-ci.org/troglobit/finit.png?branch=master)](https://travis-ci.org/troglobit/finit) +[![Coverity Scan Status](https://scan.coverity.com/projects/3545/badge.svg)](https://scan.coverity.com/projects/3545) -Finit is a small `SysV init`_ replacement with `process supervision`_ -similar to that of `daemontools`_ and `runit`_. Its focus is on small -and embedded GNU/Linux systems, although fully functional on standard -server and desktop installations. It should also work on other UNIX -systems, but this has yet to be proven. +Init is the first process to run once a UNIX kernel has booted, it +always has PID 1 and is responsible for starting up the rest of the +system. Finit is a very small plugin based init with built in +[process supervision](https://en.wikipedia.org/wiki/Process_supervision) +similar to that of D.J. Bernstein's +[daemontools](http://cr.yp.to/daemontools.html) and Gerrit Pape's +[runit](http://smarden.org/runit/). Its focus is on small and embedded +GNU/Linux systems, although fully functional on standard server and +desktop installations. -Finit is fast because it starts services in parallel, it then supervises -and automatically restarts them if they fail. This can be extended upon -with custom callbacks for all services, hooks into the boot process, or -plugins to extend the functionality and adapt Finit to your needs. +Finit is fast because it is "scripted" with C and starts services in +parallel. Services are supervised and automatically restarted if they +fail. Services can have callbacks that are called before a service is +(re)started. For instance, before attempting to start a heavily +resource intensive service like IPsec or OpenVPN, a callback can check +if the outbound interface is up and has an IP address, or just check if +the service is disabled -- much like what a SysV init start script +usually does. + +To extend finit with new functionality, hooks can be added at certain +points in the boot process that execute in sequence, which is useful for +certain satisfying preconditions or for synchronization purposes. One +can also create plugins to functionality to suit your own needs, the +initctl compatibility plugin that comes with finit is one such plugin. Finit is not only fast, it's arguably one of the easiest to get started with. A complete system can be booted with one simple configuration -file, ``/etc/finit.conf``, see below for syntax. +file, `/etc/finit.conf`, see below for syntax. Features -------- **Process Supervision** -Start, monitor and restarting services if they fail. +Start, monitor and restart services if they fail. **Runlevels** Finit supports standard runlevels if you want, but you don't need them @@ -33,7 +46,7 @@ for simple installations. **Plugins** Extend and modify finit behavior. See examples in plugins/ directory. Plugin capabilities: - + * Service callbacks — modify service arguments, run/restart/stop * Task/Run callbacks — a one-shot commands, executed in sequence * Hooks — hook into the boot at predefined points to extend finit @@ -47,94 +60,107 @@ hook into the boot process or respond to various I/O. /etc/finit.conf --------------- -Contrary to most script based init alternatives (`SysV init`_, upstart_, -systemd_, OpenRC_ and the likes) finit instead reads its configuration -from ``/etc/finit.conf``. Below is a brief list, see the source code -for the full list: +Contrary to most other script based init alternatives +([SysV init](https://en.wikipedia.org/wiki/Init), +[upstart](http://upstart.ubuntu.com/), +[systemd](http://www.freedesktop.org/wiki/Software/systemd/), +[OpenRC](http://www.gentoo.org/proj/en/base/openrc/) and the likes) +finit reads its configuration from `/etc/finit.conf`. Syntax: + +* `check ` -check Run fsck on a file system before mounting it -module +* `module ` + Load a kernel module, with optional arguments -network +* `network ` + Script or program to bring up networking, with optional arguments -runlevel +* `runlevel ` + N is the runlevel number 1-9, where 6 is reserved for reboot -run [RUN_LVLS] /path/to/cmd ARGS -- Optional description +* `run [RUN_LVLS] /path/to/cmd ARGS -- Optional description` + One-shot command to run in sequence when entering a runlevel, with optional arguments and description. This command is guaranteed to be completed before running the next command. -task [RUN_LVLS] /path/to/cmd ARGS -- Optional description +* `task [RUN_LVLS] /path/to/cmd ARGS -- Optional description` + One-shot like 'run', but starts in parallel with the next command -service [RUN_LVLS] /path/to/daemon ARGS -- Optional description +* `service [RUN_LVLS] /path/to/daemon ARGS -- Optional description` + Service, or daemon, to be monitored and automatically restarted if it exits prematurely. Please note that you often need to provide a --foreground or --no-background argument to most daemons to prevent them from forking off to the background. -runparts +* `runparts ` + Call run-parts(8) on a directory other than default ``/etc/finit.d`` -include +* `include ` + Include another configuration file, ``/etc/finit.d``, or runparts path is prepended to file if the file is not found or an absolute path is not given -tty [RUN_LVLS] +* `tty [RUN_LVLS] ` + Start a getty on the given TTY device, in the given runlevels. When - no tty setting is given in ``finit.conf``, or if /bin/sh is given as + no tty setting is given in `finit.conf`, or if `/bin/sh` is given as argument instead of a device path, a single shell is started on the default console. Useful for really bare-bones systems -console +* `console ` + Some embedded systems have a dedicated console port. This command tells finit to not start getty, but instead print a friendly message and wait for the user to activate the console with a key press before starting getty. -When running ``make install`` no default ``/etc/finit.conf`` will be +When running `make install` no default `/etc/finit.conf` will be provided since the system requirements differ too much. Try out the -Debian 6.0 example ``/usr/share/doc/finit/finit.conf`` configuration -that is capable of service monitoring SSH, sysklogd, gdm and a console -getty! +Debian 6.0 example `/usr/share/doc/finit/finit.conf` configuration that +is capable of service monitoring SSH, sysklogd, gdm and a console getty! /etc/finit.d ------------ At the end of the boot, when networking and all services are up, finit -calls its built-in run-parts(8) on the ``/etc/finit.d/`` directory, if -it exists. Similar to how the ``/ec/rc.local`` file works in most other +calls its built-in run-parts(8) on the `/etc/finit.d/` directory, if +it exists. Similar to how the `/ec/rc.local` file works in most other init daemons, only finit runs a directory of scripts. This replaces the -earlier support for a ``/usr/sbin/services.sh`` script in the original +earlier support for a `/usr/sbin/services.sh` script in the original finit. Runlevels --------- -Support for runlevels_ is included in Finit from v1.8. By default all -services, tasks, run commands and TTYs listed without a set of runlevels -get a default set [234] assigned. The default runlevel after boot is 2. +Basic support for [runlevels](http://en.wikipedia.org/wiki/Runlevel) is +included in Finit from v1.8. By default all services, tasks, run +commands and TTYs listed without a set of runlevels get a default set +`[234]` assigned. The default runlevel after boot is 2. -To specify an allowed set of runlevels for a service, run command, task, -or tty, add [NNN] to it in finit.conf, like this:: +To specify an allowed set of runlevels for a `service`, `run` command, `task`, +or `tty`, add `[NNN]` to it in your `finit.conf`, like this: - run [S] /etc/init.d/acpid start -- Starting ACPI Daemon - task [S] /etc/init.d/kbd start -- Preparing console - service [S12345] /sbin/klogd -n -x -- Kernel log daemon - tty [12345] /dev/tty1 - tty [2] /dev/tty2 - tty [2] /dev/tty3 - tty [2] /dev/tty4 - tty [2] /dev/tty5 - tty [2] /dev/tty6 + run [S] /etc/init.d/acpid start -- Starting ACPI Daemon + task [S] /etc/init.d/kbd start -- Preparing console + service [S12345] /sbin/klogd -n -x -- Kernel log daemon + tty [12345] /dev/tty1 + tty [2] /dev/tty2 + tty [2] /dev/tty3 + tty [2] /dev/tty4 + tty [2] /dev/tty5 + tty [2] /dev/tty6 In this example acpid is started once at bootstrap using a conventional SysV init script. Here the run command was used, meaning the following @@ -145,10 +171,10 @@ in the order listed and subsequent commands are not started until a run command has completed. Existing finit.conf files that lack runlevel setting will get a default -runlevel assigned, [234]. +runlevel assigned, `[234]`. Switching between runlevels can be done by calling init with a single -argument, e.g., 'init 5' switches to runlevel 5. +argument, e.g., `init 5` switches to runlevel 5. Hooks, Callbacks & Plugins @@ -158,43 +184,37 @@ Finit provides only the bare necessities for starting and supervising processes, with an emphasis on *bare* -- for your convenience it does however come with support for hooks, service callbacks and plugins that can used to extend finit with. For your convenience a set of predefined -plugins are available:: +plugins are available: -alsa-utils.so (HOOK) - Restore and save ALSA sound settings on startup/shutdown. +- *alsa-utils.so*: Restore and save ALSA sound settings on + startup/shutdown. -bootmisc.so (HOOK) - Setup necessary files for UTMP, tracking logins at boot. +- *bootmisc.so*: Setup necessary files for UTMP, tracking logins + at boot. -dbus.so (HOOK) - Setup and start system message bus, D-Bus, at boot. +- *dbus.so*: Setup and start system message bus, D-Bus, at boot. -hwclock.so (HOOK) - Restore and save system clock from/to RTC on startup/shutdown. +- *hwclock.so*: Restore and save system clock from/to RTC on + startup/shutdown. -initctl.so (PLUGIN) - Extends finit with a traditional initctl functionality. +- *initctl.so*: Extends finit with a traditional initctl functionality. -resolvconf.so (HOOK) - Setup necessary files for resolvconf at startup. +- *resolvconf.so*: Setup necessary files for resolvconf at startup. -tty.so (I/O PLUGIN) - Watches /dev, using inotify, for new device nodes (TTY's) to +- *tty.so*: Watches /dev, using inotify, for new device nodes (TTY's) to start/stop getty consoles on them on demand. -urandom.so (HOOK) - Setup random seed at startup. +- *urandom.so*: Setup random seed at startup. -x11-common.so (HOOK) - Setup necessary files for X-Window. +- *x11-common.so*: Setup necessary files for X-Window. These are only hooks and plugins to extend finit, but it is also possible to extend finit with a callback for each service. Such a callback would be called right before the process is started, or -restarted if it exits. Callback gets a pointer to the ``svc_t`` +restarted if it exits. Callback gets a pointer to the `svc_t` of the service, with all command line parameters free to modify if needed. All the callback needs to do is repond with one of: -``SVC_STOP(0)``, ``SVC_START(1)``, or ``SVC_RELOAD(2)`` -- the +`SVC_STOP(0)`, `SVC_START(1)`, or `SVC_RELOAD(2)` -- the latter of which means finit will send SIGHUP to the process. @@ -202,7 +222,7 @@ Rebooting and Halting --------------------- Finit handles SIGUSR1 and SIGUSR2 for reboot and halt, and listens to -``/dev/initctl`` so standard Linux reboot and halt commands should also +`/dev/initctl` so standard Linux reboot and halt commands should also work. @@ -217,129 +237,116 @@ alter the behavior of finit. The following environment variables are checked by the makefiles and control what is built and where resulting binaries are installed. -**ROOTDIR=** - Top directory for building complete system, used in pretty printing +- `ROOTDIR=`: Top directory for building complete system, used in pretty + printing. -**VERSION=** - Defaults to the currently released version of finit, e.g., 1.3 but can - be overridden by packages to add a suffix or completely alter the version. +- `VERSION=`: Defaults to the currently released version of finit, + e.g., 1.3 but can be overridden by packagers using this variable to + add a suffix or completely alter the version. -**CFLAGS=** - Standard CFLAGS are inherited from the build environment. +- `CFLAGS=`: Standard `CFLAGS` are inherited from the build environment. -**CPPFLAGS=** - Standard CPPFLAGS are inherited from the build environment. +- `CPPFLAGS=`: Standard `CPPFLAGS` are inherited from the build + environment. -**LDFLAGS=** - Standard LDFLAGS are inherited from the build environment. +- `LDFLAGS=`: Standard `LDFLAGS` are inherited from the build + environment. -**LDLIBS=** - Standard LIBLIBS are inherited from the build environment. +- `LDLIBS=`: Standard `LIBLIBS` are inherited from the build environment. -**prefix=** - Base prefix path for all files, except ``sbinbdir`` and ``sysconfdir``. - Used in concert with the ``DESTDIR`` variable. Defaults to ``/usr`` +- `prefix=`: Base prefix path for all files, except `sbinbdir` and + `sysconfdir`. Used in concert with the `DESTDIR` variable. -**sbindir=** - Path to where resulting binaries should install to. Used in concert - with the ``DESTDIR`` variable. Defaults to ``/sbin`` + Defaults to `/usr`. -**sysconfdir=** - Path to where finit configuration files should install to. Used in - concert with the ``DESTDIR`` variable. Defaults to ``/etc``, but is - currently unused. +- `sbindir=`: Path to where resulting binaries should install to. Used + in concert with the `DESTDIR` variable. -**PLUGINS=** - List of stock finit plugins to build and install. + Defaults to `/sbin`. -**plugindir=** - Absolute path to where finit should look for dynamically loadable plugins - at runtime. At installation prepended by ``DESTDIR`` and ``prefix``. - Defaults to ``/lib/finit/plugins`` +- `sysconfdir=`: Path to where finit configuration files should install + to. Used in concert with the `DESTDIR` variable. -**DESTDIR=** - Used by packagers and distributions when building a relocatable - bundle of files. Always prepended to the ``prefix`` destination - directory. + Defaults to `/etc`, but is currently unused. -**Example**:: +- `PLUGINS=`: List of stock finit plugins to build and install. - $ tar xfJ finit-1.3.tar.xz - $ PLUGINS="initctl.so hwclock.so" DESTDIR=/tmp/finit/dst \ - make -C finit-1.3/ clean install - make: Entering directory `/home/troglobit/finit-1.3' - CC finit.o - CC conf.o - CC helpers.o - CC sig.o - CC svc.o - CC plugin.o - CC strlcpy.o - LINK finit - CC plugins/initctl.o - PLUGIN plugins/initctl.so - CC plugins/hwclock.o - PLUGIN plugins/hwclock.so - INSTALL /tmp/finit/dst/sbin/finit - INSTALL /tmp/finit/dst/lib/finit/plugins/initctl.so - INSTALL /tmp/finit/dst/lib/finit/plugins/hwclock.so - make: Leaving directory `/home/troglobit/finit-1.3' +- `plugindir=`: Absolute path to where finit should look for dynamically + loadable plugins at runtime. At installation prepended by `DESTDIR` + and `prefix`. -In this example the `finit-1.3.tar.xz`_ archive is unpacked to the -user's home directory, built and installed to a temporary staging -directory. The environment variables ``DESTDIR`` and ``PLUGINS`` are -changed to suit this particular build. + Defaults to `/lib/finit/plugins`. + +- `DESTDIR=`: Used by packagers and distributions when building a + relocatable bundle of files. Always prepended to the `prefix` + destination directory. + +**Example**: + + $ tar xfJ finit-1.3.tar.xz + $ PLUGINS="initctl.so hwclock.so" DESTDIR=/tmp/finit/dst \ + make -C finit-1.3/ clean install + make: Entering directory `/home/troglobit/finit-1.3' + CC finit.o + CC conf.o + CC helpers.o + CC sig.o + CC svc.o + CC plugin.o + CC strlcpy.o + LINK finit + CC plugins/initctl.o + PLUGIN plugins/initctl.so + CC plugins/hwclock.o + PLUGIN plugins/hwclock.so + INSTALL /tmp/finit/dst/sbin/finit + INSTALL /tmp/finit/dst/lib/finit/plugins/initctl.so + INSTALL /tmp/finit/dst/lib/finit/plugins/hwclock.so + make: Leaving directory `/home/troglobit/finit-1.3' + +In this example the +[finit-1.3.tar.xz](ftp://troglobit.com/finit/finit-1.3.tar.xz) +archive is unpacked to the user's home directory, built and +installed to a temporary staging directory. The environment +variables `DESTDIR` and `PLUGINS` are changed to suit this +particular build. Running ------- The default install does not setup finit as the system default -``/sbin/init``, neither does it setup an initial ``/etc/finit.conf``. +`/sbin/init`, neither does it setup an initial `/etc/finit.conf`. It is assumed that users of finit are competent enough to either setup -finit as their default ``/sbin/init`` or alter their respective Grub, +finit as their default `/sbin/init` or alter their respective Grub, LOADLIN, LILO, U-Boot/Barebox or RedBoot boot loader configuration to -give the kernel the following extra command line:: +give the kernel the following extra command line: - init=/sbin/finit + init=/sbin/finit Debugging --------- -Add ``finit_debug``, or ``--debug``, to the kernel command line to +Add `finit_debug`, or `--debug`, to the kernel command line to enable trace messages. A console getty is always started, see the file -``finit.h`` for more useful compile-time tweaks:: +`finit.h` for more useful compile-time tweaks: - init=/sbin/finit --debug + init=/sbin/finit --debug -Contact -------- +Credits & Contact +----------------- -This is the continuation of the `original finit`_ by Claudio Matsuoka, -which in turn was reverse engineered from syscalls of the `EeePC -fastinit`_ -- "gaps filled with frog DNA ...". It is currently being -developed and maintained by `Joachim Nilsson`_ at `GitHub`_. Please -file bug reports, clone it, or send pull requests for bug fixes and -proposed extensions. +This is the continuation of the [original finit](http://helllabs.org/finit/) +by [Claudio Matsuoka](https://github.com/cmatsuoka), which in turn was +reverse engineered from syscalls of the +[EeePC fastinit](http://wiki.eeeuser.com/boot_process:the_boot_process) +-- "gaps filled with frog DNA ...". -.. _`SysV init`: https://en.wikipedia.org/wiki/Init -.. _`Joachim Nilsson`: http://troglobit.com -.. _GitHub: http://github.com/troglobit/finit -.. _`process supervision`: https://en.wikipedia.org/wiki/Process_supervision -.. _`daemontools`: http://cr.yp.to/daemontools.html -.. _`runit`: http://smarden.org/runit/ -.. _`original finit`: http://helllabs.org/finit/ -.. _`EeePC fastinit`: http://wiki.eeeuser.com/boot_process:the_boot_process -.. _upstart: http://upstart.ubuntu.com/ -.. _runlevels: http://en.wikipedia.org/wiki/Runlevel -.. _systemd: http://www.freedesktop.org/wiki/Software/systemd/ -.. _OpenRC: http://www.gentoo.org/proj/en/base/openrc/ -.. _`finit-1.3.tar.xz`: ftp://troglobit.com/finit/finit-1.3.tar.xz -.. |cistatus| image:: https://travis-ci.org/troglobit/finit.png?branch=master - :target: https://travis-ci.org/troglobit/finit -.. |covstat| image:: https://scan.coverity.com/projects/3545/badge.svg - :target: https://scan.coverity.com/projects/3545 +Finit is currently being developed and maintained by +[Joachim Nilsson](http://troglobit.com) at +[GitHub](http://github.com/troglobit/finit). Please file bug reports, clone it, +or send pull requests for bug fixes and proposed extensions.