From e6f36974c8f1f42617a1fe40f2f75f2fa7d19741 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Sun, 25 Apr 2021 22:46:43 +0200 Subject: [PATCH] Document all facets of rescue mode; traditional and fallback Signed-off-by: Joachim Wiberg --- doc/cmdline.md | 12 ++++---- doc/config.md | 79 +++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 79 insertions(+), 12 deletions(-) diff --git a/doc/cmdline.md b/doc/cmdline.md index 270eea4b..865cf9c9 100644 --- a/doc/cmdline.md +++ b/doc/cmdline.md @@ -30,10 +30,12 @@ The `bool` setting is one of `on, off, true false, 1, 0`. * `quiet`: Suppress kernel logging to console, except for warnings and errors. -* `rescue`: Start Finit rescue mode; no network, no `fsck` of file - systems in `/etc/fstab`, no `/etc/rc.local`, no `runparts`. The - configuration is read from `/lib/finit/rescue.conf`, and can be - modified by the operator. +* `rescue`: Start rescue/maintenance mode. If your system comes with + the bundled `sulogin` program (Finit, or from util-linux/Busybox), + you will be given a root login to a maintenance shell. However, if + `sulogin` is missing, the file `/lib/finit/rescue.conf` is read and + the system booted in a limited fallback mode. See [config.md][] + for more information. * `single`, or `S`: Single user mode, runlevel 1, in Finit. Useful to debug problems with the regular runlevel. All services and TTYs in @@ -42,5 +44,5 @@ The `bool` setting is one of `on, off, true false, 1, 0`. For more on kernel boot paramaters, see the man page [bootparam(7)][]. - +[config.md][]: config.md#rescue-mode [bootparam(7)]: https://www.man7.org/linux/man-pages/man7/bootparam.7.html diff --git a/doc/config.md b/doc/config.md index aeef658b..c4a165ed 100644 --- a/doc/config.md +++ b/doc/config.md @@ -21,6 +21,7 @@ Configuration * [TTYs and Consoles](#ttys-and-consoles) * [Non-privileged Services](#non-privileged-services) * [Redirecting Output](#redirecting-output) +* [Rescue Mode](#rescue-mode) * [Limitations](#limitations) * [/etc/finit.conf](#etcfinitconf) * [/etc/finit.d](#etcfinitd) @@ -467,7 +468,8 @@ size limit is reached. ### TTYs and Consoles **Syntax:** `tty [LVLS] DEV [BAUD] [noclear] [nowait] [nologin] [TERM]` - `tty [LVLS] CMD [noclear] [nowait]` + `tty [LVLS] CMD [noclear] [nowait]` + `tty [LVLS] [notty] [rescue]` 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 @@ -486,9 +488,18 @@ The default baud rate is 0, i.e., keep kernel default. The second `tty` syntax variant is for using an external getty, like agetty or the BusyBox getty. - -By default both variants *clear* the TTY and *wait* for the user to -press enter before starting getty. + +The third variant is for board bringup and the `rescue` boot mode. No +device node is required in this variant, the same output that the kernel +uses is reused for stdio. If the `rescue` option is omitted, a shell is +started (`nologin`, `noclear`, and `nowait` are implied), if the rescue +option is set the bundled `/libexec/finit/sulogin` 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. For more information, +see the [Rescue Mode](#rescue-mode) section. + +By default, the first two syntax variants *clear* the TTY and *wait* for +the user to press enter before starting getty. **Example:** @@ -525,10 +536,11 @@ can be omitted to keep the kernel default. tty [12345] @console noclear vt220 -On really bare bones systems Finit can give you a shell prompt as -soon as [bootstrap][] is done, without opening any device node: +On really bare bones systems, or for board bringup, Finit can give you a +shell prompt as soon as [bootstrap][] is done, without opening any +device node: - tty [12345789] notty noclear + tty [12345789] notty This should of course not be enabled on production systems. Because it may give a user root access without having to log in. However, for @@ -584,6 +596,59 @@ Log rotation is controlled using the global `log` setting. service log:prio:user.warn,tag:ntpd /sbin/ntpd pool.ntp.org -- NTP daemon +Rescue Mode +----------- + +Finit supports a rescue mode which is activated by the `rescue` option +on the kernel command line. See [cmdline docs](cmdline.md) for how to +activate it. + +The rescue mode comes in two flavors; *traditional* and *fallback*. + + +### Traditional + +This is what most users expect. A very early maintenance login prompt, +served by the bundled `/libexec/finit/sulogin` program, or the standard +`sulogin` from util-linux or BusyBox is searched for in the UNIX default +`$PATH`. If a successful login is made, or the user exits (Ctrl-D), the +rescue mode is ended and the system boots up normally. + +> **Note:** if the user (UID 0 and GID 0) does not have a password, or +> __the account is locked__, the user is presented with a password-less +> `"Press enter to enter maintenance mode."`, prompt which opens up a +> root shell. + + +### Fallback + +If no `sulogin` program is found, Finit tries to bring up as much of its +own functionality as possible, yet limiting many aspects, meaning; no +network, no `fsck` of file systems in `/etc/fstab`, no `/etc/rc.local`, +no `runparts`, and most plugins are skipped (except those that provide +functionality for the condition subsystem). + +Instead of reading `/etc/finit.conf` et al, system configuration is read +from `/lib/finit/rescue.conf`, which can be freely modified by the +system administrator. + +The bundled default `rescue.conf` contains nothing more than: + + runlevel 1 + tty [12345] rescue + +The `tty` has the `rescue` option set, which works similar to the board +bring-up tty option `notty`. The major difference being that `sulogin` +is started to query for root/admin password. If `sulogin` is not found, +`rescue` behaves like `notty` and gives a plain root shell prompt. + +If Finit cannot find `/lib/finit/rescue.conf` it defaults to: + + tty [12345] rescue + +There is no way to exit the *fallback* rescue mode. + + Limitations -----------