System Bootstrap

Introduction

How a system boots is important to how it will actively operate. This document presents available options that govern system bootstrap.

The main aspects that are configured in this context is where the system will obtain its configuration file from and where it will access various certificates. Any external media device that should be usable on the device needs to be defined in this context.

In addition, this context provides information about the secure boot status. Secure boot is a mechanism that verifies the integrity of code before allowing it to execute during system startup. It prevents unauthorized or malicious code from compromising the boot process. The chain of trust is a sequence of steps that collectively establish trust in the system. It ensures the integrity of the software. The trust chain starts from a foundational element called the root of trust. Throughout this documentation, the term hardware anchor is used. In simple terms, the hardware anchor indicates that trusted and immutable code residing within the processor validates signatures of the subsequent code layers. Essentially, the root of trust resides within the hardware itself.

For additional information and example use-cases see:

Usage of External Media Devices

SD-card and USB memory sticks are supported external storage types. Availability depends on the product make and model, not all products support all types of media.

The SD-card has higher priority than USB memory sticks. Meaning, if both an SD-card and a USB memory stick is present, the SD-card will be used.

Note

SD-cards must to be inserted before boot to be detected. Hot-plugging is not supported. USB memory sticks have hot-plug support and will be made available to the system, provided no SD-card is present.

The system will also handle partitions that may be present on an external media device. In the case of partitions, each individual one will be treated as a separate media definition in the system.

Any external media device that is intended to be used, for any purpose, on the device needs to be specified in the boot configuration context. These definitions dictate how the physical media should be matched and represented on the device. If this is not done the external media device will not be mounted and accessible to the user.

Configuration

This is the top level configuration in the boot context.

example:/#> boot
example:/boot/#>
[no] config-sync [FROM-MEDIA]

Enable automatic sync of configuration and certificates from external media to built-in flash before system bootstrap is completed.

With this feature the system can be set up to copy files from an external media device (e.g. USB, SD-Card) to built-in flash (internal) before booting up the system with built-in flash. I.e., the external media device would only need to be inserted once at deployment.

The target media cannot be changed, it will always be the internal media definition.

Default: Disabled.

no
Disable the automatic sync.
FROM-MEDIA
The media from which to sync from. Medias are configured and set up using the media command.
[no] config-order [MEDIA:TYPE] [, MEDIA:TYPE [, ...]]

Define the system boot configuration order. At startup the config-order is traversed in order, the first config option to be successfully applied will be used.

The config-order is specified with a media and file/mode to use. Multiple options can be specified. The specified media is what the system will attempt to mount when bootstrapping the system.

Note

If an external media is specified (i.e. not internal), the configuration files must be located on the external media. It will not use any builtin default files in the same manner as an internal configuration would.

If no more options exist, the config-fallback will be used.

Default: internal:startup.

example:/boot/#> config-order external:startup, internal:startup

no
Reset to the default config-order : internal:startup.
MEDIA

Dynamically created using the media command. Use the show command in the current context or show media to list all existing media definitions. In addition, two default media definitions exist:

  • internal: The representation of the built-in flash. This cannot be changed or removed.

  • external: The default media definition for any connected external media device (e.g. USB, SD-Card). It is configured to always match the first partition on said external media device. This definition is not static or locked, it can be freely adjusted by the user, even removed.

TYPE

The specific type of configuration file to be used or a specific mode of obtaining said file. The following options are valid selections:

  • startup: This option will cause the system to boot using the standard startup configuration file.

  • none: This option will cause the system to boot in a blank state, or a no configuration mode, using the special configuration file no-config.cfg. In this state essentially no services will be enabled on the device and all ports will be disabled. The only access to the device will be using a console connection.

  • safe: This option will cause the system to boot in a safe state, using the special configuration file safe-config.cfg. In this state basic services will be enabled so that the device can easily be made accessible. In addition, all port interfaces on the device will be separated from each other and be configured as a DHCP client. This will allow a user to easily provide the device with an IP address so that the device can be made accessible with, for instance, WEB and SSH.

  • net: This option will cause the system to boot in net configuration mode. In this mode the device will attempt to obtain a startup configuration file over the net (e.g. DHCP).

Tip

For a more detailed description on these configuration files that the system uses to achieve this, and how to potentially override them with custom behavior, refer to this page and section.

[no] cert-order [MEDIA] [, MEDIA [, ...]]

Define the system boot certificate order.

The certificate order is specified by a media indicating where to locate the certificates. Multiple options can be specified, if one fails the next in the order will be used.

Note

A “hidden” option will always exist as the last resort, and that will be the internal flash definition (internal).

Default: internal.

no
Reset to the default cert-order : internal.
MEDIA

