WeOS
5.29.0

# External Media HowTo

## Introduction

The use-case in this document covers how to set up the system to use configuration files from external media, e.g. USB or SD-card. It also details how to ensure the configuration is protected from any changes when the system is running, i.e. a read-only mode.

### Directory Layout

In order to boot from an external media it needs to have to correct directory layout, otherwise the system will not be able to obtain the necessary files and will fail-over to a fallback.

The operating system assumes an external media device has the following file system layout:

    /media/
    |- config/
    |  |- config0.cfg                            # Example name
    |  |- startup-config.cfg   --> config0.cfg   # Symlink
    |  `- startup-config.lnk                     # For fat based fs
    |
    `- certs/
       |- aacerts/
       |- cacerts/
       |- certs/
       |- crls/
       |- ocspcerts/
       |- ovpnkeys/
       `- private/

The `startup-config.cfg` file is a symbolic link to the currently active configuration file (or slot), here `config0.cfg`. On file systems like FAT, which do not support symbolic links, a Windows-style `.lnk` file is used instead. The file must be named `startup-config.lnk` and contain the name of the file it refers to, without any leading path component, in this example the text `config0.cfg` followed by an optional newline.

### Populate Media

The media can be set up either offline, on a workstation using the above directory layout, or using the built-in `media sync` feature:

    example:/#> media sync internal external
    Copying files to external media ...

Now we can configure the boot config order to external, when we reboot we will read the configuration file from that media.

If the device is configured to boot using external media and an empty media is used, the media will be populated with factory default files at boot, provided the media is not set to be `read-only`, see more on that below.

## Configuration

This section details how to set up the device to use configuration files from external media. Appropriate fallback methods are also discussed. All available boot configuration options can be found here:

- Boot Configuration Guide

### Configure the systems media definitions

In order for the system to be able to recognise and use any external media device, they need to be defined using the `media` command. This command will allow the user to set up how a media device will be accessed on the device, and to what real physical device and/or partition on said device it will map to. By default two different media definitions exist:

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

A more comprehensive example of how to make external media devices accessible on the system can be seen in the Access External Media Devices howto.

For additional information how to set up a media definition see the `media` command under the Boot Configuration Guide.

### Set Up the Systems Configuration Order

The following commands define the order in which the system will attempt to obtain its startup configuration file.

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

If an external media cannot be found the system will use the internal startup-config. Which can be useful to trigger a fail-over in case the external media is missing or damaged.

If the `config-order` setting only contains `external` and no media can be found, the system will trigger an alarm and start with the configured fallback:

    example:/boot/#> config-fallback failsafe

The fail-safe option configured here starts the system with the `safe-config` configuration. Other fallback alternatives are: `factory` which uses the `factory-config` configuration, `none` which uses the `no-config` configuration, or `reboot` which causes the device to reboot until any of the media in `config-order` can be accessed.

### Sync Configuration Files to Internal Media

The optional `config-sync` setting will when enabled automatically sync its configuration and certificates files to the systems built-in flash, represented by the `internal` media definition. The `config-sync` setting requires the user to provide the name of the external media to sync from. This action will then be performed during the initial part of the boot process.

This functionality allows for a configuration of the system where the external media would only need to be inserted once during the initial deployment. The easiest way to configure the system to act in this manner, can be achieved like this:

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

Utilizing this setup would cause the system to copy any existing configuration from any inserted external media to the internal media, during the next reboot. It has also been configured with the `config-order` set to `internal:startup`. Therefore, the system will boot from the internal configuration, that now is the transferred configuration from the external media.

If the external media now is removed, the next time the system boots it will still boot according to the configuration defined by the `config-order` setting. Regardless if the `config-sync` flag is still set or not, this setting only cares about transferring the files, not how the system will actually boot.

### Read-only Media

Set up any external media to be read only when booting:

    example:/boot/#> media external
    example:/boot/media-external/#> read-only
    example:/boot/media-external/#> end
    example:/boot/#>

Note: when a media has been configured read-only it must have the appropriate files present on the media, since no new information can be written to it when it has booted. This includes certificate files as well.

Note

The system does not allow any executable files, located on mounted external media, to be executed.

### Customize Special Configuration Files

When defining the systems configuration order using the `config-order` command a media and a mode/file is always specified. The configuration files that are applied by the system in this case have a default that will be applied, unless the user override these. These are the names of the files mapped against the file/mode and the intended usage of their default files:

Mode/File | Corresponding Config File | Intended Usage
--- | --- | ---
startup | startup-config.cfg | The normal startup configuration file of the system. This file is always updated anytime confiugration changes are saved normally on the device.
factory | factory-config.cfg | This configuration file contains the factory default configuration. Using this mode will cause the system to boot as if it were in its original factory state.
none | no-config.cfg | This configuration file is intended to be as the name indicates, as a no config. The default file will ensure that the system is started with ecentially no services enabled and all the ports of the device will be configured disabled. Hence, the device will only be accessible with a console connection.
safe | safe-config.cfg | This configuration file is intended to start the system in a safe state, where each port on the device will be individually separated from the rest. Each of these port interfaces will have DHCP enabled on them so that it is possible to assign them an IP address to make the device accessible. This so that the device should be recovrable since the user should be able to provide it with an accessible IP address.
net | net-config.cfg | This configuration file is applied on the system when it enters net boot mode. During the net boot process the device enters a special state where this configuration is applied in order to bring the system to a point where it is possible for it to obtain is startup configuration remotely. The default file will ensure that the device asks for a DHCP address on each port, independent of each other. Since it could be possible that the DHCP server is located on any of the ports, we need to send a discover on all of them.

In order to override these files it is possible to add a replacement manually in the intended configuration folder on the intended boot media. The folder structure was described earlier in this document. The replacement file simply needs to have the same name as the built-in default files described above. Anytime a replacement file is present on the selected configuration media, it will be used instead of the built-in default.

This could be especially useful for the net boot configuration file `net-config.cfg`, when the method of obtaining the configuration file needs to be more specific. Considering the default mentioned above, a DHCP discover will be sent on every port on the device. If you for instance want the initial discover to be sent on only a particular port, this could be achieved by adding an override version of the `net-config.cfg` under the configuration folder of the selected media.

### Verify Setup

In order to see if the boot configuration looks like intended:

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

    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

« Previous Next »