mirror of
https://github.com/troglobit/finit.git
synced 2026-11-20 19:41:51 +00:00
doc: Major refactor, change layout
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
1 parent
ad08f30b31
commit
352ffb1582
1 file changed
+104
-35
+104
-35
@@ -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
|
||||||
|
|||||||
Reference in new issue
Block a user