Dynamically created using the media command. Use the show command in the current context or show media to list all existing media definitions. In addition, two default media definitions exist:

  • internal: The representation of the built-in flash. This cannot be changed or removed.

  • external: The default media definition for any connected external media device (e.g. USB, SD-Card). It is configured to always match the first partition on said external media device. This definition is not static or locked, it can be freely adjusted by the user, even removed.

[no] config-fallback [reboot|failsafe|none]

Specify the fallback option to config-order. The configured action is taken only if the above config-order fails. Should this happen an alarm is also triggered in the system.

Default: failsafe.

no
Reset to the default fallback, safe.
reboot
If this option is used the device will simply restart if the fallback is reached.
failsafe

This option will cause the system to boot in a safe state, using the special configuration file safe-config.cfg. In this state basic services will be enabled so that the device can easily be made accessible. In addition, all port interfaces on the device will be separated from each other and be configured as a DHCP client. This will allow a user to easily provide the device with an IP address so that the device can be made accessible with, for instance, WEB and SSH.

The major difference between this and simply using the safe mode in a config-order entry, is that this is an error state. In addition, an alarm will also be triggered, indicating that the system booted on its fallback.

Tip

For a more detailed description on the special configuration file that the system uses the achieve this, and how to potentially override it with custom behavior, refer to this page and section.

none

This option will cause the system to boot in a blank state, or a no configuration mode, using the special configuration file no-config.cfg. In this state essentially no services will be enabled on the device and all ports will be disabled. The only access to the device will be using a console connection.

The major difference between this and simply using the none mode in a config-order entry, is that this is an error state. In addition, an alarm will also be triggered, indicating that the system booted on its fallback.

Tip

For a more detailed description on the special configuration file that the system uses the achieve this, and how to potentially override it with custom behavior, refer to this page and section.

[no] media NAME

Create and manage media mapping definitions.

Specify the media devices that should be recognised by the system and be made available to the user. The media definitions that are defined here dictate how any external media device (e.g. USB, SD-Card) will be mapped and accessible on the rest of the system.

Each individual media definition require a specific ‘match’ rule that specify how a physical media will be linked to the media definition. This allows the user to match not only a specific external media device as a whole, but individual partitions that may exist on it as well. A media definition can be matched based on the following information:

  • Partition number: Used to indicate a match based on a specific partition number on the physical media device. If no partitions exist on the device, that will count as a match for partition 1 (The first).

  • Label: Used to indicate a match based on a specific label possibly present on the physical media device.

Currently it is only possible to create media definitions for external media devices that are connected. Hence, it is not possible to create any media definitions for internal memory on the built-in flash. The built-in flash is currently entirely represented by the special media definition internal. This is a definition that cannot be changed or removed by the user.

An external media device will only be accessible on the system if a matching media definition exist. In other words, if no match exist the device will not be mounted on the system whatsoever.

If a match cannot be made, this media will simply not be present, no error will occur because a specific match cannot be made.

Default: By default two different media definitions will be present:

  • internal: Special definition and representation of the built-in flash, this media definition cannot be changed or removed.

  • external: Base definition aimed to match the first partition located on any connected external physical media. If no partitions exist on the device this will also be a match in that case.

no
Resets all media definitions back to the defaults.
NAME
The name of the media definition in free form text.
[no|show] net

Enter a sub-configuration context handling net boot configuration options.

no
Resets all net specific settings to its defaults.
[no|show] loader

Enter the configuration context for the boot-loader, reset boot-loader settings to default, or show current settings.

no
Resets all boot-loader settings.

Media Settings

The media configuration is a sub-context of the boot configuration context.

Note

It is currently not possible to perform any changes to internal media definition. Any other media definition can be freely changed in any way the user wants.

example:/#> boot
example:/boot/#> media external
example:/boot/media-external/#>
[no] match [label NAME] | [partition NUMB]

Set a match rule specifying how the media will be identified.

The match rule specify how a physical device (e.g. USB, SD-Card) will be linked to the media definition.

Note

Currently the match rule cannot specify a specific external media connection port, it will operate based on the device that is connected. If a device has the possibility to connect more than one external media device (Both a USB device and a SD-Card) it cannot be guaranteed which one will be selected, but in general the SD-Card will be preferred.

However, it is safest to currently only have a maximum of one external media device connected, in order to ensure that the behavior will be deterministic.

example:/boot/media-external/#> match partition 1
example:/boot/media-external/#> match label my-device-label

no
A match rule must always exist for a media definition. Therefore, it cannot be removed, it can only be changed.
partition
Used to indicate a match based on a specific partition number on the physical media device. If no partitions exist on the device, that will count as a match for partition 1 (The first).
label
Used to indicate a match based on a specific label possibly present on the physical media device.
[no] read-only

Enable, or disable read-only mode.

Default: Disabled.

no
Disables read-only.
[no] timeout [1-60]

Set the media timeout, how long to wait for external media to “wake up” at power-on. Some USB stick controllers can take up to 30 sec. to start up.

Default: 30 seconds.

