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
+104 -35
+104 -35
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,14 +100,21 @@ 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. **Syntax:** `host <NAME>`, or `hostname <NAME>`
Set system hostname to NAME, unless `/etc/hostname` exists in which case
the contents of that file is used.
### Kernel Modules
**Syntax:** `module <MODULE> [ARGS]`
* `module <MODULE> [ARGS]`
Load a kernel module, with optional arguments. Similar to `insmod` Load a kernel module, with optional arguments. Similar to `insmod`
command line tool. command line tool.
@@ -106,13 +126,24 @@ Syntax
$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)`, **Syntax:** `network <PATH>`
without the prefix. E.g. to set `RLIMIT_CPU`, use `cpu`.
Script or program to bring up networking, with optional arguments.
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 LIMIT is an integer that depends on the resource being modified, see
the man page, or the kernel `/proc/PID/limits` file, for details. the man page, or the kernel `/proc/PID/limits` file, for details.
@@ -131,18 +162,31 @@ Syntax
`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
**Syntax:** `runlevel <N>`
N is the runlevel number 1-9, where 6 is reserved for reboot.
Default: 2
### 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 One-shot command to run in sequence when entering a runlevel, with
optional arguments and description. optional arguments and description.
`run` commands are guaranteed to be completed before running the next `run` commands are guaranteed to be completed before running the next
command. Highly useful if true serialization is needed. command. Highly useful if true serialization is needed.
* `task [LVLS] <COND> /path/to/cmd ARGS -- Optional description`
### 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. 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 Both `run` and `task` commands are run in a shell, so pipes and
@@ -150,36 +194,45 @@ Syntax
task [s] echo "foo" | cat >/tmp/bar task [s] echo "foo" | cat >/tmp/bar
* `sysv [LVLS] <COND> /path/to/init-script -- Optional description`__
### SysV Init Scripts
**Syntax:** `sysv [LVLS] <COND> /path/to/init-script -- Optional description`
Similar to `task` is the `sysv` stanza, which can be used to call SysV 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 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. re-use much of existing setup and init scripts in Linux distributions.
When entering an allowed runlevel, Finit calls `init-script start`, When entering an allowed runlevel, Finit calls `init-script start`, when
when entering a disallowed runlevel, Finit calls `init-script stop`, entering a disallowed runlevel, Finit calls `init-script stop`, and if
and if the Finit .conf, where `sysv` stanza is declared, is modified, the Finit .conf, where `sysv` stanza is declared, is modified, Finit
Finit calls `init-script restart` on `initctl reload`. Similar to calls `init-script restart` on `initctl reload`. Similar to how
how `service` stanzas work. `service` stanzas work.
Forking services started with `sysv` scripts can be monitored by Finit Forking services started with `sysv` scripts can be monitored by Finit
by declaring the PID file to look for: `pid:!/path/to/pidfile.pid`. by declaring the PID file to look for: `pid:!/path/to/pidfile.pid`.
* `service [LVLS] <COND> /path/to/daemon ARGS -- Optional description`
### Services
**Syntax:** `service [LVLS] <COND> /path/to/daemon ARGS -- Optional description`
Service, or daemon, to be monitored and automatically restarted if it Service, or daemon, to be monitored and automatically restarted if it
exits prematurely. Finit tries to restart services that die 10 times exits prematurely. Finit tries to restart services that die 10 times
before giving up, then you have to `initctl restart NAME` it manually. before giving up, then you have to `initctl restart NAME` it manually.
For daemons that support it, we recommend appending `--foreground`, For daemons that support it, we recommend appending `--foreground`,
`--no-background`, `-n`, `-F`, or similar command line argument to `--no-background`, `-n`, `-F`, or similar command line argument to
prevent them from forking off a sub-process in the background. This prevent them from forking off a sub-process in the background. This is
is the most reliable way to monitor a service. the most reliable way to monitor a service.
However, not all daemons support running in the foreground, or they However, not all daemons support running in the foreground, or they may
may start logging to the foreground as well, these are called forking start logging to the foreground as well, these are called forking
services and are supported using the same syntax as forking `sysv` services and are supported using the same syntax as forking `sysv`
services, using the `pid:!/path/to/pidfile.pid` syntax. services, using the `pid:!/path/to/pidfile.pid` syntax.
**Example:** **Example:**
In the case of `ospfd` (below), we omit the `-d` flag (daemonize) to In the case of `ospfd` (below), we omit the `-d` flag (daemonize) to
prevent it from forking to the background: prevent it from forking to the background:
@@ -208,8 +261,8 @@ Syntax
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
@@ -232,7 +285,11 @@ Syntax
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>`
### Run-parts Scripts
**Syntax:** `runparts <DIR>`
Call [run-parts(8)][] on `DIR` to run start scripts. All executable Call [run-parts(8)][] on `DIR` to run start scripts. All executable
files, or scripts, in the directory are called, in alphabetic order. files, or scripts, in the directory are called, in alphabetic order.
The scripts in this directory are executed at the very end of runlevel The scripts in this directory are executed at the very end of runlevel
@@ -246,10 +303,17 @@ Syntax
services and programs either terminate or start in the background or services and programs either terminate or start in the background or
you will block Finit. you will block Finit.
* `include <CONF>`
### Including Finit Configs
**Syntax:** `include <CONF>`
Include another configuration file. Absolute path required. Include another configuration file. Absolute path required.
* `log size:200k count:5`
### General Logging
**Syntax:** `log size:200k count:5`
Log rotation for run/task/services using the `log` sub-option with Log rotation for run/task/services using the `log` sub-option with
redirection to a log file. Global setting, applies to all services. redirection to a log file. Global setting, applies to all services.
@@ -262,8 +326,11 @@ Syntax
Setting count to 0 means the logfile will be truncated when the MAX Setting count to 0 means the logfile will be truncated when the MAX
size limit is reached. size limit is reached.
* `tty [LVLS] <DEV> [BAUD] [noclear] [nowait] [nologin] [TERM]` ### 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 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 TTY device DEV, in the given runlevels. The DEV may be the special
keyword `@console`, or `console`, useful on embedded systems. keyword `@console`, or `console`, useful on embedded systems.
@@ -322,6 +389,7 @@ Syntax
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