wt/finit
1
0
Fork 0
mirror of https://github.com/troglobit/finit.git synced 2026-10-12 10:12:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

man: sync man pages with documentation

Browse Source 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2025-07-10 13:30:12 +02:00
parent ab82e6f696
commit f42a1fd356
3 changed files with 245 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/finit.8
+70 -13
View File
@@ -2,7 +2,7 @@
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.Dd Apr 22, 2023
.Dd Jul 9, 2025
.\" Please adjust this date whenever revising the manpage.
.Dt FINIT 8 SMM
.Os Linux
@@ -10,30 +10,66 @@
.Nm finit
.Nd Fast init for Linux systems
.Sh SYNOPSIS
.Nm /sbin/finit
.Op --
.Nm /sbin/finit --
.Op debug
.Op finit.cond=foo[,bar[,baz]]
.Op finit.config=/path/to/alt/finit.conf
.Op finit.debug
.Op finit.fstab=/etc/fstab.alt
.Op finit.status=<on,off>
.Op finit.status_style=<classic,modern>
.Op loglevel=<0-7>
.Op panic=SEC
.Op quiet
.Op rescue | recover
.Op single | S
.Op panic=SEC
.Op loglevel=<0-7>
.Op fsck.mode=[auto,skip,force]
.Op fsck.repair=[no,yes,preen]
.Op finit.debug=<true,false>
.Op finit.fstab=/path/to/fstab
.Op finit.cond=foo[,bar[,baz]]
.Op finit.config=/path/to/finit.conf
.Op finit.status_style=<classic,modern>
.Op finit.status=<on,off>
.Nm /sbin/telinit
.Op Fl hv
.Op q | Q | 0-9
.Op q | Q | s | S | 0-9
.Sh DESCRIPTION
Fast init for Linux systems. Reverse engineered from the EeePC
fastinit, 10+ years ago by Claudio Matsuoka, "gaps filled with frog
DNA ...". Focus is on small and embedded systems, although Finit is
fully usable on server and desktop systems as well.
.Sh OPTIONS
When
.Sy not
started as PID 1,
.Nm
behaves like
.Nm telinit ,
following classic UNIX command line syntax. The options are:
.Pp
Features include:
.Bl -tag -width Ds -compact -offset indent
.It Fl h
Show built-in help text.
.It Fl v
Show program version.
.El
.Pp
More options are implemented for SysV init support, but are ignored.
.Sh ARGUMENTS
When
.Sy not
started as PID 1,
.Nm ,
or
.Nm telinit ,
take these arguments:
.Pp
.Bl -tag -width Ds -compact -offset indent
.It q | Q
Reload configuration, same as
.Cm initctl reload .
.It 0 - 9
Go to runlevel N, same as
.Cm initctl reload N .
.It s | S
Go to single user mode, runlevel 1.
.El
.Sh FEATURES
.Bl -bullet -width 1n -compact
.It
Runlevels, defined per service
@@ -93,6 +129,27 @@ Enable kernel debug. Debug messages are printed to the console until
Finit starts up, unless
.Cm loglevel=7
(below) is used.
.It Cm fsck.mode=<auto,force,skip>
Defaults to
.Cm auto ,
unless Finit is built with
.Cm configure --enable-fastboot ,
in which case the default is
.Cm skip .
.It Cm fsck.repair=<preen,yes,no>
Defaults to
.Cm preen ,
unless Finit is built with
.Cm configure --enable-fsckfix ,
in which case the default is
.Cm yes .
This configure option also sets
.Cm fsck.mode=force ,
unless fastboot is also enabled. I.e.,
.Cm configure --enable-fastboot
build option overrides the
.Cm fsck.mode
default value.
.It Cm finit.cond=foo[,bar[,baz]]
set
.Cm <boot/foo>
man/finit.conf.5
+128 -13
View File
@@ -2,7 +2,7 @@
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.Dd July 11, 2023
.Dd July 10, 2025
.Dt FINIT.CONF 5 SMM
.Os Linux
.Sh NAME
@@ -178,7 +178,7 @@ Similar to
.Cm service
is the
.Cm sysv
stanza, which can be used to call SysV style start/stop scripts. The
directive, which can be used to call SysV style start/stop scripts. The
primary intention for this command is to be able to re-use traditional
SysV init scripts in Linux distributions.
.Pp
@@ -194,7 +194,7 @@ on
.Cm initctl reload .
Similar to how
.Cm service
stanzas work.
directives work.
.Pp
Forking services started with
.Cm sysv
@@ -416,7 +416,30 @@ The post:script is called with the same environment variables
for the
.Cm EXIT_CODE
variable which is set to
.Cm "crashed" .
.Cm "crashed"
.It Cm reload:'script [args]'
some services do not support SIGHUP but may have other ways to update
the configuration of a running daemon. When
.Cm reload:script
is defined it is preferred over SIGHUP. Like systemd,
.Nm finit
sets
.Cm $MAINPID
as a convenience to scripts, which in effect also allow
.Cm reload:'kill -HUP $MAINPID'
.It Cm stop:'script [args]'
Some services may require alternate methods to be stopped. When
.Cm stop:script
is defined it is preferred over SIGTERM and stop, for
.Cm service
and
.Cm sysv
directives, respectively.
Similar to
.Cm reload:script ,
.Nm finit
sets
.Cm $MAINPID .
.El
.Pp
When stopping a service (run/task/sysv/service), either manually or when
@@ -535,7 +558,7 @@ size limit is reached.
.It Cm tty Oo LVLS Oc Ao COND Ac Ar DEV Oo BAUD Oc Oo noclear Oc Oo nowait Oc Oo nologin Oc Oo TERM Oc
This form of the
.Cm tty
stanza uses the built-in getty on the given TTY device
directive uses the built-in getty on the given TTY device
.Ar DEV ,
in the given runlevels.
.Ar DEV may be the special keyword
@@ -545,8 +568,8 @@ useful on embedded systems.
.Pp
The default baud rate is 0, i.e., keep kernel default.
.Pp
The `tty` stanza inherits runlevel, condition (and other feature)
parsing from the `service` stanza. So TTYs can run in one or many
The `tty` directive inherits runlevel, condition (and other feature)
parsing from the `service` directive. So TTYs can run in one or many
runlevels and depend on any condition supported by Finit. This is
useful e.g. to depend on `<pid/elogind>` before starting a TTY.
.Bd -unfilled -offset indent
@@ -555,7 +578,7 @@ tty [12345] /dev/ttyAMA0 115200 noclear vt220
.It Cm tty Oo LVLS Oc Ao COND Ac Ar CMD DEV Oo noclear Oc Oo nowait Oc
This form of the
.Cm tty
stanza is for using an external getty, like agetty or the BusyBox getty.
directive is for using an external getty, like agetty or the BusyBox getty.
.Pp
By default, these first two syntax variants
.Em clear
@@ -625,7 +648,7 @@ board bringup and system debugging it can come in handy.
.Pp
One can also use the
.Cm service
stanza to start a stand-alone shell:
directive to start a stand-alone shell:
.Bd -unfilled -offset indent
service [12345] /bin/sh -l
.Ed
@@ -650,9 +673,9 @@ is started to present a bare-bones root login prompt. If the root
(uid:0, gid:0) user does not have a password set, no rescue is possible.
.El
.Sh COMMAND MODIFIERS
The run/task/tty/service/sysv stanzas take modifiers, or options, to
The run/task/tty/service/sysv directives take modifiers, or options, to
control their behavior. This section lists them with their limitations.
All modifiers must be placed between the stanza and its command.
All modifiers must be placed between the directive and its command.
.Bl -tag -width 1n
.It Cm @user:group
Every
@@ -946,9 +969,10 @@ or
service [...] <...> cgroup.maint /path/to/foo args -- description
.Ed
.Pp
The latter form also allows per-stanza limits on the form:
The latter form also allows per-stanza limits on the form (notice the
single quotes for arguments that contain spaces):
.Bd -unfilled -offset indent
service [...] <...> cgroup.maint:cpu.max:10000,mem.max:655360 /path/to/foo args -- description
service [...] <...> cgroup.maint:cpu.max:'200000 100000',mem.max:655360 /path/to/foo args -- description
.Ed
.Pp
Notice the comma separation and the
@@ -968,6 +992,97 @@ available in your Linux kernel, or the name is misspelled.
Linux cgroups and details surrounding values are not explained in the
Finit documentation. The Linux admin-guide cover this well:
.Lk https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html
.Sh CONDITIONAL LOADING
Finit support conditional loading of stanzas. The following example is
take from the
.Pa system/hotplug.conf
file in the Finit distribution. Here we only show a simplified subset.
.Pp
Starting with the
.Cm nowarn
option.
.Bd -unfilled -offset indent
service nowarn name:udevd pid:udevd /lib/systemd/systemd-udevd
service nowarn name:udevd pid:udevd udevd
.Ed
.Pp
When loading the .conf file Finit looks for
.Pa /lib/systemd/systemd-udevd
if that is not found Finit automatically logs a warning. The
.Cm nowarn
option disables this warning so that the second line can be evaluated,
which also provides a service named
.Cm udevd .
.Bd -unfilled -offset indent
run nowarn if:udevd <pid/udevd> :1 udevadm settle -t 0
.Ed
.Pp
This line is only loaded if we know of a service named
.Cm udevd .
Again, we do not warn if
.Cm udevadm
is not found, execution will also stop here until the PID condition is
asserted, i.e., Finit detecting udevd has started.
.Bd -unfilled -offset indent
run nowarn conflict:udevd [S] mdev -s -- Populating device tree
.Ed
.Pp
If
.Cm udevd
is not available, we try to run
.Cm mdev ,
but if that is not found, again we do not warn.
.Pp
Conditional loading statements can also be negated, so the previous stanza
can also be written as:
.Bd -unfilled -offset indent
run nowarn if:!udevd [S] mdev -s -- Populating device tree
.Ed
.Pp
The reason for using
.Cm conflict
in this example is that a conflict can be resolved. Stanzas marked with
.C, conflict:foo
are rechecked at runtime.
.Sh CONDITIONAL EXECUTION
Similar to conditional loading of stanzas there is conditional runtime
execution. This can be confusing at first, since Finit already has a
condition subsystem, but this is more akin to the qualification to a
runlevel. E.g., a
.Cm task [123]
is qualified to run only in runlevel 1, 2, and 3. It is not considered
for other runlevels.
.Pp
Conditional execution qualify a run/task/service based on a condition.
Consider this (simplified) example from the Infix operating system:
.Bd -unfilled -offset indent
run [S] name:startup <pid/sysrepo> confd -b --load startup-config
run [S] if:<usr/fail-startup> name:failure <pid/sysrepo> confd --load failure-config
.Ed
.Pp
The two run statements reside in the same .conf file so Finit runs them
in true sequence. If loading the file
.Cm startup-config
fails
.Cm confd
sets the condition
.Cm usr/fail-startup ,
thus allowing the next run statement to load
.Cm failure-config .
.Pp
Notice the critical difference between the
.Cm <pid/sysrepo>
condition and
.Cm if:<usr/fail-startup> .
The former is a condition for starting and the latter is a condition to
check if a run/task/service is qualified to even be considered.
.Pp
Conditional execution statements can also be negated, so provided the
file loaded did the opposite, i.e., set a condition on success, the
previous stanza can also be written as:
.Bd -unfilled -offset indent
run [S] if:<!usr/startup-ok> name:failure <pid/sysrepo> confd ...
.Ed
.Sh LIMITATIONS
As of Finit v4 there are no limitations to where
.Cm .conf
man/initctl.8
+47 -44
View File
@@ -2,7 +2,7 @@
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.Dd June 6, 2021
.Dd July 10, 2025
.\" Please adjust this date whenever revising the manpage.
.Dt INITCTL 8 SMM
.Os Linux
@@ -24,39 +24,39 @@ This program follows the usual UNIX command line syntax, with long
options starting with two dashes (`-'). The options are as follows:
.Bl -tag -width Ds
.It Fl b, -batch
Batch mode, no screen size probing. Useful for scripting.
Batch mode, no screen size probing. Useful for scripting
.It Fl c, -create
Create missing paths (and files) as needed. Useful with the
.Cm edit
command.
command
.It Fl f, -force
Ignore missing files and arguments, never prompt.
Ignore missing files and arguments, never prompt
.It Fl h, -help
Show built-in help text.
Show built-in help text
.It Fl j, -json
JSON output in
.Ar status
and
.Ar cond
commands.
commands
.It Fl n, -noerr
When scripting
.Nm
to stop, start, restart, or signal a task or service, this option can be
used to ignore error 69 (no such task or service) and instead return 0
(OK).
(OK)
.It Fl 1, -once
Only one lap in commands like top.
Only one lap in commands like top
.It Fl p, -plain
Use plain table headings, no ANSI control characters.
Use plain table headings, no ANSI control characters
.It Fl q, -quiet
Silent, only return status of command.
Silent, only return status of command
.It Fl t, -no-heading
Skip table headings.
Skip table headings
.It Fl v, -verbose
Verbose output, where applicable.
Verbose output, where applicable
.It Fl V, -version
Show program version.
Show program version
.El
.Sh COMMANDS
.Bl -tag -width Ds
@@ -66,9 +66,9 @@ Toggle
(daemon) debug to
.Pa /dev/console
.It Nm Ar help
Show built-in help text.
Show built-in help text
.It Nm Ar version
Show program version.
Show program version
.It Nm Ar ls | list
List all
.Cm *.conf
@@ -112,9 +112,10 @@ like
.Ar edit
this tells
.Nm finit
that a configuration has been changed and is a candidate to be restarted
(or SIGHUP'ed) on
that a configuration has been changed and is a candidate to be reloaded
(SIGHUP'ed or restarted) on
.Cm initctl reload
in dependency order
.It Nm Ar enable Ar CONF
Enable
.Cm .conf
@@ -127,12 +128,12 @@ Disable
.Cm .conf
in
.Pa /etc/finit.d/enabled ,
i.e., removes symlink.
i.e., removes symlink
.It Nm Ar reload
Reload
Reload all (touched)
.Cm *.conf in
.Pa /etc/finit.d ,
i.e., activates changes.
.Pa /etc/finit.d
and activate changes
.It Nm Ar cond set Ar COND Op COND ...
Set (assert) user-defined condition,
.Cm +usr/COND
@@ -148,7 +149,7 @@ The command is geared for scripting, check the exit code to get the
status of the condition: 0 - on, 1 - off, 255 - flux. For a more
verbose output, use the
.Fl v
option.
option
.It Nm Ar cond clr | clear Ar COND Op COND ...
Clear (deassert) user-defined condition,
.Cm -usr/COND
@@ -157,28 +158,28 @@ Show condition status, default
.Cm cond
command. Also supports the
.Fl j
option for detailed JSON output.
option for detailed JSON output
.It Nm Ar cond dump Op Cm TYPE
Dump all, or a given type of, conditions and their status. Also
supports the
.Fl j
option for detailed JSON output.
option for detailed JSON output
.It Nm Ar ident Op Cm NAME
Display indentities of all run/task/services, or only instances
matching
.Cm NAME .
A partial string, e.g.,
.Cm NAM ,
will not match anything.
will not match anything
.It Nm Ar log Op Cm NAME
Show ten last Finit, or
.Cm NAME ,
messages from syslog.
messages from syslog
.It Nm Ar start Cm NAME[:ID]
Start service by name, with optional ID, e.g.,
.Cm initctl start tty:1
.It Nm Ar stop Cm NAME[:ID]
Stop/Pause a running service by name.
Stop/Pause a running service by name
.It Nm Ar reload Cm NAME[:ID]
Reload service as if its configuration had changed. Internally,
.Nm finit
@@ -193,17 +194,19 @@ it is the same as calling
Except for two things:
.Bl -enum -offset indent -compact
.It
if the service supports HUP, it's signaled instead of stop-started, and
if the service supports HUP (or has a
.Cm reload:script )
it is signaled instead of stop-started, and
.It
it allows restarting run/task in the same runlevel -- which is otherwise
restricted.
restricted
.El
.It Nm Ar signal Cm NAME:[ID] S
.It Nm Ar <kill | signal> Cm NAME:[ID] S
Send signal S to service, by name.
.Cm S
may be a complete signal name such as SIGHUP, or short name such as HUP, or the signal number such as 1 (SIGHUP).
may be a complete signal name such as SIGHUP, or short name such as HUP, or the signal number such as 1 (SIGHUP)
.It Nm Ar restart Cm NAME[:ID]
Restart (stop/start) service by name.
Restart (stop/start) service by name
.It Nm Ar status Cm NAME[:ID]
Show service status, by name. If only
.Cm NAME
@@ -225,48 +228,48 @@ option for detailed JSON output suitable for machine parsing.
.Pp
.Sy Tip:
.Xr jq 1
is a useful scripting tool in combination with JSON output.
is a useful scripting tool in combination with JSON output
.It Nm Ar status
Show status of all services, default command. Also supports the
.Fl j
option for detailed JSON output.
option for detailed JSON output
.It Nm Ar cgroup
List cgroup config overview.
List cgroup config overview
.It Nm Ar ps
List processes based on cgroups.
List processes based on cgroups
.It Nm Ar top
Show top-like listing based on cgroups.
Show top-like listing based on cgroups
.It Nm Ar plugins
List installed plugins.
List installed plugins
.It Nm Ar runlevel Op Ar 0-9
Show or set runlevel: 0 halt, 6 reboot.
.Pp
If called at boot (runlevel S) to set the runlevel, Finit only schedules
the change, effectively overriding the configured runlevel from
.Pa /etc/finit.conf .
Useful to trigger a fail-safe mode, or similar.
Useful to trigger a fail-safe mode, or similar
.It Nm Ar reboot
Reboot system, default if
.Cm reboot
is symlinked to
.Nm .
.Nm
.It Nm Ar halt
Halt system, default if
.Cm halt
is symlinked to
.Nm .
.Nm
.It Nm Ar poweroff
Power-off system, default if
.Cm poweroff
is symlinked to
.Nm .
.Nm
.It Nm Ar suspend
Suspend system, default if
.Cm suspend
is symlinked to
.Nm .
.Nm
.It Nm Ar utmp show
Raw dump of UTMP/WTMP db.
Raw dump of UTMP/WTMP db
.El
.Sh SEE ALSO
.Xr finit.conf 5