peter/infix
1
0
Fork 0
mirror of https://github.com/kernelkit/infix.git synced 2026-08-06 23:43:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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 <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2025-07-30 14:58:14 +02:00
parent dc8fc40002
commit 5b100fb99e
6 changed files with 165 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/boot.md
+83
View File
@@ -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
doc/branding.md
+1 -1
View File
@@ -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
doc/index.md
+79
View File
@@ -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.
doc/introduction.md
-152
View File
@@ -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.
doc/upgrade.md
+1 -1
View File
@@ -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
mkdocs.yml
+1 -2
View File
@@ -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