This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation

How to install and upgrade ESB3024 Router

1: Installing a 1.16 release

1.1: Configuration changes between 1.14 and 1.16

2: Installing a 1.14 release

2.1: Configuration changes between 1.12.1 and 1.14

3: Installing a 1.12 release

3.1: Configuration changes between 1.10.2 and 1.12

4: Installing release 1.10.x

4.1: Configuration changes between 1.8.0 and 1.10.x

5: Installing release 1.8.0

5.1: Configuration changes between 1.6.0 and 1.8.0

6: Installing release 1.6.0

6.1: Configuration changes between 1.4.0 and 1.6.0

1 - Installing a 1.16 release

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

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
```

Upgrade from and earlier ESB3024 Router release

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.

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.

1.1 - Configuration changes between 1.14 and 1.16

This describes the configuration changes between ESB3024 Router version 1.14 and 1.16

Confd configuration changes

Below are the changes to the confd configuration between versions 1.14 and 1.16 listed.

Added `region` GeoIP classifier

Classifiers of type geoip now have a region property.

Added `integration.routing.gui` configuration

There is now an integration.routing.gui section which will be used by the GUI.

Added `services.routing.accounts` configuration

The services.routing.accounts list has been added to the configuration.

2 - Installing a 1.14 release

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

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.14.0.iso /mnt/acd
```
Run the installer script.
```
/mnt/acd/installer
```

Upgrade from and earlier ESB3024 Router release

The following steps can be used to upgrade the router from a 1.10 or 1.12 release to 1.14.0. If upgrading from an earlier release it is recommended to first upgrade to 1.10.1 in multiple steps; for instance when upgrading from release 1.8.0 to 1.14.0, it is recommended to first upgrade to 1.10.1 and then to 1.14.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.14.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.14, 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.12.0, --from 1.10.2 should be replaced with --from 1.12.0.
The command line required to run the tool is different depending on which esb3024 release it is run on. On 1.14.0 it is run like this:
```
cat config_backup.json | \
  podman run -i --rm \
  images.edgeware.tv/acd-confd-migration:1.14.0 \
  --in - --from 1.10.2 --to 1.14.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

2.1 - Configuration changes between 1.12.1 and 1.14

This describes the configuration changes between ESB3024 Router version 1.12.1 and 1.14.x

Confd configuration changes

Below are the changes to the confd configuration between versions 1.12.1 and 1.14.x listed.

Renamed `services.routing.settings.allowedProxies`

The configuration setting services.routing.settings.allowedProxies has been renamed to services.routing.settings.trustedProxies.

Added `services.routing.tuning.general.restApiMaxBodySize`

This parameter configures the maximum body size for the REST API. It mainly applies to the configuration, which sometimes has a large payload size.

3 - Installing a 1.12 release

How to install and upgrade to ESB3024 Router release 1.12.0 and 1.12.1

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 its 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-esb3024-1.12.1.iso /mnt/acd
```
Run the installer script.
```
/mnt/acd/installer
```

Upgrade from ESB3024 Router release 1.10

