doc: add system Introduction about *-config and failure modes

Fixes #360

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

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**

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.