mirror of
https://github.com/kernelkit/infix.git
synced 2026-07-29 04:03:01 +02:00
Joachim Wiberg
817ec4675b
That factory-config and failure-config can be overridden by customer specific requirements is documented in the branding document. Focus on Infix native defaults in general documentation. Move most of customer specifics to foot note. Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
139 lines
6.2 KiB
Markdown
139 lines
6.2 KiB
Markdown
# 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.
|
|
|
|
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). To enter the
|
|
CLI 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`.
|
|
|
|
> 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.
|
|
|
|
|
|
|
|
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`
|
|
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. The default[^3] 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 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.
|