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:

1. 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.

2. 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.

3. 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.

1. 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
   

2. 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.

1. 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
   

2. 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
   

3. 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-*'
   

4. Run the installer script.

   /mnt/acd/installer
   

5. 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.

6. 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.

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

8. 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

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.