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:

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 internal

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

The optional config-sync setting will cause any connected external media to automatically sync its configuration and certificate files to the systems internal media. This would be performed during the initial part of the boot process.

This functionality allows for a configuration of the system were 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
example:/boot/#> config-order internal

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. 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-ext/#> read-only
example:/boot/media-ext/#> 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.

Verify Setup

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

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

Media Configuration                                                           
Internal
    Read-only   : Disabled

External
    Read-only   : Disabled
    Timeout     : 30

Bootloader Configuration                                                      
Login Password  : Disabled

Rescue Mode
    Address     : 192.168.2.200
    Netmask     : 255.255.255.0
    Peer        : 192.168.2.1
    Port        : 6000