From 1a439baf68aaf258208aa3cd50f66f0d5bdad1b5 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Tue, 22 Nov 2022 08:06:26 +0100 Subject: [PATCH] Further improve runparts/hook script docs, add limitations Issue #320 Signed-off-by: Joachim Wiberg --- doc/config.md | 33 +++++++++++++++++++++++++++------ doc/plugins.md | 5 +++-- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/doc/config.md b/doc/config.md index 27ba74f5..1284b39d 100644 --- a/doc/config.md +++ b/doc/config.md @@ -638,6 +638,33 @@ files, or scripts, in the directory are called, in alphabetic order. The scripts in this directory are executed at the very end of runlevel `S`, [bootstrap][]. +**Limitations:** + +Scripts called from `runparts`, or hook scripts (see below), are limited +in what they can do and expect from Finit: + + 1. Finit is single threaded and all scripts executed from these two + mechanisms are limited to file system operations (early or late + hooks may not have write access!) and standard UNIX programs. + 2. Thus, it is *not possible* to call `initctl` to query status of + services since that calls Finit over the `/run/finit/socket`. + 3. Confusingly enough, there are some commands to `initctl` that are + available; `ls`, `enable`, `disable`, `touch`, `create`, `delete`, + and all the `cond` commands. Because all these are basically just + wrappers for manipulating files (again, write access for early/late + hooks may not be available.) + +Also, similar to the `/etc/rc.local` shell script, make sure that all +your services and programs either terminate or start in the background +or you will block Finit. + +> **Note:** `runparts` scrips are only read and executed in runlevel S +> ([bootstrap][]). See [hook scripts](plugins.md#hooks) for other ways +> to run scripts at certain points during the complete lifetime of the +> system. + +**Recommendataions:** + It can be beneficial to use `01-name`, `02-othername`, etc., to ensure the scripts are started in that order, e.g., if there is a dependency order between scripts. Symlinks to existing daemons can talso be used, @@ -649,12 +676,6 @@ be called with an extra argument, `start` and `stop`, respectively. E.g., `S01foo` will be called as `S01foo start`. Of course, `S01foo` and `K01foo` may be a symlink to to `another/directory/foo`. -Similar to the `/etc/rc.local` shell script, make sure that all your -services and programs either terminate or start in the background or -you will block Finit. - -> **Note:** only read and executed in runlevel S ([bootstrap][]). - [run-parts(8)]: http://manpages.debian.org/cgi-bin/man.cgi?query=run-parts diff --git a/doc/plugins.md b/doc/plugins.md index 976ef6b1..c2ee13a0 100644 --- a/doc/plugins.md +++ b/doc/plugins.md @@ -8,7 +8,8 @@ Hooks & Plugins * [Shutdown Hooks](#shutdown-hooks) Finit can be extended to add general functionality in the form of I/O -monitors, or hook plugins. +monitors, or hook plugins. It is even possible to run scripts at these +hook points, see below. The following sections detail existing plugins and hook points. For more information, see the plugins listed below. @@ -109,7 +110,7 @@ a plain shell script, or program, that does a very small dedicated job at the below hook points. See [Run-parts Scripts](config.md#run-parts-scripts) for details on the -requirements, and possibilities, of hook scripts. +requirements, possibilities, and *limitations* of hook scripts. **Example:**