From dd5ace4d3f6be5b509517dd882a31270de248f89 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Wed, 27 Mar 2024 14:52:05 +0100 Subject: [PATCH] doc: add system Introduction about *-config and failure modes Fixes #360 Signed-off-by: Joachim Wiberg --- doc/README.md | 1 + doc/img/fail-secure.svg | 4 ++ doc/introduction.md | 130 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 135 insertions(+) create mode 100644 doc/img/fail-secure.svg create mode 100644 doc/introduction.md diff --git a/doc/README.md b/doc/README.md index 9b9417d9..271d3d59 100644 --- a/doc/README.md +++ b/doc/README.md @@ -14,6 +14,7 @@ the `help` command. - [CLI User's Guide](cli/tutorial.md) - [Quick Overview](cli/quick.md) - **Infix User Guide** + - [Introduction](introduction.md) - [System Configuration](system.md) - [Network Configuration](networking.md) - **Infix In-Depth** diff --git a/doc/img/fail-secure.svg b/doc/img/fail-secure.svg new file mode 100644 index 00000000..ce44d733 --- /dev/null +++ b/doc/img/fail-secure.svg @@ -0,0 +1,4 @@ + + + +
Read VPD
PWD
OK?
Load
startup-config
CFG
OK?
Std. Operating
Load
failure-config
Fail Secure
RMA Mode
CFG
OK?
No
No
Yes
Yes
No
Yes
CFG
AVAIL
?
/run/system.json
Generate
failure-config
copy factory->
startup-config
No
Generate
factory-config
Yes
probe
bootstrap
load
RESET?
rm -rf /cfg
Yes
No
mnt
bootstrap should never fail. If it does we would see it in development.

So if it does, we will start a getty on console so that the developer mode 'root' user can log in and debug.
load may fail in production, so must *never* be allowed to get a login on any front-end (getty, NETCONF, web, SSH, etc.)
 \ No newline at end of file diff --git a/doc/introduction.md b/doc/introduction.md new file mode 100644 index 00000000..1b6743e3 --- /dev/null +++ b/doc/introduction.md @@ -0,0 +1,130 @@ +# Introduction + +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. + +## CLI + +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. + +> Proceed to the [CLI User Guide](cli/tutorial.md). + + +## Key Concepts + +The two modes in the CLI are the admin-exec and the configure context. +When logging in to the system, from the console port or SSH, you land in +admin-exec. Here you can inspect the 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. + +> The [CLI Introduction](cli/introduction.md) can be useful to skim +> through at this point. + +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, if it + does not exist, i.e., only on first boot or after factory reset. + - `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`. + +> See the [Branding & Releases](branding.md) for information on how +> `factory-config` and `failure-config` can be adapted to different +> customer requirements. + + +## 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 the `/cfg` and `/var` file systems, which host the + read-writable data like `startup-config` and container images, the + system checks if it's time for a factory reset. If so it wipes the + contents of these partitions before proceeding + 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[^1] 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` + 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[^2] 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). + +*Fail Secure Mode* is a fail-safe mode provided for debugging the +system. Depending on customer requirements this may be either the +`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. + +The generic default is 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. + +[^1]: YANG is a modeling language from IETF, replacing that used for + SNMP (MIB), used to describe the subsystems and properties of + the system. +[^2]: Return Merchandise Authorization (RMA), i.e., broken beyond repair + by end-user and legible for return to manufacturer.