doc: Major refactor, change layout

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg committed 2021-02-17 11:26:49 +01:00
1 parent ad08f30b31
commit 352ffb1582
1 file changed
+222 -153
+222 -153
View File
@@ -3,7 +3,20 @@ Configuration
* [Introduction](#introduction) * [Introduction](#introduction)
* [Service Wrapper Scripts](#service-wrapper-scripts) * [Service Wrapper Scripts](#service-wrapper-scripts)
* [Syntax](#syntax) * [Configuration File Syntax](#configuration-file-syntax)
* [Hostname](#hostname)
* [Kernel Modules](#kernel-modules)
* [Networking](#networking)
* [Resource Limits](#resource-limits)
* [Runlevels](#runlevels)
* [One-shot Commands (sequence)](#one-shot-commands--sequence-)
* [One-shot Commands (parallel)](#one-shot-commands--parallel-)
* [SysV Init Scripts](#sysv-init-scripts)
* [Services](#services)
* [Run-parts Scripts](#run-parts-scripts)
* [Including Finit Configs](#including-finit-configs)
* [General Logging](#general-logging)
* [TTYs and Consoles](#ttys-and-consoles)
* [Non-privileged Services](#non-privileged-services) * [Non-privileged Services](#non-privileged-services)
* [Redirecting Output](#redirecting-output) * [Redirecting Output](#redirecting-output)
* [Limitations](#limitations) * [Limitations](#limitations)
@@ -87,37 +100,55 @@ example employs a wrapper script in `/etc/start.d`.
> instead of sending SIGHUP at restart/reload events. > instead of sending SIGHUP at restart/reload events.
Syntax Configuration File Syntax
------ -------------------------
* `host <NAME>`, or `hostname <NAME>` ### Hostname
Set system hostname to NAME, unless `/etc/hostname` exists in which
case the contents of that file is used.
* `module <MODULE> [ARGS]` **Syntax:** `host <NAME>`, or `hostname <NAME>`
Load a kernel module, with optional arguments. Similar to `insmod`
command line tool.
Note, there is both a `modules-load.so` and a `modprobe.so` plugin Set system hostname to NAME, unless `/etc/hostname` exists in which case
that can handle module loading better. The former supports loading the contents of that file is used.
from `/etc/modules-load.d/`, and the latter uses kernel modinfo to
automatically load (or coldplug) every required module. For hotplug
we recommend the BusyBox mdev tool, add to `/etc/mdev.conf`: ### Kernel Modules
**Syntax:** `module <MODULE> [ARGS]`
Load a kernel module, with optional arguments. Similar to `insmod`
command line tool.
Note, there is both a `modules-load.so` and a `modprobe.so` plugin
that can handle module loading better. The former supports loading
from `/etc/modules-load.d/`, and the latter uses kernel modinfo to
automatically load (or coldplug) every required module. For hotplug
we recommend the BusyBox mdev tool, add to `/etc/mdev.conf`:
$MODALIAS=.* root:root 0660 @modprobe -b "$MODALIAS" $MODALIAS=.* root:root 0660 @modprobe -b "$MODALIAS"
* `network <PATH>`
Script or program to bring up networking, with optional arguments
* `rlimit [hard|soft] RESOURCE <LIMIT|unlimited>` Set the hard or soft ### Networking
limit for a resource, or both if that argument is omitted. `RESOURCE`
is the lower-case `RLIMIT_` string constants from `setrlimit(2)`,
without the prefix. E.g. to set `RLIMIT_CPU`, use `cpu`.
LIMIT is an integer that depends on the resource being modified, see **Syntax:** `network <PATH>`
the man page, or the kernel `/proc/PID/limits` file, for details.
Finit versions before v3.1 used `infinity` for `unlimited`, which is Script or program to bring up networking, with optional arguments.
still supported, albeit deprecated.
Deprecated. We recommend using task/run or `/etc/network/interfaces` if
you have a system with ifupdown.
### Resource Limits
**Syntax:** `rlimit [hard|soft] RESOURCE <LIMIT|unlimited>`
Set the hard or soft limit for a resource, or both if that argument is
omitted. `RESOURCE` is the lower-case `RLIMIT_` string constants from
`setrlimit(2)`, without prefix. E.g. to set `RLIMIT_CPU`, use `cpu`.
LIMIT is an integer that depends on the resource being modified, see
the man page, or the kernel `/proc/PID/limits` file, for details.
Finit versions before v3.1 used `infinity` for `unlimited`, which is
still supported, albeit deprecated.
# No process is allowed more than 8MB of address space # No process is allowed more than 8MB of address space
rlimit hard as 8388608 rlimit hard as 8388608
@@ -128,200 +159,237 @@ Syntax
# CPU limit for all services, soft & hard = 10 sec # CPU limit for all services, soft & hard = 10 sec
rlimit cpu 10 rlimit cpu 10
`rlimit` can be set globally, in `/etc/finit.conf`, or locally for `rlimit` can be set globally, in `/etc/finit.conf`, or locally for
a set of task/run/services, in `/etc/finit.d/*.conf`. a set of task/run/services, in `/etc/finit.d/*.conf`.
* `runlevel <N>`
N is the runlevel number 1-9, where 6 is reserved for reboot.
Default is 2.
* `run [LVLS] <COND> /path/to/cmd ARGS -- Optional description` ### Runlevels
One-shot command to run in sequence when entering a runlevel, with
optional arguments and description.
`run` commands are guaranteed to be completed before running the next **Syntax:** `runlevel <N>`
command. Highly useful if true serialization is needed.
* `task [LVLS] <COND> /path/to/cmd ARGS -- Optional description` N is the runlevel number 1-9, where 6 is reserved for reboot.
One-shot like 'run', but starts in parallel with the next command.
Both `run` and `task` commands are run in a shell, so pipes and Default: 2
redirects can be freely used:
### One-shot Commands (sequence)
**Syntax:** `run [LVLS] <COND> /path/to/cmd ARGS -- Optional description`
One-shot command to run in sequence when entering a runlevel, with
optional arguments and description.
`run` commands are guaranteed to be completed before running the next
command. Highly useful if true serialization is needed.
### One-shot Commands (parallel)
**Syntax:** `task [LVLS] <COND> /path/to/cmd ARGS -- Optional description`
One-shot like 'run', but starts in parallel with the next command.
Both `run` and `task` commands are run in a shell, so pipes and
redirects can be freely used:
task [s] echo "foo" | cat >/tmp/bar task [s] echo "foo" | cat >/tmp/bar
* `sysv [LVLS] <COND> /path/to/init-script -- Optional description`__
Similar to `task` is the `sysv` stanza, which can be used to call SysV
style scripts. The primary intention for this command is to be able to
re-use much of existing setup and init scripts in Linux distributions.
When entering an allowed runlevel, Finit calls `init-script start`, ### SysV Init Scripts
when entering a disallowed runlevel, Finit calls `init-script stop`,
and if the Finit .conf, where `sysv` stanza is declared, is modified,
Finit calls `init-script restart` on `initctl reload`. Similar to
how `service` stanzas work.
Forking services started with `sysv` scripts can be monitored by Finit **Syntax:** `sysv [LVLS] <COND> /path/to/init-script -- Optional description`
by declaring the PID file to look for: `pid:!/path/to/pidfile.pid`.
* `service [LVLS] <COND> /path/to/daemon ARGS -- Optional description` Similar to `task` is the `sysv` stanza, which can be used to call SysV
Service, or daemon, to be monitored and automatically restarted if it style scripts. The primary intention for this command is to be able to
exits prematurely. Finit tries to restart services that die 10 times re-use much of existing setup and init scripts in Linux distributions.
before giving up, then you have to `initctl restart NAME` it manually.
For daemons that support it, we recommend appending `--foreground`, When entering an allowed runlevel, Finit calls `init-script start`, when
`--no-background`, `-n`, `-F`, or similar command line argument to entering a disallowed runlevel, Finit calls `init-script stop`, and if
prevent them from forking off a sub-process in the background. This the Finit .conf, where `sysv` stanza is declared, is modified, Finit
is the most reliable way to monitor a service. calls `init-script restart` on `initctl reload`. Similar to how
`service` stanzas work.
However, not all daemons support running in the foreground, or they Forking services started with `sysv` scripts can be monitored by Finit
may start logging to the foreground as well, these are called forking by declaring the PID file to look for: `pid:!/path/to/pidfile.pid`.
services and are supported using the same syntax as forking `sysv`
services, using the `pid:!/path/to/pidfile.pid` syntax.
**Example:**
In the case of `ospfd` (below), we omit the `-d` flag (daemonize) to ### Services
prevent it from forking to the background:
**Syntax:** `service [LVLS] <COND> /path/to/daemon ARGS -- Optional description`
Service, or daemon, to be monitored and automatically restarted if it
exits prematurely. Finit tries to restart services that die 10 times
before giving up, then you have to `initctl restart NAME` it manually.
For daemons that support it, we recommend appending `--foreground`,
`--no-background`, `-n`, `-F`, or similar command line argument to
prevent them from forking off a sub-process in the background. This is
the most reliable way to monitor a service.
However, not all daemons support running in the foreground, or they may
start logging to the foreground as well, these are called forking
services and are supported using the same syntax as forking `sysv`
services, using the `pid:!/path/to/pidfile.pid` syntax.
**Example:**
In the case of `ospfd` (below), we omit the `-d` flag (daemonize) to
prevent it from forking to the background:
service [2345] <pid/zebra> /sbin/ospfd -- OSPF daemon service [2345] <pid/zebra> /sbin/ospfd -- OSPF daemon
`[2345]` denote the runlevels `ospfd` is allowed to run in, they are `[2345]` denote the runlevels `ospfd` is allowed to run in, they are
optional and default to level 2-5 if omitted. optional and default to level 2-5 if omitted.
`<...>` is the condition for starting `ospfd`. In this example Finit `<...>` is the condition for starting `ospfd`. In this example Finit
waits for another service, `zebra`, to have created its PID file in waits for another service, `zebra`, to have created its PID file in
`/var/run/quagga/zebra.pid` before starting `ospfd`. Finit watches `/var/run/quagga/zebra.pid` before starting `ospfd`. Finit watches
*all* files in `/var/run`, for each file named `*.pid`, or `*/pid`, *all* files in `/var/run`, for each file named `*.pid`, or `*/pid`,
Finit opens it and find the matching `NAME:ID` using the PID. Finit opens it and find the matching `NAME:ID` using the PID.
Some services do not maintain a PID file and rather than patching each Some services do not maintain a PID file and rather than patching each
application Finit provides a workaround. A `pid` keyword can be set application Finit provides a workaround. A `pid` keyword can be set
to have Finit automatically create (when starting) and later remove to have Finit automatically create (when starting) and later remove
(when stopping) the PID file. The file is created in the `/var/run` (when stopping) the PID file. The file is created in the `/var/run`
directory using the `basename(1)` of the service. The default can be directory using the `basename(1)` of the service. The default can be
modified with an optional `pid:`-argument: modified with an optional `pid:`-argument:
pid[:[/path/to/]filename[.pid]] pid[:[/path/to/]filename[.pid]]
For example, by adding `pid:/run/foo.pid` to the service `/sbin/bar`, For example, by adding `pid:/run/foo.pid` to the service `/sbin/bar`,
that PID file will, not only be created and removed automatically, but that PID file will, not only be created and removed automatically, but
also be used by the Finit condition subsystem. So a service/run/task also be used by the Finit condition subsystem. So a service/run/task
can depend on `<pid/bar>`. can depend on `<pid/bar>`.
> For a detailed description of conditions, and how to debug them, see > For a detailed description of conditions, and how to debug them,
> the [Finit Conditions](conditions.md) document. > see the [Finit Conditions](conditions.md) document.
If a service should not be automatically started, it can be configured If a service should not be automatically started, it can be configured
as manual with the optional `manual` argument. The service can then be as manual with the optional `manual` argument. The service can then be
started at any time by running `initctl start <service>`. started at any time by running `initctl start <service>`.
manual:yes manual:yes
The name of a service, shown by the `initctl` tool, defaults to the The name of a service, shown by the `initctl` tool, defaults to the
basename of the service executable. It can be changed with the basename of the service executable. It can be changed with the
optional `name` argument: optional `name` argument:
name:<service-name> name:<service-name>
When stopping a service (run/task/sysv/service), either manually or When stopping a service (run/task/sysv/service), either manually or
when moving to another runlevel, Finit starts by sending `SIGTERM`, to when moving to another runlevel, Finit starts by sending `SIGTERM`, to
allow the process to shut down gracefully. If the process has not allow the process to shut down gracefully. If the process has not
been collected within 3 seconds, Finit sends `SIGKILL`. To halt the been collected within 3 seconds, Finit sends `SIGKILL`. To halt the
process using a different signal, use the option `halt:SIGNAL`, e.g., process using a different signal, use the option `halt:SIGNAL`, e.g.,
`halt:SIGPWR`. To change the delay between your halt signal and KILL, `halt:SIGPWR`. To change the delay between your halt signal and KILL,
use the option `kill:SEC`, e.g., `kill:10` to wait 10 seconds before use the option `kill:SEC`, e.g., `kill:10` to wait 10 seconds before
sending `SIGKILL`. sending `SIGKILL`.
* `runparts <DIR>`
Call [run-parts(8)][] on `DIR` to run start scripts. All executable
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.
It can be beneficial to use `S01name`, `S02othername`, etc. if there ### Run-parts Scripts
is a dependency order between the scripts. Symlinks to existing
daemons can talso be used, but make sure they daemonize by default.
Similar to the `/etc/rc.local` shell script, make sure that all your **Syntax:** `runparts <DIR>`
services and programs either terminate or start in the background or
you will block Finit.
* `include <CONF>` Call [run-parts(8)][] on `DIR` to run start scripts. All executable
Include another configuration file. Absolute path required. 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.
* `log size:200k count:5` It can be beneficial to use `S01name`, `S02othername`, etc. if there
is a dependency order between the scripts. Symlinks to existing
daemons can talso be used, but make sure they daemonize by default.
Log rotation for run/task/services using the `log` sub-option with Similar to the `/etc/rc.local` shell script, make sure that all your
redirection to a log file. Global setting, applies to all services. services and programs either terminate or start in the background or
you will block Finit.
The size can be given as bytes, without a specifier, or in `k`, `M`,
or `G`, e.g. `size:10M`, or `size:3G`. A value of `size:0` disables
log rotation. The default is `200k`.
The count value is recommended to be between 1-5, with a default 5. ### Including Finit Configs
Setting count to 0 means the logfile will be truncated when the MAX
size limit is reached.
* `tty [LVLS] <DEV> [BAUD] [noclear] [nowait] [nologin] [TERM]` **Syntax:** `include <CONF>`
Include another configuration file. Absolute path required.
### General Logging
**Syntax:** `log size:200k count:5`
Log rotation for run/task/services using the `log` sub-option with
redirection to a log file. Global setting, applies to all services.
The size can be given as bytes, without a specifier, or in `k`, `M`,
or `G`, e.g. `size:10M`, or `size:3G`. A value of `size:0` disables
log rotation. The default is `200k`.
The count value is recommended to be between 1-5, with a default 5.
Setting count to 0 means the logfile will be truncated when the MAX
size limit is reached.
### TTYs and Consoles
**Syntax:** `tty [LVLS] <DEV> [BAUD] [noclear] [nowait] [nologin] [TERM]`
`tty [LVLS] <CMD> <ARGS> [noclear] [nowait]` `tty [LVLS] <CMD> <ARGS> [noclear] [nowait]`
The first variant of this option uses the built-in getty on the given
TTY device DEV, in the given runlevels. The DEV may be the special
keyword `@console`, or `console`, useful on embedded systems.
The default baud rate is 0, i.e., keep kernel default. The first variant of this option uses the built-in getty on the given
TTY device DEV, in the given runlevels. The DEV may be the special
keyword `@console`, or `console`, useful on embedded systems.
**Example:** The default baud rate is 0, i.e., keep kernel default.
**Example:**
tty [12345] /dev/ttyAMA0 115200 noclear vt220 tty [12345] /dev/ttyAMA0 115200 noclear vt220
The second `tty` syntax variant is for using an external getty, like The second `tty` syntax variant is for using an external getty, like
agetty or the BusyBox getty. agetty or the BusyBox getty.
By default both variants *clear* the TTY and *wait* for the user to By default both variants *clear* the TTY and *wait* for the user to
press enter before starting getty. press enter before starting getty.
**Example:** **Example:**
tty [12345] /sbin/getty -L 115200 /dev/ttyAMA0 vt100 tty [12345] /sbin/getty -L 115200 /dev/ttyAMA0 vt100
tty [12345] /sbin/agetty -L ttyAMA0 115200 vt100 nowait tty [12345] /sbin/agetty -L ttyAMA0 115200 vt100 nowait
The `noclear` option disables clearing the TTY after each session. The `noclear` option disables clearing the TTY after each session.
Clearing the TTY when a user logs out is usually preferable. Clearing the TTY when a user logs out is usually preferable.
The `nowait` option disables the `press Enter to activate console` The `nowait` option disables the `press Enter to activate console`
message before actually starting the getty program. On small and message before actually starting the getty program. On small and
embedded systems running multiple unused getty wastes both memory embedded systems running multiple unused getty wastes both memory
and CPU cycles, so `wait` is the preferred default. and CPU cycles, so `wait` is the preferred default.
The `nologin` option disables getty and `/bin/login`, and gives the The `nologin` option disables getty and `/bin/login`, and gives the
user a root (login) shell on the given TTY `<DEV>` immediately. user a root (login) shell on the given TTY `<DEV>` immediately.
Needless to say, this is a rather insecure option, but can be very Needless to say, this is a rather insecure option, but can be very
useful for developer builds, during board bringup, or similar. useful for developer builds, during board bringup, or similar.
Notice the ordering, the `TERM` option to the built-in getty must be Notice the ordering, the `TERM` option to the built-in getty must be
the last argument. the last argument.
Embedded systems may want to enable automatic `DEV` by supplying the Embedded systems may want to enable automatic `DEV` by supplying the
special `@console` device. This works regardless weather the system special `@console` device. This works regardless weather the system
uses `ttyS0`, `ttyAMA0`, `ttyMXC0`, or anything else. Finit figures uses `ttyS0`, `ttyAMA0`, `ttyMXC0`, or anything else. Finit figures
it out by querying sysfs: `/sys/class/tty/console/active`. The speed it out by querying sysfs: `/sys/class/tty/console/active`. The speed
can be omitted to keep the kernel default. can be omitted to keep the kernel default.
**Example:** **Example:**
tty [12345] @console noclear vt220 tty [12345] @console noclear vt220
On really bare bones systems Finit offers a fallback shell, which On really bare bones systems Finit offers a fallback shell, which
should not be enabled on production systems since. This because it should not be enabled on production systems since. This because it
may give a user root access without having to log in. However, for may give a user root access without having to log in. However, for
bringup and system debugging it can come in handy: bringup and system debugging it can come in handy:
configure --enable-fallback-shell configure --enable-fallback-shell
One can also use the `service` stanza to start a stand-alone shell: One can also use the `service` stanza to start a stand-alone shell:
service [12345] /bin/sh -l service [12345] /bin/sh -l
### Non-privileged Services ### Non-privileged Services
Every `run`, `task`, or `service` can also list the privileges the Every `run`, `task`, or `service` can also list the privileges the
@@ -340,6 +408,7 @@ multiple web servers, add `:ID` somewhere between the `run`, `task`,
Without the `:ID` to the service the latter will overwrite the former Without the `:ID` to the service the latter will overwrite the former
and only the old web server would be started and supervised. and only the old web server would be started and supervised.
### Redirecting Output ### Redirecting Output
The `run`, `task`, and `service` stanzas also allow the keyword `log` to The `run`, `task`, and `service` stanzas also allow the keyword `log` to