no
Resets the timeout to its default, 30 seconds.

Net Settings

Net configuration is a sub-context in the boot configuration.

example:/#> boot
example:/boot/#> net
example:/boot/net/#>
[no] sync

Sync any configuration file, obtained with the net boot mode, to the startup configuration file of the selected boot media.

The media that the obtained configuration file will be synced to is determined by the media selected in association with the net mode in the config-order. A few examples of this:

  • internal:net: Sync the obtained configuration to the startup config located on the built-in flash.

  • external:net: Sync the obtained configuration to the startup config located on the external media device specified by the media definition external.

Default: Disabled.

no
Disable sync.
[no] mode [dhcp]

Net boot mode to use if configured in the config-order.

Default: dhcp.

no
Resets to its default.
dhcp
Use DHCP option 66 and 67 to retrieve server location and the name of the configuration file to download and apply.
[no] timeout [0|1-2147483647]

Timeout, in seconds, for how long to attempt a net boot. When the timer expires, the next option in the config-order will be attempted.

If the timeout is set to 0, the timeout will be infinite.

Default: 300.

no
Reset to the default value.
[no] clientid [STRING]

Client ID to be used in the DHCP Discover message. This can be used to specify to the DHCP server any specific configuration file that this device wants.

Default: None.

no
Remove any configured Client ID.
STRING
A free form string, with a maximum length of 64 characters.
[no] accept-first-lease

Enable to always accept the first DHCP lease received.

When this setting is enabled the DHCP boot handling will accept the first lease that it receives. What accept entails depends on the contents of the received DHCP lease, the following two cases exist:

  1. If the DHCP lease contains boot information (option 66/67), an attempt to download the config will be performed as normal.

  2. If the DHCP lease contains NO boot information (option 66/67), the bootstrap process will directly continue to the next option specified in the boot config-order, or if no other option exist go to the config-fallback.

Default: Disabled.

no
Disable sync.
[no] password [STRING]

A password may be used to secure login during net boot when the console is accessible.

If left blank the net boot password will be the factory defaults until a the user configuration is received.

Default: None.

no
Remove any configured Password
STRING
A free form string, with a maximum length of 64 characters.

Boot-loader Settings

Boot-loader configuration is a sub-context in the boot configuration.

example:/#> boot
example:/boot/#> loader
example:/boot/loader/#>
[no] login password|hash STRING

Set the bootloader password.

no
Disable password.
STRING
The string representation of the password.
[no] rescue-address IPADDR

Set the rescue mode (netconsole) IP address.

Parameters

no
Reset the setting to its default value, 192.168.2.200.
IPADDR
IP address in standard quad-dotted notation, e.g. 192.168.1.1.
[no] rescue-netmask NETMASK

Set the rescue mode (netconsole) netmask.

no
Reset the setting to its default value, 225.255.255.0.
NETMASK
Size of the net in quad-dotted format, e.g. 255.255.255.0.
[no] rescue-port PORT

Set the rescue mode (netconsole) UDP port.

no
Reset the setting to its default value, 6000.
PORT
Port number in range 1-65535.
[no] rescue-peer IPADDR

Set the rescue mode (netconsole) peer IP.

no
Reset the setting to its default value, 192.168.2.1.
IPADDR
IP address in standard quad-dotted notation, e.g. 192.168.1.1.
[no] allow-untrusted

Set allow untrusted for non hardware-anchored machines. This disables the OS signature check. It’s recommended to leave this at the default value.

no
Reset the setting to its default value, re-enabling the OS signature check for non hardware-anchored machines. This setting has no effect on hardware-anchored machines.
[no] unlock-license [VFS-uri]

Set a cryptographic unlock license for hardware anchored machines. This disables the OS signature check. It’s recommended to leave this at the default value.

no
Reset the setting to its default value, re-enabling the OS signature check for hardware-anchored machines. This setting has no effect on non hardware-anchored machines.

Status

The currently configured boot settings can be viewed form the top level in the CLI:

example:/#> show boot
Bootstrap Configuration                                                       
Config-sync     : Disabled
Config-fallback : failsafe

Config order                                                                  
#  MEDIA                      MODE                                            
1  internal                   startup


Certificate order                                                             
#  MEDIA                                                                      
1  internal


Media Configuration                                                           
#  NAME                       R/O  TIMEOUT  MATCH                             
1  internal                   No   -------  System Internal
2  external                   No   30       Partition number: 1

Net Configuration                                                             
Sync            : Disabled
Timeout         : 300
Mode            : dhcp
Client ID       :

Bootloader Configuration                                                      
Login Password  : Disabled

Rescue Mode
    Address     : None
    Netmask     : None
    Peer        : None
    Port        : -2

Secure boot status
    Hardware anchor : Disabled
    Secure OS boot  : Enforce signed

Secure boot control
    Allow untrusted : Disabled