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