WeOS
5.29.0

# 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:

- Config From External Media
- Access External Media Devices
- Bootstrap System Configuration Over the Network
- Bootstrap System Configuration Using DHCP
- Secure Boot Configuration using unlocking tokens

## 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.

  Note

  If configuration is loaded from external media or netboot, the incoming configuration can bypass input validation.

  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.

    - `factory:` This option will cause the system to boot using the factory default 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 behaviour, refer to this page and section.

Note

‘cert-order’ External should only be used to increase the available space for certificates. Any private keys that are uploaded to the device will be no be readable by other devices if the Media is transferred.

`[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|factory|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 behaviour, refer to this page and section.

  factory

    This option will cause the system to boot using the factory default configuration file factory-config.cfg.

    The major difference between this and simply using the `factory` 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 behaviour, 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 behaviour, 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
    Media definition name. Maximum length is 32 characters. Only alphanumeric characters and the special characters underscore (_) and dash (-) are allowed.
`[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
      behaviour 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.
`boot-integrity restore`
  Restores a boot configuration integrity violation. This feature protects the bootloader configuration. Note: If downgrading to a version before this feature, and then under ‘/boot’ menu modifies configuration this will result in a integrity violation after an upgrade.

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

    Boot configuration integrity
        Status          : OK

« Previous Next »