infix/doc/introduction.md

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.

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 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 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 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. 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¹ 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² 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³ 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. ↩︎