The following steps can be used to upgrade the router from a 1.10 release to 1.12.0 or 1.12.1. If upgrading from an earlier release it is recommended to perform the upgrade in multiple steps; for instance when upgrading from release 1.8.0 to 1.12.1, it is recommended to first upgrade to 1.10.1 or 1.10.2 and then to 1.12.1.

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-esb3024-1.12.1.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 1.10 versions is not directly compatible with 1.12, 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.
To help with migrating the configuration, a new tool has been included in the 1.12.0 release, which will automatically apply any necessary schema migrations. Further details about this tool can be found here. Confd Auto Upgrade.
The confd-auto-upgrade 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.10.1, --from 1.10.2 should be replaced with --from 1.10.1.
The command line required to run the tool is different if it is run on esb3024-1.12.0 or esb3024-1.12.1. On 1.12.1 it is run like this:
```
cat config_backup.json | \
  podman run -i --rm \
  images.edgeware.tv/auto-upgrade-esb3024-1.12.1-master:20240702T151205Z-f1b53a98f \
  --in - --from 1.10.2 --to 1.12.1 \
  | tee config_upgraded.json
```
On esb3024-1.12.0 it is run like this:
```
cat config_backup.json | \
  podman run -i --rm \
  images.edgeware.tv/auto-upgrade-esb3024-1.12.0:20240619T154952Z-2b72f7400 \
  --in - --from 1.10.2 --to 1.12.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

3.1 - Configuration changes between 1.10.2 and 1.12

This describes the configuration changes between ESB3024 Router version 1.10.2 and 1.12.0/1.12.1.

Confd configuration changes

Below are the major changes to the confd configuration between versions 1.10.2 and 1.12.0/1.12.1. Note that there are no configuration changes between versions 1.12.0 and 1.12.1, so the differences apply to both.

Added `services.routing.translationFunctions.hostRequest`

A new translation function has been added which will allow custom Lua code to modify requests to backend hosts before they are sent.

Added `services.routing.translationFunctions.session`

A new translation function has been added which will allow custom Lua code to be executed after the router has made the routing decision but before generating the redirect URL.

An example use case would be for enabling instream sessions, which can be done by setting this value to return set_session_type('instream').

Removed `services.routing.settins.managedSessions` configuration

This configuration is no longger used.

Added `services.routing.tuning.general.maxActiveManagedSessions` tuning parameter.

This parameter configures the maximum number of active managed sessions.

4 - Installing release 1.10.x

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

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 its 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-esb3024-1.10.1.iso /mnt/acd
```
Run the installer script.
```
/mnt/acd/installer
```

Upgrade from ESB3024 Router release 1.8.0

The following steps can be used to upgrade the router from release 1.8.0 to 1.10.x. If upgrading from an earlier release it is recommended to perform the upgrade in multiple steps; for instance when upgrading from release 1.6.0 to 1.10.x, it is recommended to first upgrade to 1.8.0 and then to 1.10.x.

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-esb3024-1.10.1.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 version 1.8.0 is not directly compatible with 1.10.x, 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.
To determine if the configuration needs to be converted, confcli can be run like below. If it prints error messages, the configuration needs to be converted. If no error messages are printed, the configuration is valid and no further updates are necessary.
```
confcli | head -n5
[2024-04-02 14:48:37,155] [ERROR] Missing configuration key /integration
[2024-04-02 14:48:37,162] [ERROR] Missing configuration key /services/routing/settings/qoeTracking
[2024-04-02 14:48:37,222] [ERROR] Missing configuration key /services/routing/hostGroups/convoy-rr/hosts/convoy-rr-1/healthChecks
[2024-04-02 14:48:37,222] [ERROR] Missing configuration key /services/routing/hostGroups/convoy-rr/hosts/convoy-rr-2/healthChecks
[2024-04-02 14:48:37,242] [ERROR] Missing configuration key /services/routing/hostGroups/e-dns/hosts/linton-dns-1/healthChecks
{
   "integration": {
      "convoy": {
            "bridge": {
               "accounts": {
```
If error messages are printed, the configuration needs to be converted. If the configuration was saved in the file config_backup.json, the conversion can be done by typing this at the command line:
```
sed -E -e '/"hosts":/,/]/ s/([[:space:]]+)("hostname":.*)/\1\2\n\1"healthChecks": [],/' -e '/"apiKey":/ d' config_backup.json | \
curl -s -X PUT -T - -H 'Content-Type: application/json' http://localhost:5000/config/__active/
```
```
systemctl restart acd-confd
```
This adds empty healthChecks sections to all hosts and removes the apiKey configuration. After that, acd-confd is restarted. See Configuration changes between 1.8.0 and 1.10.x for more details about the configuration changes.
Migrating configuration to esb3024-1.10.2
When upgrading to version 1.10.2, an extra step is required to migrate the consistent hashing configuration. This step is necessary both when upgrading from an earlier 1.10 release and when upgrading from older versions. It is only needed if consistent hashing was configured in the previous version.
To determine if consistent hashing was configured, execute the following command:
```
confcli | head -n2
[2024-05-31 09:43:55,932] [ERROR] Missing configuration key /services/routing/rules/constantine/hashAlgorithm
{
    "integration": {
```
If an error message about a missing configuration key appears, the configuration must be migrated. If no such error message appears, this step should be skipped.
To migrate the configuration, execute the following command at the command line:
```
curl -s http://localhost:5000/config/__active/ | \
sed -E 's/(.*)("type":.*"consistentHashing")(,?)/\1\2,\n\1"hashAlgorithm": "MD5"\3/' | \
curl -s -X PUT -T - -H 'Content-Type: application/json' http://localhost:5000/config/__active/
```
This command will read the current configuration, add the hashAlgorithm configuration key, and write back the updated configuration.
Remove the Account Monitor container
Older versions of the router installed the Account Monitor tool. This was removed in release 1.8.0, but if it is still present and unused, it can be removed by typing:
```
podman rm account-monitor
```
Remove the confd-transformer.lua file
After installing or upgrading to 1.10.x, ensure that the confd-transformer.lua script located in /opt/edgeware/acd/router/lib/standard_lua directory is removed.
This file contains deprecated Lua language definitions which will override newer versions of those functions already present in the ACD Router’s Lua Standard Library. When upgrading beyond 1.10.2, the installer will automatically remove this file, however for this particular release, it requires manual intervention.
```
rm -f /opt/edgeware/acd/router/lib/standard_lua/confd-transformer.lua
```
After removing this file, it will be necessary to restart the router to flush the definitions from the router’s memory:
```
systemctl restart acd-router
```

