Configuration changes between 1.14 and 1.16
This describes the configuration changes between ESB3024 Router version 1.14 and 1.16
To install ESB3024 Router, one first needs to copy the installation ISO image
to the target node where the router will be run. Due to the way the
installer operates, it is necessary that the host is reachable by
password-less SSH from itself for the user account that will perform the
installation, and that this user has sudo
access.
Prerequisites:
Ensure that the current user has sudo
access.
sudo -l
If the above command fails, you may need to add the user to the
/etc/sudoers
file.
Ensure that the installer has password-less SSH access to localhost
.
If using the root
user, the PermitRootLogin
property of the
/etc/ssh/sshd_config
file must be set to ‘yes’.
The local host key must also be included in the .ssh/authorized_keys
file of the user running the installer. That can be done by issuing the
following as the intended user:
mkdir -m 0700 -p ~/.ssh
ssh-keyscan localhost >> ~/.ssh/authorized_keys
Note! The ssh-keyscan
utility will result in the key fingerprint being
output on the console. As a security best-practice it is recommended to
verify that this host-key matches the machine’s true SSH host key. As an
alternative, to this ssh-keyscan
approach, establishing an SSH connection
to localhost and accepting the host key will have the same result.
Disable SELinux.
The Security-Enhanced Linux Project (SELinux) is designed to add an additional layer of security to the operating system by enforcing a set of rules on processes. Unfortunately out of the box the default configuration is not compatible with the way the installer operates. Before proceeding with the installation, it is recommended to disable SELinux. It can be re-enabled after the installation completes, if desired, but will require manual configuration. Refer to the Red Hat Customer Portal for details.
To check if SELinux is enabled:
getenforce
This will result in one of 3 states, “Enforcing”, “Permissive” or “Disabled”. If the state is “Enforcing” use the following to disable SELinux. Either “Permissive” or “Disabled” is required to continue.
setenforce 0
This disables SELinux, but does not make the change persistent across
reboots. To do that, edit the /etc/selinux/config
file and set the
SELINUX
property to disabled
.
It is recommended to reboot the computer after changing SELinux modes, but the changes should take effect immediately.
Assuming the installation ISO image is in the current working directory,
the following steps need to be executed either by root
user or with sudo
.
Mount the installation ISO image under /mnt/acd
.
Note: The mount-point may be any accessible path, but /mnt/acd
will be
used throughout this document.
mkdir -p /mnt/acd
mount esb3024-acd-router-1.16.0.iso /mnt/acd
Run the installer script.
/mnt/acd/installer
The following steps can be taken to upgrade the router from a 1.10 or later release to 1.16.0. If upgrading from an earlier release it is recommended to first upgrade to 1.10.1 and then to upgrade to 1.16.0.
The upgrade procedure for the router is performed by taking a backup of the configuration, installing the new release of the router, and applying the saved configuration.
With the router running, save a backup of the configuration.
The exact procedure to accomplish this depends on the current method of
configuration, e.g. if confd
is used, then the configuration should be
extracted from confd
, but if the REST API is used directly, then the
configuration must be saved by fetching the current configuration snapshot
using the REST API.
Extracting the configuration using confd
is the recommend approach where
available.
confcli | tee config_backup.json
To extract the configuration from the REST API, the following may be used instead. Depending on the version of the router used, an API-Key may be required to fetch from the REST API.
curl --insecure https://localhost:5001/v2/configuration \
| tee config_backup.json
If the API Key is required, it can be found in the file
/opt/edgeware/acd/router/cache/rest-api-key.json
and
can be passed to the API by setting the value of the X-API-Key
header.
curl --insecure -H "X-API-Key: 1234abcd" \
https://localhost:5001/v2/configuration \
| tee config_backup.json
Mount the new installation ISO under /mnt/acd
.
Note: The mount-point may be any accessible path, but /mnt/acd
will be used
throughout this document.
mkdir -p /mnt/acd
mount esb3024-acd-router-1.16.0.iso /mnt/acd
Stop the router and all associated services.
Before upgrading the router it needs to be stopped, which can be done by typing this:
systemctl stop 'acd-*'
Run the installer script.
/mnt/acd/installer
Migrate the configuration.
Note that this step only applies if the router is configured using
confd
. If it is configured using the REST API, this step is not necessary.
The confd configuration used in the previous versions is not directly compatible with 1.16, and may need to be converted. If this is not done, the configuration will not be valid and it will not be possible to make configuration changes.
The acd-confd-migration
tool will automatically apply any necessary schema
migrations. Further details about this tool can be found at Confd Auto
Upgrade Tool.
The tool takes as input the old configuration file, either by reading the file directly, or by reading from standard input, applies any necessary migrations between the two specified versions, and outputs a new configuration to standard output which is suitable for being applied to the upgraded system. While the tool has the ability to migrate between multiple versions at a time, the earliest supported version is 1.10.1.
The example below shows how to upgrade from 1.10.2. If upgrading from 1.14.0,
--from 1.10.2
should be replaced with --from 1.14.0
.
The command line required to run the tool is different depending on which esb3024 release it is run on. On 1.16.0 it is run like this:
cat config_backup.json | \
podman run -i --rm \
images.edgeware.tv/acd-confd-migration:1.16.0 \
--in - --from 1.10.2 --to 1.16.0 \
| tee config_upgraded.json
After running the above command, apply the new configuration to confd
by
running cat config_upgraded.json | confcli -i
.
If there is a problem running the installer, additional debug information can
be output by adding -v
or -vv
or -vvv
to the installer command, the
more “v” characters, the more detailed output.
This describes the configuration changes between ESB3024 Router version 1.14 and 1.16