doc: collapse about + introduction into a single index.md

troglobit · troglobit · commit 5b100fb99e27 · 2025-07-30T14:58:14.000+02:00
In the spirit of my uni English teacher; "simplify, Simplify, SIMPLIFY!"
This commit collapses the About and Introduction into a single document,
doc/index.md.

Also, relocate the System Boot section to doc/boot.md, which we alrady
have and covers the initial bootloader part of it.

Signed-off-by: Joachim Wiberg &lt;troglobit@gmail.com&gt;
diff --git a/doc/boot.md b/doc/boot.md
@@ -124,6 +124,77 @@ is also possible to permanently configure the default partition from
 Infix using the [Bootloader Configuration](#configuration).
 
 
+## System Boot
+
+After the system firmware (BIOS or and [boot loader](boot.md) start
+Linux the following happens.  The various failure modes, e.g., missing
+password in VPD, are detailed later in this section.
+
+![System boot flowchart](img/fail-secure.svg)
+
+ 1. Before mounting `/cfg` and `/var` partitions, hosting read-writable
+    data like `startup-config` and container images, the system first
+    checks if a factory reset has been requested by the user, if so it
+    wipes the contents of these partitions
+ 2. Linux boots with a device tree which is used for detecting generic
+    make and model of the device, e.g., number of interfaces.  It may
+    also reference an EEPROM with [Vital Product Data](vpd.md).  That is
+    where the base MAC address and per-device password hash is stored.
+    (Generic builds use the same MAC address and password)
+ 3. On every boot the system's `factory-config` and `failure-config` are
+    generated from the YANG[^2] models of the current firmware version.
+    This ensures that a factory reset device can always boot, and that
+    there is a working fail safe, or rather *fail secure*, mode
+ 4. On first power-on, and after a factory reset, the system does not
+    have a `startup-config`, in which case `factory-config` is copied
+    to `startup-config` -- if a per-product specific version exists it
+    is preferred over the generated one
+ 5. Provided the integrity of the `startup-config` is OK, a system
+    service loads and activates the configuration
+
+### Failure Modes
+
+So, what happens if any of the steps above fail?
+
+**VPD Fail**
+
+The per-device password cannot be read, or is corrupt, so the system
+`factory-config` and `failure-config` are not generated:
+
+ 1. First boot, or after factory reset: `startup-config` cannot be
+    created or loaded, and `failure-config` cannot be loaded.  The
+    system ends up in an unrecoverable state, i.e., **RMA[^3] Mode**
+ 2. The system has booted (at least) once with correct VPD and password
+    and already has a `startup-config`.  Provided the `startup-config`
+    is OK (see below), it is loaded and system boots successfully
+
+In both cases, external factory reset modes/button will not help, and
+in the second case will cause the device to fail on the next boot.
+
+> The second case does not yet have any warning or event that can be
+> detected from the outside.  This is planned for a later release.
+
+**Broken startup-config**
+
+If loading `startup-config` fails for some reason, e.g., invalid JSON
+syntax, failed validation against the system's YANG model, or a bug in
+the system's `confd` service, the *Fail Secure Mode* is triggered and
+`failure-config` is loaded (unless VPD Failure, see above).
+
+> [!TIP]
+> Please see the [Branding & Releases](branding.md) document for how to
+> provide per-product `failure-config`, or `factory-config` to suit your
+> product's preferences.
+
+*Fail Secure Mode* is a fail-safe mode provided for debugging the
+system.  The default[^4] creates a setup of isolated interfaces with
+communication only to the management CPU, SSH and console login using
+the device's factory reset password, IP connectivity only using IPv6
+link-local, and device discovery protocols: LLDP, mDNS-SD.  The login
+and shell prompt are set to `failure-c0-ff-ee`, the last three octets of
+the device's base MAC address.
+
+
 System Upgrade
 --------------
 
@@ -337,6 +408,18 @@ If `var` is not available, Infix will still persist `/var/lib` using
 `cfg` as the backing storage.
 
 [^1]: See [Upgrade & Boot Order](upgrade.md) for more information.
+[^2]: YANG is a modeling language from IETF, replacing that used for
+    SNMP (MIB), used to describe the subsystems and properties of
+	the system.
+[^3]: Return Merchandise Authorization (RMA), i.e., broken beyond repair
+    by end-user and eligible for return to manufacturer.
+[^4]: Customer specific builds can define their own `failure-config`.
+    It may be the same as `factory-config`, with the hostname set to
+    `failure`, or a dedicated configuration that isolates interfaces, or
+    even disables ports, to ensure that the device does not cause any
+    security problems on the network.  E.g., start forwarding traffic
+    between previously isolated VLANs.
+
 
 [2]:      netboot.md
 [FIT]:    https://u-boot.readthedocs.io/en/latest/usage/fit.html
diff --git a/doc/branding.md b/doc/branding.md
@@ -50,7 +50,7 @@ at boot.  This also ensures the device can always be restored to a known
 state after a factory reset, since the `factory-config` is guaranteed to
 be compatible with the YANG models for the given software version. (For
 more information on how the system boots, please see the section [Key
-Concepts](introduction.md#key-concepts) in the Introduction document.)
+Concepts](index.md#key-concepts) in the Introduction document.)
 
 However, for custom builds of Infix it is possible to override this with
 a single static `/etc/factory-config.cfg` (and failure-config) in your
diff --git a/doc/index.md b/doc/index.md
@@ -1,3 +1,5 @@
+# Introduction
+
 ![Infix - Linux <3 NETCONF](logo.png){ align=right  width="480" }
 
 Welcome to Infix, your immutable, friendly, and secure operating system!
@@ -11,3 +13,80 @@ regression test system solely relies on NETCONF and RESTCONF.
 > [!TIP]
 > The CLI documentation is also available from inside the CLI itself
 > using the `help` command in admin-exec mode.
+
+This document provides an introduction of key concepts, details how
+the system boots, including failure modes, and provides links to
+other documents for further study.
+
+## Command Line Interface
+
+The command line interface (CLI, see-ell-i) is the traditional way of
+interacting with single network equipment like switches and routers.
+Today users have come to expect more advanced graphical GUIs, like a web
+interface, to manage a device or NETCONF-based tools that allow for
+managing entire fleets of installed equipment.
+
+Nevertheless, when it comes to initial deployment and debugging, it
+is very useful to know how to navigate and use the CLI.
+
+> [!INFO]
+> For more information, see the [CLI Introduction](cli/introduction.md)
+> and the [CLI Configuration Tutorial](cli/configure.md).
+
+## Key Concepts
+
+The two modes in the CLI are the admin-exec and the configure context.
+
+However, when logging in to the system, from the console port or SSH,
+you land in a standard UNIX shell, Bash.  This is for advanced users
+and remote scripting purposes (production equipment):
+
+```
+    Run the command 'cli' for interactive OAM
+
+    admin@example:~$
+```
+
+To enter the CLI, follow the instructions, for interactive Operations,
+Administration, and Management (OAM), type:
+
+```
+    admin@example:~$ cli
+    admin@example:/>
+```
+
+The prompt, constructed from your username and the device's hostname,
+changes slightly.  You are now in the admin-exec context of the CLI.
+Here you can inspect system status and do operations to debug networking
+issues, e.g. ping.  You can also enter configure context by typing:
+`configure` followed by commands to `set`, `edit`, apply changes using
+`leave`, or `abort` and return to admin-exec.
+
+> [!TIP]
+> If you haven't already, the [CLI Introduction](cli/introduction.md)
+> would be useful to skim through at this point.
+
+## Datastores
+
+The system has several datastores (or files):
+
+ - `factory-config` consists of a set of default configurations, some
+   static and others generated per-device, e.g., a unique hostname and
+   number of ports/interfaces.   This file is generated at boot.
+ - `failure-config` is also generated at boot, from the same YANG models
+   as `factory-config`, and holds the system *Fail Secure Mode*
+ - `startup-config` is created from `factory-config` at boot if it does
+   not exist.  It is loaded as the system configuration on each boot.
+ - `running-config` is what is actively running on the system.  If no
+   changes have been made since the system booted, it is the same as
+   `startup-config`.
+ - `candidate-config` is created from `running-config` when entering the
+   configure context.  Any changes made here can be discarded (`abort`,
+   `rollback`) or committed (`commit`, `leave`) to `running-config`.
+
+> [!TIP]
+> Please see the [Branding & Releases](branding.md) document for more
+> in-depth information on how `factory-config` and `failure-config` can
+> be adapted to different customer requirements.  Including how you can
+> override the generated versions of these files with plain per-product
+> ones -- this may even protect against some of the failure modes below.
diff --git a/doc/introduction.md b/doc/introduction.md
diff --git a/doc/upgrade.md b/doc/upgrade.md
@@ -418,7 +418,7 @@ Continued configuration is done as with any unit after factory reset.
 
 [1]: netboot.md
 [2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/confd/infix-system-software.yang
-[3]: introduction.md#system-boot
+[3]: boot.md#system-boot
 [4]: management.md#console-port
 [5]: scripting.md#-backup-configuration-using-sysrepocfg-and-scp
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -14,8 +14,7 @@ exclude_docs: |
   TODO.org
 
 nav:
-  - About: index.md
-  - Introduction: introduction.md
+  - Introduction: index.md
   - CLI:
       - Introduction: cli/introduction.md
       - Configuration: cli/configure.md
