Installing a 1.22 release

How to install and upgrade to ESB3024 Router release 1.22.x

To install ESB3024 Router, you first need 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 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 ssh access to localhost.
If using the root user, the PermitRootLogin property of the /etc/ssh/sshd_config file must be set to ‘yes’.
Ensure that sshpass is installed.
If the installer is run by the root user, this step is not necessary.
sshpass is installed by typing this:
```
sudo dnf install -y sshpass
```

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.22.0.iso /mnt/acd
```
Run the installer script.
```
/mnt/acd/installer
```
If it is not running as root, the installer will ask both for the “SSH password” and the “BECOME password”. The “SSH password” is the password that the user running the installer uses to log in to the local machine, and the “BECOME password” is the password for the user to gain sudo access. They are usually the same.

Upgrading From an Earlier ESB3024 Router Release

The following steps can be taken to upgrade the router from a 1.10 or later release to 1.22.0. If upgrading from an earlier release it is recommended to first upgrade to 1.10.1 and then to upgrade to 1.22.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.22.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
```
Please note that the installer will install new container images, but it will not remove the old ones. The old images can be removed manually after the upgrade is complete.
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.22, 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.20.1. If upgrading from 1.18.0, --from 1.20.1 should be replaced with --from 1.18.0.
The command line required to run the tool is different depending on which esb3024 release it is run on. On 1.22.0 it is run like this:
```
cat config_backup.json | \
  podman run -i --rm \
  images.edgeware.tv/acd-confd-migration:1.22.0 \
  --in - --from 1.20.1 --to 1.22.0 \
  | tee config_upgraded.json
```
After running the above command, apply the new configuration to confd by running cat config_upgraded.json | confcli -i.

Troubleshooting

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.

Configuration changes between 1.20 and 1.22

This describes the configuration changes between ESB3024 Router version 1.20 and 1.22