diff --git a/doc/boot.md b/doc/boot.md index 947affc8..d33717db 100644 --- 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 index 77759d16..1e4c33c9 100644 --- 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 index e5c9b0e0..3086f203 100644 --- 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 deleted file mode 100644 index 31b30c11..00000000 --- a/doc/introduction.md +++ /dev/null @@ -1,152 +0,0 @@ -# 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 Introduction](cli/introduction.md) or [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. - -> 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. - - `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`. - -> 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. - - -## 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[^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` -- 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[^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). - -> Again, please see the [Branding & Releases](branding.md) document for -> how to provide a per-product hard-coded `failure-config` to suit your -> products preferences. - -*Fail Secure Mode* is a fail-safe mode provided for debugging the -system. The default[^3] 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. - -[^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 eligible for return to manufacturer. -[^3]: 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. diff --git a/doc/upgrade.md b/doc/upgrade.md index a44e626a..b481724c 100644 --- 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 index 967061e5..c9fbf103 100644 --- 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