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

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:

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