Troubleshooting

4.1 - Configuration changes between 1.8.0 and 1.10.x

This describes the configuration changes between ESB3024 Router version 1.8.0 and 1.10.x.

Confd configuration changes

Below are the major changes to the confd configuration between version 1.8.0 and 1.10.x listed.

Added `integration.convoy` section

An integration.convoy section has been added to the configuration. It is currently used for configuring the Convoy Bridge service.

Removed `services.routing.apiKey` configuration

The services.routing.apiKey configuration key has been removed. This was an obsolete way of giving the configuration access to the router. The key has to be removed from the configuration when upgrading, otherwise the configuration will not be accepted.

Added `services.routing.settings.qoeTracking`

A services.routing.settings.qoeTracking section has been added to the configuration.

Added `healthChecks` sections to the hosts

The hosts in the hostGroup entries have been extended with a healthChecks key, which is a list of functions that determine if a host is in good health.

For example, a redirecting host might look like this after the configuration has been updated:

{
    "services": {
        "routing": {
            "hostGroups": [
                {
                    "name": "convoy-rr",
                    "type": "redirecting",
                    "httpPort": 80,
                    "httpsPort": 443,
                    "forwardHostHeader": true,
                    "hosts": [
                        {
                            "name": "convoy-rr-1",
                            "hostname": "convoy-rr-1",
                            "ipv6_address": "",
                            "healthChecks": [
                                "health_check('convoy-rr-1')"
                            ]
                        }
                    ]
                }
            ],

Added `hashAlgorithm` to the `consistentHashing` rule

In esb3024-1.10.2 the consistentHashing routing rule has been extended with a hashAlgorithm key, which can have the values MD5, SDBM and Murmur. The default value is MD5.

5 - Installing release 1.8.0

How to install and upgrade to ESB3024 Router release 1.8.0

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 its 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
```
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-esb3024-1.8.0.iso /mnt/acd
```
Run the installer script.
```
/mnt/acd/installer
```

Upgrade

The upgrade procedure for the router is performed by taking a backup of the configuration, installing the new version 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.2.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 version 1.6.0 is not directly compatible with 1.8.0, and may need to have a few minor manual updates in order to be valid. If this is not done, the configuration will not be valid and it will not be possible to make configuration changes.
To determine if the configuration needs to be manually updated, confcli can be run like below. If it prints error messages, the configuration needs to be updated. If no error messages are printed, the configuration is valid and no further updates are necessary.
```
confcli services.routing | head
[2024-02-01 19:05:10,769] [ERROR] Missing configuration key /services/routing/hostGroups/convoy-rr/forwardHostHeader
[2024-02-01 19:05:10,779] [ERROR] Missing configuration key /services/routing/hostGroups/e-dns/forwardHostHeader
[2024-02-01 19:05:10,861] [ERROR] 'forwardHostHeader'
```
If error messages are printed, a forwardHostHeader configuration needs to be added to the hostGroups configuration. This can be done by running this at the command line:
```
curl -s http://localhost:5000/config/__active/ | \
sed -E 's/([[:space:]]+)"type": "(host|redirecting|dns)"(,?)/\1"type": "\2",\n\1"forwardHostHeader": false\3/' | \
curl -s -X PUT -T - -H 'Content-Type: application/json' http://localhost:5000/config/__active/
```
This reads the active configuration from the router, adds the “forwardHostHeader” configuration to all host groups, and then sends the updated configuration back to the router.
See Configuration changes between 1.6.0 and 1.8.0 for more details about the configuration changes.
Remove the Account Monitor container
Previous versions of the router installed the Account Monitor tool. This is no longer included, but since the previous version installed, there will be a stopped Account Monitor container. If it is not used, the container can be removed by typing:
```
podman rm account-monitor
```

Troubleshooting

5.1 - Configuration changes between 1.6.0 and 1.8.0

This describes the configuration changes between ESB3024 Router version 1.6.0 and 1.8.0.

Confd configuration changes

Below are some of the configuration changes between version 1.4.0 and 1.6.0 listed. The list only contains the changes that might affect already existing configuration, enirely new items are not listed. Normally nothing needs to be done about this since they will be upgraded automatically, but they are listed here for reference.

Added `enabled` to `contentPopularity`

An enabled key has been added to services.routing.settings.contentPopularity. After the key has been added, the configuration looks like this:

{
    "services": {
        "routing": {
            "settings": {
                "contentPopularity": {
                    "enabled": true,
                    "algorithm": "score_based",
                    "sessionGroupNames": []
                },
                ...

Added `selectionInputItemLimit` to `tuning`

A selectionInputItemLimit key has been added to services.routing.tuning.general. After the key has been added, the configuration looks like this:

{
    "services": {
        "routing": {
            "tuning": {
                "general": {
                    ...
                    "selectionInputItemLimit": 10000,
                    ...

Added `forwardHostHeader` to `hostGroups`

All three hostGroup types (host, redirecting and dns) have been extended with a forwardHostHeader key. For example, a redirecting host might look like this after the change:

{
    "services": {
        "routing": {
            "hostGroups": [
                {
                    "name": "convoy-rr",
                    "type": "redirecting",
                    "httpPort": 80,
                    "httpsPort": 443,
                    "forwardHostHeader": true,
                    "hosts": [
                        {
                            "name": "convoy-rr-1",
                            "hostname": "convoy-rr-1",
                            "ipv6_address": ""
                        }
                    ]
                }
            ],
            ...

REST API configuration changes

The following items have been added to the REST API configuration. They will not need to be manually updated, the router will add the new keys with default values. Note that this is not a complete list of all changes, it only contains the changes that will be automatically added when upgrading the router.

If the router is configured via confd and confcli, these changes will be applied by them. This section is only relevant if the router is configured via the v2/configuration API.

Added the session_translation_function key.
Added the tuning.selection_input_item_limit key.

6 - Installing release 1.6.0

How to install and upgrade to ESB3024 Router release 1.6.0

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 its 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
```
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-esb3024-1.8.0.iso /mnt/acd
```
Run the installer script.
```
/mnt/acd/installer
```

Upgrade

The upgrade procedure for the router is performed by taking a backup of the configuration, installing the new version 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.2.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.
See Configuration changes between 1.4.0 and 1.6.0 for instructions on how to migrate the configuration to release 1.6.0.

Troubleshooting

6.1 - Configuration changes between 1.4.0 and 1.6.0

This describes the configuration changes between ESB3024 Router version 1.4.0 and 1.6.0.

confd configuration

The confd configuration used in version 1.4.0 is not directly compatible with 1.6.0, and will need to have a few minor updates in order to be valid. If this is not done, the configuration will not be valid and it will not be possible to make configuration changes. Running confcli will cause error messages and an empty default configuration to be printed.

$ confcli services.routing.
[2023-12-12 16:08:07,120] [ERROR] Missing configuration key /services/routing/translationFunctions
[2023-12-12 16:08:07,122] [ERROR] Missing configuration key /services/routing/settings/instream/dashManifestRewrite/sessionGroupNames
[2023-12-12 16:08:07,122] [ERROR] Missing configuration key /services/routing/settings/instream/hlsManifestRewrite/sessionGroupNames
[2023-12-12 16:08:07,123] [ERROR] Missing configuration key /services/routing/settings/managedSessions
[2023-12-12 16:08:07,123] [ERROR] Missing configuration key /services/routing/tuning/target/recentDurationMilliseconds
{
    "routing": {
        "apiKey": "",
        "settings": {
            "allowedProxies": [],
            "contentPopularity": {
                "algorithm": "score_based",
                "sessionGroupNames": []
            },
            "extendedContentIdentifier": {
            ...

The first thing that needs to be done is to rename the keys sessionGroupIds to sessionGroupNames. If the configuration was backed up to the file config_backup.json before upgrading, the keys can be renamed and the updated configuration can be applied by typing this:

sed 's/"sessionGroupIds"/"sessionGroupNames"/' config_backup.json | confcli -i
[2023-12-19 12:33:17,725] [ERROR] Missing configuration key /services/routing/translationFunctions
[2023-12-19 12:33:17,726] [ERROR] Missing configuration key /services/routing/settings/instream/dashManifestRewrite/sessionGroupNames
[2023-12-19 12:33:17,727] [ERROR] Missing configuration key /services/routing/settings/instream/hlsManifestRewrite/sessionGroupNames
[2023-12-19 12:33:17,727] [ERROR] Missing configuration key /services/routing/settings/managedSessions
[2023-12-19 12:33:17,727] [ERROR] Missing configuration key /services/routing/tuning/target/recentDurationMilliseconds

The configuration has not yet been converted, so the error messages are still printed. The configuration will be converted when the acd-confd service is restarted.

systemctl restart acd-confd

This concludes the conversion of the configuration and the router is ready to be used.

Configuration changes

Below are all configuration changes between version 1.4.0 and 1.6.0 listed. Normally nothing needs to be done about this since they will be upgraded automatically, but they are listed here for reference.

Added `translationFunctions` block

services.routing.translationFunctions has been added. It can be added as a map with two empty strings as values, to make the top of the configuration look like this:

{
    "services": {
        "routing": {
            "translationFunctions": {
                "request": "",
                "response": ""
            },
            ...

Renamed `sessionGroupIds` to `sessionGroupNames`

The keys services.routing.settings.instream.dashManifestRewrite.sessionGroupIds and services.routing.settings.instream.hlsManifestRewrite.sessionGroupIds have been renamed to services.routing.settings.instream.dashManifestRewrite.sessionGroupNames and services.routing.settings.instream.hlsManifestRewrite.sessionGroupNames respectively. Any session group IDs need to be manually converted to session group names.

After the conversion, the head of the configuration file might look like this:

{
    "services": {
        "routing": {
            "apiKey": "",
            "settings": {
                "allowedProxies": [],
                "contentPopularity": {
                    "algorithm": "score_based",
                    "sessionGroupNames": []
                },
                "extendedContentIdentifier": {
                    "enabled": false,
                    "includedQueryParams": []
                },
                "instream": {
                    "dashManifestRewrite": {
                        "enabled": false,
                        "sessionGroupNames": []
                    },
                    "hlsManifestRewrite": {
                        "enabled": false,
                        "sessionGroupNames": []
                    },
                    "reversedFilenameComparison": false
                },
                ...

Added `managedSessions` block

A services.routing.settings.managedSessions block has been added. After adding the block, the configuration might look like this:

{
    "services": {
        "routing": {
            "apiKey": "",
            "settings": {
                "allowedProxies": [],
                "contentPopularity": {
                    "algorithm": "score_based",
                    "sessionGroupNames": []
                },
                ...
                "managedSessions": {
                    "fraction": 0.0,
                    "maxActive": 100000,
                    "sessionTypes": []
                },
                "usageLog": {
                    "enabled": false,
                    "logInterval": 3600000
                }
            },
            ...

Added `recentDurationMilliseconds`

A services.routing.tuning.target.recentDurationMilliseconds key has been added to the configuration file, with a default value of 500. After adding the key, the configuration might look like this:

{
    "services": {
        "routing": {
            "apiKey": "",
            ...
            "tuning": {
                "target": {
                    ...
                    "recentDurationMilliseconds": 500,
                    ...

Storing the updated configuration

After all these changes have been done to the configuration file, it can be applied to the router using confcli.

confcli will still display error messages because the stored configuration is not valid. They will not be displayed anymore after the valid configuration has been applied.

$ confcli -i < updated_config.json
[2023-12-12 18:52:05,500] [ERROR] Missing configuration key /services/routing/translationFunctions
[2023-12-12 18:52:05,502] [ERROR] Missing configuration key /services/routing/settings/instream/dashManifestRewrite/sessionGroupNames
[2023-12-12 18:52:05,502] [ERROR] Missing configuration key /services/routing/settings/instream/hlsManifestRewrite/sessionGroupNames
[2023-12-12 18:52:05,503] [ERROR] Missing configuration key /services/routing/settings/managedSessions
[2023-12-12 18:52:05,511] [ERROR] Missing configuration key /services/routing/tuning/target/recentDurationMilliseconds

Raw configuration

The following changes have been made to the raw configuration. If the router is configured via confd and confcli, these changes will be applied by them. This section is only relevant if the router is configured via the v2/configuration API.

Simple changes

The following keys were added or removed. They will not need to be manually updated, the router will add the new keys with default values.

Removed the tuning.repeated_session_start_threshold_seconds key.
Removed the lua_paths key.
Added the tuning.target_recent_duration_milliseconds key.

EDNS proxy changes

If the router has been configured to use an EDNS server, the following has to be changed for the configuration to work.

The hosts.proxy_address key has been renamed to hosts.proxy_url and now accepts a port that is used when connecting to the proxy.

The cdns.http_port and cdns.https_port keys now configure the port that is used for connecting to the EDNS server, before they configured the port that is used for connecting to the proxy.

Installation

1 - Installing a 1.16 release

Upgrade from and earlier ESB3024 Router release

Troubleshooting

1.1 - Configuration changes between 1.14 and 1.16

Confd configuration changes

Added region GeoIP classifier

Added integration.routing.gui configuration

Added services.routing.accounts configuration

2 - Installing a 1.14 release

Upgrade from and earlier ESB3024 Router release

Troubleshooting

2.1 - Configuration changes between 1.12.1 and 1.14

Confd configuration changes

Renamed services.routing.settings.allowedProxies

Added services.routing.tuning.general.restApiMaxBodySize

3 - Installing a 1.12 release

Upgrade from ESB3024 Router release 1.10

Troubleshooting

3.1 - Configuration changes between 1.10.2 and 1.12

Confd configuration changes

Added services.routing.translationFunctions.hostRequest

Added services.routing.translationFunctions.session

Removed services.routing.settins.managedSessions configuration

Added services.routing.tuning.general.maxActiveManagedSessions tuning parameter.

4 - Installing release 1.10.x

Upgrade from ESB3024 Router release 1.8.0

Troubleshooting

4.1 - Configuration changes between 1.8.0 and 1.10.x

Confd configuration changes

Added integration.convoy section

Removed services.routing.apiKey configuration

Added services.routing.settings.qoeTracking

Added healthChecks sections to the hosts

Added hashAlgorithm to the consistentHashing rule

5 - Installing release 1.8.0

Upgrade

Troubleshooting

5.1 - Configuration changes between 1.6.0 and 1.8.0

Confd configuration changes

Added enabled to contentPopularity

Added selectionInputItemLimit to tuning

Added forwardHostHeader to hostGroups

REST API configuration changes

6 - Installing release 1.6.0

Upgrade

Troubleshooting

6.1 - Configuration changes between 1.4.0 and 1.6.0

confd configuration

Configuration changes

Added translationFunctions block

Renamed sessionGroupIds to sessionGroupNames

Added managedSessions block

Added recentDurationMilliseconds

Storing the updated configuration

Raw configuration

Simple changes

EDNS proxy changes

Added `region` GeoIP classifier

Added `integration.routing.gui` configuration

Added `services.routing.accounts` configuration

Renamed `services.routing.settings.allowedProxies`

Added `services.routing.tuning.general.restApiMaxBodySize`

Added `services.routing.translationFunctions.hostRequest`

Added `services.routing.translationFunctions.session`

Removed `services.routing.settins.managedSessions` configuration

Added `services.routing.tuning.general.maxActiveManagedSessions` tuning parameter.

Added `integration.convoy` section

Removed `services.routing.apiKey` configuration

Added `services.routing.settings.qoeTracking`

Added `healthChecks` sections to the hosts

Added `hashAlgorithm` to the `consistentHashing` rule

Added `enabled` to `contentPopularity`

Added `selectionInputItemLimit` to `tuning`

Added `forwardHostHeader` to `hostGroups`

Added `translationFunctions` block

Renamed `sessionGroupIds` to `sessionGroupNames`

Added `managedSessions` block

Added `recentDurationMilliseconds`