wt/finit
1
0 Fork 0
mirror of https://github.com/troglobit/finit.git synced 2026-10-14 10:19:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README to Markdown syntax.

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+175 -168
View File
@@ -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 <DEV>`
check <DEV>
Run fsck on a file system before mounting it
module <MODULE>
* `module <MODULE>`
Load a kernel module, with optional arguments
network <PATH>
* `network <PATH>`
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
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 <PATH>
* `runparts <PATH>`
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
path is prepended to file if the file is not found or an absolute
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
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 <DEV>
* `console <DEV>`
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.