Update README to Markdown syntax.

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>
This commit is contained in:
Joachim Nilsson committed 2014-11-26 15:56:50 +01:00
1 parent e30d2aae19
commit 588901ee4c
1 file changed
+175 -168
+175 -168
View File
@@ -1,30 +1,43 @@
============================================================================== README
Finit | Fast Init Replacement ======
============================================================================== [![Build Status](https://travis-ci.org/troglobit/finit.png?branch=master)](https://travis-ci.org/troglobit/finit)
|cistatus| [![Coverity Scan Status](https://scan.coverity.com/projects/3545/badge.svg)](https://scan.coverity.com/projects/3545)
|covstat|
Finit is a small `SysV init`_ replacement with `process supervision`_ Init is the first process to run once a UNIX kernel has booted, it
similar to that of `daemontools`_ and `runit`_. Its focus is on small always has PID 1 and is responsible for starting up the rest of the
and embedded GNU/Linux systems, although fully functional on standard system. Finit is a very small plugin based init with built in
server and desktop installations. It should also work on other UNIX [process supervision](https://en.wikipedia.org/wiki/Process_supervision)
systems, but this has yet to be proven. 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 Finit is fast because it is "scripted" with C and starts services in
and automatically restarts them if they fail. This can be extended upon parallel. Services are supervised and automatically restarted if they
with custom callbacks for all services, hooks into the boot process, or fail. Services can have callbacks that are called before a service is
plugins to extend the functionality and adapt Finit to your needs. (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 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 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 Features
-------- --------
**Process Supervision** **Process Supervision**
Start, monitor and restarting services if they fail. Start, monitor and restart services if they fail.
**Runlevels** **Runlevels**
Finit supports standard runlevels if you want, but you don't need them Finit supports standard runlevels if you want, but you don't need them
@@ -33,7 +46,7 @@ for simple installations.
**Plugins** **Plugins**
Extend and modify finit behavior. See examples in plugins/ directory. Extend and modify finit behavior. See examples in plugins/ directory.
Plugin capabilities: Plugin capabilities:
* Service callbacks — modify service arguments, run/restart/stop * Service callbacks — modify service arguments, run/restart/stop
* Task/Run callbacks — a one-shot commands, executed in sequence * Task/Run callbacks — a one-shot commands, executed in sequence
* Hooks — hook into the boot at predefined points to extend finit * 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 /etc/finit.conf
--------------- ---------------
Contrary to most script based init alternatives (`SysV init`_, upstart_, Contrary to most other script based init alternatives
systemd_, OpenRC_ and the likes) finit instead reads its configuration ([SysV init](https://en.wikipedia.org/wiki/Init),
from ``/etc/finit.conf``. Below is a brief list, see the source code [upstart](http://upstart.ubuntu.com/),
for the full list: [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 <DEV>`
check <DEV>
Run fsck on a file system before mounting it Run fsck on a file system before mounting it
module <MODULE> * `module <MODULE>`
Load a kernel module, with optional arguments Load a kernel module, with optional arguments
network <PATH> * `network <PATH>`
Script or program to bring up networking, with optional arguments Script or program to bring up networking, with optional arguments
runlevel <N> * `runlevel <N>`
N is the runlevel number 1-9, where 6 is reserved for reboot 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 One-shot command to run in sequence when entering a runlevel, with
optional arguments and description. This command is guaranteed to optional arguments and description. This command is guaranteed to
be completed before running the next command. 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 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 Service, or daemon, to be monitored and automatically restarted if
it exits prematurely. Please note that you often need to provide it exits prematurely. Please note that you often need to provide
a --foreground or --no-background argument to most daemons to a --foreground or --no-background argument to most daemons to
prevent them from forking off to the background. prevent them from forking off to the background.
runparts <PATH> * `runparts <PATH>`
Call run-parts(8) on a directory other than default ``/etc/finit.d`` Call run-parts(8) on a directory other than default ``/etc/finit.d``
include <CONF> * `include <CONF>`
Include another configuration file, ``/etc/finit.d``, or runparts 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 prepended to file if the file is not found or an absolute
path is not given path is not given
tty [RUN_LVLS] <DEV | /bin/sh> * `tty [RUN_LVLS] <DEV | /bin/sh>`
Start a getty on the given TTY device, in the given runlevels. When 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 argument instead of a device path, a single shell is started on the
default console. Useful for really bare-bones systems default console. Useful for really bare-bones systems
console <DEV> * `console <DEV>`
Some embedded systems have a dedicated console port. This command Some embedded systems have a dedicated console port. This command
tells finit to not start getty, but instead print a friendly message 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 and wait for the user to activate the console with a key press before
starting getty. 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 provided since the system requirements differ too much. Try out the
Debian 6.0 example ``/usr/share/doc/finit/finit.conf`` configuration Debian 6.0 example `/usr/share/doc/finit/finit.conf` configuration that
that is capable of service monitoring SSH, sysklogd, gdm and a console is capable of service monitoring SSH, sysklogd, gdm and a console getty!
getty!
/etc/finit.d /etc/finit.d
------------ ------------
At the end of the boot, when networking and all services are up, finit 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 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 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 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. finit.
Runlevels Runlevels
--------- ---------
Support for runlevels_ is included in Finit from v1.8. By default all Basic support for [runlevels](http://en.wikipedia.org/wiki/Runlevel) is
services, tasks, run commands and TTYs listed without a set of runlevels included in Finit from v1.8. By default all services, tasks, run
get a default set [234] assigned. The default runlevel after boot is 2. 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, To specify an allowed set of runlevels for a `service`, `run` command, `task`,
or tty, add [NNN] to it in finit.conf, like this:: or `tty`, add `[NNN]` to it in your `finit.conf`, like this:
run [S] /etc/init.d/acpid start -- Starting ACPI Daemon run [S] /etc/init.d/acpid start -- Starting ACPI Daemon
task [S] /etc/init.d/kbd start -- Preparing console task [S] /etc/init.d/kbd start -- Preparing console
service [S12345] /sbin/klogd -n -x -- Kernel log daemon service [S12345] /sbin/klogd -n -x -- Kernel log daemon
tty [12345] /dev/tty1 tty [12345] /dev/tty1
tty [2] /dev/tty2 tty [2] /dev/tty2
tty [2] /dev/tty3 tty [2] /dev/tty3
tty [2] /dev/tty4 tty [2] /dev/tty4
tty [2] /dev/tty5 tty [2] /dev/tty5
tty [2] /dev/tty6 tty [2] /dev/tty6
In this example acpid is started once at bootstrap using a conventional In this example acpid is started once at bootstrap using a conventional
SysV init script. Here the run command was used, meaning the following 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. command has completed.
Existing finit.conf files that lack runlevel setting will get a default 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 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 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 processes, with an emphasis on *bare* -- for your convenience it does
however come with support for hooks, service callbacks and plugins that however come with support for hooks, service callbacks and plugins that
can used to extend finit with. For your convenience a set of predefined can used to extend finit with. For your convenience a set of predefined
plugins are available:: plugins are available:
alsa-utils.so (HOOK) - *alsa-utils.so*: Restore and save ALSA sound settings on
Restore and save ALSA sound settings on startup/shutdown. startup/shutdown.
bootmisc.so (HOOK) - *bootmisc.so*: Setup necessary files for UTMP, tracking logins
Setup necessary files for UTMP, tracking logins at boot. at boot.
dbus.so (HOOK) - *dbus.so*: Setup and start system message bus, D-Bus, at boot.
Setup and start system message bus, D-Bus, at boot.
hwclock.so (HOOK) - *hwclock.so*: Restore and save system clock from/to RTC on
Restore and save system clock from/to RTC on startup/shutdown. startup/shutdown.
initctl.so (PLUGIN) - *initctl.so*: Extends finit with a traditional initctl functionality.
Extends finit with a traditional initctl functionality.
resolvconf.so (HOOK) - *resolvconf.so*: Setup necessary files for resolvconf at startup.
Setup necessary files for resolvconf at startup.
tty.so (I/O PLUGIN) - *tty.so*: Watches /dev, using inotify, for new device nodes (TTY's) to
Watches /dev, using inotify, for new device nodes (TTY's) to
start/stop getty consoles on them on demand. start/stop getty consoles on them on demand.
urandom.so (HOOK) - *urandom.so*: Setup random seed at startup.
Setup random seed at startup.
x11-common.so (HOOK) - *x11-common.so*: Setup necessary files for X-Window.
Setup necessary files for X-Window.
These are only hooks and plugins to extend finit, but it is also 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 possible to extend finit with a callback for each service. Such a
callback would be called right before the process is started, or 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 of the service, with all command line parameters free to modify
if needed. All the callback needs to do is repond with one of: 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. 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 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. work.
@@ -217,129 +237,116 @@ alter the behavior of finit.
The following environment variables are checked by the makefiles and control The following environment variables are checked by the makefiles and control
what is built and where resulting binaries are installed. what is built and where resulting binaries are installed.
**ROOTDIR=** - `ROOTDIR=`: Top directory for building complete system, used in pretty
Top directory for building complete system, used in pretty printing printing.
**VERSION=** - `VERSION=`: Defaults to the currently released version of finit,
Defaults to the currently released version of finit, e.g., 1.3 but can e.g., 1.3 but can be overridden by packagers using this variable to
be overridden by packages to add a suffix or completely alter the version. add a suffix or completely alter the version.
**CFLAGS=** - `CFLAGS=`: Standard `CFLAGS` are inherited from the build environment.
Standard CFLAGS are inherited from the build environment.
**CPPFLAGS=** - `CPPFLAGS=`: Standard `CPPFLAGS` are inherited from the build
Standard CPPFLAGS are inherited from the build environment. environment.
**LDFLAGS=** - `LDFLAGS=`: Standard `LDFLAGS` are inherited from the build
Standard LDFLAGS are inherited from the build environment. environment.
**LDLIBS=** - `LDLIBS=`: Standard `LIBLIBS` are inherited from the build environment.
Standard LIBLIBS are inherited from the build environment.
**prefix=** - `prefix=`: Base prefix path for all files, except `sbinbdir` and
Base prefix path for all files, except ``sbinbdir`` and ``sysconfdir``. `sysconfdir`. Used in concert with the `DESTDIR` variable.
Used in concert with the ``DESTDIR`` variable. Defaults to ``/usr``
**sbindir=** Defaults to `/usr`.
Path to where resulting binaries should install to. Used in concert
with the ``DESTDIR`` variable. Defaults to ``/sbin``
**sysconfdir=** - `sbindir=`: Path to where resulting binaries should install to. Used
Path to where finit configuration files should install to. Used in in concert with the `DESTDIR` variable.
concert with the ``DESTDIR`` variable. Defaults to ``/etc``, but is
currently unused.
**PLUGINS=** Defaults to `/sbin`.
List of stock finit plugins to build and install.
**plugindir=** - `sysconfdir=`: Path to where finit configuration files should install
Absolute path to where finit should look for dynamically loadable plugins to. Used in concert with the `DESTDIR` variable.
at runtime. At installation prepended by ``DESTDIR`` and ``prefix``.
Defaults to ``/lib/finit/plugins``
**DESTDIR=** Defaults to `/etc`, but is currently unused.
Used by packagers and distributions when building a relocatable
bundle of files. Always prepended to the ``prefix`` destination
directory.
**Example**:: - `PLUGINS=`: List of stock finit plugins to build and install.
$ tar xfJ finit-1.3.tar.xz - `plugindir=`: Absolute path to where finit should look for dynamically
$ PLUGINS="initctl.so hwclock.so" DESTDIR=/tmp/finit/dst \ loadable plugins at runtime. At installation prepended by `DESTDIR`
make -C finit-1.3/ clean install and `prefix`.
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`_ archive is unpacked to the Defaults to `/lib/finit/plugins`.
user's home directory, built and installed to a temporary staging
directory. The environment variables ``DESTDIR`` and ``PLUGINS`` are - `DESTDIR=`: Used by packagers and distributions when building a
changed to suit this particular build. 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 Running
------- -------
The default install does not setup finit as the system default 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 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 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 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 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, This is the continuation of the [original finit](http://helllabs.org/finit/)
which in turn was reverse engineered from syscalls of the `EeePC by [Claudio Matsuoka](https://github.com/cmatsuoka), which in turn was
fastinit`_ -- "gaps filled with frog DNA ...". It is currently being reverse engineered from syscalls of the
developed and maintained by `Joachim Nilsson`_ at `GitHub`_. Please [EeePC fastinit](http://wiki.eeeuser.com/boot_process:the_boot_process)
file bug reports, clone it, or send pull requests for bug fixes and -- "gaps filled with frog DNA ...".
proposed extensions.
.. _`SysV init`: https://en.wikipedia.org/wiki/Init Finit is currently being developed and maintained by
.. _`Joachim Nilsson`: http://troglobit.com [Joachim Nilsson](http://troglobit.com) at
.. _GitHub: http://github.com/troglobit/finit [GitHub](http://github.com/troglobit/finit). Please file bug reports, clone it,
.. _`process supervision`: https://en.wikipedia.org/wiki/Process_supervision or send pull requests for bug fixes and proposed extensions.
.. _`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