diff --git a/man/finit.8 b/man/finit.8 index dda03e8c..df5b527e 100644 --- a/man/finit.8 +++ b/man/finit.8 @@ -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= -.Op finit.status_style= -.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= +.Op finit.fstab=/path/to/fstab +.Op finit.cond=foo[,bar[,baz]] +.Op finit.config=/path/to/finit.conf +.Op finit.status_style= +.Op finit.status= .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= +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= +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 diff --git a/man/finit.conf.5 b/man/finit.conf.5 index 00953b67..47b4b9f8 100644 --- a/man/finit.conf.5 +++ b/man/finit.conf.5 @@ -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 `` 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 :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 confd -b --load startup-config +run [S] if: name:failure 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 +condition and +.Cm if: . +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: name:failure confd ... +.Ed .Sh LIMITATIONS As of Finit v4 there are no limitations to where .Cm .conf diff --git a/man/initctl.8 b/man/initctl.8 index 1d6ab842..8751b5e4 100644 --- a/man/initctl.8 +++ b/man/initctl.8 @@ -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 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