Start splitting up the README into separate files

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>

doc/plugins.md

@@ -0,0 +1,145 @@
+Hooks, Callbacks & Plugins
+==========================
+
+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.
+
+
+Plugins
+-------
+
+For your convenience a set of *optional* plugins are available:
+
+* *alsa-utils.so*: Restore and save ALSA sound settings on
+  startup/shutdown.  _Optional plugin._
+
+* *bootmisc.so*: Setup necessary files and system directories for, e.g.,
+  UTMP (tracks logins at boot).  This plugin is central to get a working
+  system and runs at `HOOK_BASEFS_UP`.  The `/var`, `/run`, and `/dev`
+  file systems must be writable for this plugin to work.
+
+  Note: On an embedded system both `/var` and `/run` can be `tmpfs` RAM
+  disks and `/dev` is usually a `devtmpfs`.  This must be defined in the
+  `/etc/fstab` file and in the Linux kernel config.
+
+* *dbus.so*: Setup and start system message bus, D-Bus, at boot.
+  _Optional plugin._
+
+* *echo.so*: RFC 862 plugin.  Start as inetd service, like time below.
+
+* *chargen.so*: RFC 864 plugin.  Start as inetd service, like time below.
+
+* *daytime.so*: RFC 867 plugin.  Start as inetd service, like time below.
+
+* *discard.so*: RFC 863 plugin.  Start as inetd service, like time below.
+
+* *hwclock.so*: Restore and save system clock from/to RTC on
+  startup/shutdown.
+
+* *initctl.so*: Extends finit with a traditional `initctl` functionality.
+
+* *lost.so*: Very simple `HOOK_SVC_LOST` example.  Logs process ID and
+  name to syslog.  _Optional plugin._
+
+* *netlink.so*: Listens to Linux kernel Netlink events for gateway and
+  interfaces.  These events are then sent to the Finit service monitor
+  for services that may want to be SIGHUP'ed on new default route or
+  interfaces going up/down.
+
+* *resolvconf.so*: Setup necessary files for `resolvconf` at startup.
+  _Optional plugin._
+
+* *time.so*: RFC 868 (rdate) plugin.  Start as inetd service.  Useful
+  for testing inetd filtering — BusyBox has an rdate (TCP) client.
+
+* *tty.so*: Watches `/dev`, using inotify, for new device nodes (TTY's)
+  to start/stop getty consoles on them on demand.  Useful when plugging
+  in a usb2serial converter to login to your embedded device.
+
+* *urandom.so*: Setup random seed at startup.
+
+* *x11-common.so*: Setup necessary files for X-Window.  _Optional plugin._
+
+Usually you want to hook into the boot process once, simple hook plugins
+like `bootmisc.so` are great for that purpose.  They are called at each
+hook point in the boot process, useful to insert some pre-bootstrap
+mechanisms, like generating configuration files, restoring HW device
+state, etc.  Available hook points are:
+
+
+Hooks
+-----
+
+### Bootstrap Hooks
+
+* `HOOK_ROOTFS_UP`: When `finit.conf` has been read and `/` has is
+  mounted — very early
+
+* `HOOK_BASEFS_UP`: All of `/etc/fstab` is mounted, swap is available
+  and default init signals are setup
+
+* `HOOK_NETWORK_UP`: System bootstrap, runlevel S, has completed and
+  networking is up (`lo` is up and the `network` script has run)
+
+* `HOOK_SVC_UP`: All services in the active runlevel has been launched
+
+* `HOOK_SYSTEM_UP`: All services *and* everything in `/etc/finit.d`
+  has been launched
+
+### Runtime Hooks
+
+* `HOOK_SVC_RECONF`: Called when the user has changed something in the
+  `/etc/finit.d` directory and issued `SIGHUP`.  The hook is called when
+  all modified/removed services have been stopped.  When the hook has
+  completed, Finit continues to start all modified and new services.
+
+* `HOOK_SVC_LOST`: Called when a process is lost.  When reconfiguring
+  services at runtime this hook may be called a lot.  However, it may be
+  a quite useful hook to monitor a system post bootstrap when no, or
+  few, services are expected to exit.  A default plugin `lost.so` is
+  available in the `plugins/` subdirectory as an example.
+
+  **NOTE:** This hook callback gets the lost PID as argument.
+
+* `HOOK_SVC_START`: Like `HOOK_SVC_LOST`, but called when a process is
+  started.  Same caveats apply.
+
+  **NOTE:** This hook callback gets the new PID as argument.
+
+* `HOOK_RUNLEVEL_CHANGE`: Called when the user has issued a runlevel
+  change.  The hook is called when services not matching the new
+  runlevel have been been stopped.  When the hook has completed, Finit
+  continues to start all services in the new runlevel.
+
+### Shutdown Hooks
+
+* `HOOK_SHUTDOWN`: Called at shutdown/reboot, right before all
+  services are sent `SIGTERM`
+
+Plugins like `initctl.so` and `tty.so` extend finit by acting on events,
+they are called I/O plugins and are called from the finit main loop when
+`poll()` detects an event.  See the source code for `plugins/*.c` for
+more help and ideas.
+
+
+Callbacks
+---------
+
+Callback plugins are called by finit right before a process is started,
+or restarted if it exits.  The callback runs as a separate process and
+receives a pointer to the `svc_t` of the service, with all command line
+parameters free to modify as needed.
+
+All the callback needs to do is respond with one of: `SVC_STOP (0)`
+tells Finit to *not* start the service, `SVC_START (1)` to start the
+service, or `SVC_RELOAD (2)` to have finit signal the process with
+`SIGHUP`.
+
+
+<!--
+  -- Local Variables:
+  -- mode: markdown
+  -- End:
+  -->