Upgrading Avantra

About Versions, Patches, Upgrades, etc.

We first will describe the terminology used in Avantra with respect to versions, patches, upgrades, etc.

Versioning

As described earlier in this document Avantra consists of several software components. Each of these components has a particular version number, and the whole Avantra suite has a version number as well.

The version number for Avantra always has the format [major].[minor] with major and minor being numbers. The Avantra version described in this document is 20.11. We also use the term release as a synonym for version.

Every Avantra component has a version number in format [major].[minor].[patch-level] where [major].[minor] denotes the Avantra version the component belongs to, and patch-level indicates the particular patch level of the component.

With every new release of Avantra, the version number changes (at least the minor version number), and the patch-level of every component is set to 0. Patches will be released on a per component level comprising first of all bug fixes. The Avantra Server, and the Avantra Agent share a common patch-level at the time of release.

Details can be found in the Release Notes.

Version Compatibility

As a general rule, all Avantra components sharing the same [major].[minor] version prefix are compatible to each other, regardless of the particular patch level. Also, as a general rule, components having a different [major].[minor] version prefix are not compatible!

In order to support smooth version upgrades Avantra Server components ensure a certain degree of compatibility to Avantra Agents with a lower [major].[minor] version number. This is described in a more formal way in the Release Notes.

Therefore you must not install a Avantra Agent with a higher [major].[minor] version number than the [major].[minor] version number of the Avantra Server components!

Version Upgrades vs Applying Patches

When we talk about applying patches we mean to replace a particular Avantra component with one that shares the same version number except for the patch-level. The procedures how to apply patches are described in Applying Patches at the very end of this chapter.

When we talk about version upgrades or (short) upgrades we mean to lift the whole Avantra installation from one [major].[minor] version to the next. The major part of this chapter describes how to perform a version upgrade of Avantra.

Upgrade Notes

This and the following sections describe the upgrade of Avantra Server components from version 7.3.x or higher to 20.11.

Before you start your installation, please ensure to read the release notes for Avantra 20.11 and use the latest software versions and patches of Avantra, as described in the Components section.

Starting with Syslink Xandria 7.3, the patch level of the Avantra Master must be equal to or higher than that of the Avantra Agent.
Upgrade Path

You first need to upgrade the Avantra Server to version 20.11 before you can upgrade the Avantra Agents.

Afterwards, if necessary, migrate any existing Syslink Xandria Gateway to an Avantra Agent as described in Upgrading Avantra Gatewayss
Java (former Runtime Environment (JRE))

Avantra Server components require Java 8 or 11. Only the 64-bit version is supported.

Avantra Agents 20.11.0 require Java 8 or 11. You may need to upgrade your Java before you can upgrade the Avantra Agents.

Permissions

You must have local administrator or root permissions in order to perform the upgrade.

Microsoft SQL Server

The Avantra Server supports Microsoft SQL Server 2012, 2014, 2016, 2017, and 2019.

Agent Compatibility

Avantra Agents version 7.3.x and higher are supported with Avantra Server 20.11.

Transports

Avantra 20.11 comes with new transport requests. You need to upgrade to Avantra Agent 20.11 before you can import the new transport requests. However, the Avantra Agent 20.11 also supports the old transport requests shipped with Avantra 20.5 and even Syslink Xandria 7.3. Anyway, the latest transport requests are required to provide all new functions.

Upgrading Server Components (on Microsoft Windows operating systems)

Follow these steps to upgrade your Avantra Server components to Version 20.11:

Upgrading the other Avantra server components

Procedure: Running the Avantra Server Installer

  1. Download avantra-server-20.11.0-win64.exe from the SERVER RELEASE 20.11.0 section at the Support menu of avantra.com.

  2. Open the installer, push Next on the welcome screen and accept the license using the I agree option on the license screen.

  3. You are asked to install either the Avantra Master, the UI, or both. Usually you will leave the default and install both. Push Next to continue.

  4. Choose an appropriate installation location and push Next.

  5. Choose the ports for incoming HTTP and or HTTPS connections of the web UI. You may push the Verify Ports button in order to check if the ports are free. Press Next.

  6. Verify the Windows Firewall configuration rules that will be added to your system. Press Next to proceed.

  7. Choose the (Windows) user to run the Windows services as. If you use Windows Authentication for the Microsoft SQL Server (which is the default in Step 4 of the Procedure: Installing Microsoft SQL Server Express Edition), make sure you use the same user here as for the Microsoft SQL Server.

    If you did not change the command in Step 4 of Procedure: Installing Microsoft SQL Server Express Edition, leave it to the default LocalSystem here. If your Microsoft SQL Server is running with a different user, fill in the same user. Press Next to proceed.

  8. Push Install.

  9. On the final screen, make sure you have checked Install UI and Master and push Finish.

Upgrading Server Components (on Unix-like operating systems)

Procedure: Upgrading Avantra Server components

  1. Download avantra-server-20.11.0-[os].bin from the AVANTRA SERVER RELEASE 20.11.0 section at the Support menu of avantra.com.

    Make sure the file is executable. Otherwise:

    xandria$ chmod 755 avantra-server-20.11.0-[os].bin

  2. Perform one of the following steps:

    • If your existing Avantra UI installation is listening on a port ≥ 1024, (with or without redirecting some port < 1024 to the actual Avantra UI port) execute the following as user root:

      root$ chown -R xandria:xandria /syslink/xangui
root$ chown -R xandria:xandria /syslink/.xandria

      Please make sure to change the XANGUI_USER=root entry in the header of the /syslink/xangui/rc.xangui script to XANGUI_USER=xandria. Command below uses vi as editor, please use any editor you are familiar with.

      root$ vi /syslink/xangui/rc.xangui

      Perform the following steps as user xandria.

    • If your existing Avantra UI installation is listening on a port < 1024, and you have no redirect scenario in place perform the following steps as user root.

      It is recommended to run Avantra processes with a lower privileged OS user than root, so you change the Avantra UI port during this upgrade.

  3. In the /syslink directory, run

    xandria$ ./avantra-server-20.11.0-[os].bin

    On Linux operating systems, the Avantra Master and the UI restart automatically after an upgrade, however, without support for systemd commands (this will be fixed in our future releases). For now, to avoid additional steps to stop and restart Avantra services, we recommend using the following install command for Linux:

    sh avantra-server-20.11.n-linux.bin -- --no-start

    The installer requires a suitable Java 8 or 11 Runtime Environment to run. It usually finds it automatically based on the existing installation. If no suitable Java 8 or 11 Runtime Environment is found, you can specify one like this:

    xandria$ ./avantra-server-20.11.03-[os].bin -- --jvm=[path_to_java_executable]

    with [path_to_java_executable] the absolute path of the java executable.

    Yes, it’s really -- first and then --jvm.

  4. Open your preferred web browser and point it to the URL http[s]://avantra-server[:port]/xn. Use any User having the Permission Administrator Functions.

    In some cases, the following additional operations may be required:

  5. On the Avantra UI Post Upgrade Steps page push the Start post upgrade steps button.

  6. Once finished, click Start Avantra UI.

Installing the License

You can skip this section if you are upgrading from Avantra 20.5 to 20.11.

  1. Select Administration  Licenses from the Avantra UI top-level menu. The Licenses page opens.

  2. Click on Request / Install Xandria License. Then copy and paste the license key retrieved in Obtaining the License before the Upgrade including the lines marked as -----BEGIN/END XLIC BLOCK----- to the corresponding text box and press OK.

  3. A message appears that the license was installed. Verify the Status and Status Message are Ok.

Upgrading Avantra Agents

You have the option to upgrade Avantra Agents manually or automatically (recommended).

Upgrading Avantra Agents Automatically

Avantra Agents are able to perform Agent Self Updates. These updates can be initiated centrally, so the installation of patches and new versions becomes easy even in large-scale Avantra environments.

You need the Trigger Agent Updates Permission in order to perform automatic updates.

Make sure to upgrade to Java 8 or 11 Runtime Environment before you upgrade the Avantra Agents.

External vs. Internal JVM

For your convenience, Avantra has included a JVM installation and update feature. If you make use of this feature, the installed JVM will reside in the Avantra Agent installation directory and does not interfere with your operating system.

Of course you can make use of any Java 8 or 11 eventually installed. It will be found automatically if its location is included in the PATH environment variable. In this document we use the term external JVM for this kind of installation, and the term internal JVM if it is maintained by the Avantra Agent.

Table 1. Advantages and Disadvantages of Internal and External JVMs
Installation Type Advantage Disadvantage

External

Automatic Updates through operating system

Agent needs to be restarted manually after JVM update

Internal

Agent restarts automatically after JVM update

Updates need to be invoked manually

For IBM AIX you probably want to use the external JVM. There are no packages available in a format that can be deployed by the Avantra Agent.

However, you can compose your own Java distribution package in tar.gz format and install it through the Avantra Agent.

In this case the file must be named [java|jre|jdk|jvm]-[version]-[os]-[osarch].tar.gz and has to contain a complete directory structure with JRE (or JDK).

Example: java-8u123-aix-ppc_64.tar.gz

Valid operating system architectures are displayed in the Server Info section of a Server record.

Managing Internal Java Virtual Machines

The following procedure relates to the configuration and upgrade of an internal JVM. If you want to change your JVM type from external to internal or vice versa, see this solution article for details).

To download and upgrade an internal JVM, proceed as follows:

  1. Find a suitable Java package on AdoptOpenJDK. Choose to download tar.gz packages, which are accepted by Avantra UI Update Manager, and use the 64-bit package on a 64-bit operating system.

    Since AdoptOpenJDK only provides zip or msi packages for Windows, you need to follow some additional steps for that operating system described below. This process will be improved in future releases.

    • For Windows operating systems, download the zip installer (OpenJDK 8 (LTS) version > HotSpot JVM > Windows OS > x64 architecture > JDK/JRE .zip file).

    • Unzip the archive and edit the content of the release file by removing all lines except for the following (on the example of Java version 1.8.0_292):

      JAVA_VERSION="1.8.0_292"

      OS_NAME="Windows"

      OS_VERSION="5.2"

      OS_ARCH="amd64"

      SOURCE=""

    • After this, remember to rename the folder to match the Avantra specific package naming: e.g. jre-8u292-windows-x64.

    • Finally, zip the renamed folder into a tar archive using 7Zip, and then zip the tar archive into a gz archive.

      For Linux operating systems, you will need to unpack the tar.gz package from AdoptOpenJDK, edit the release file (see above), and pack it again into the tar.gz folder with the following name format: jre-8u292-linux-x64.tar.gz.

      Make sure there is no top-level directory inside your archive (i.e. jdk8u302-b08-jre) since the downloaded package cannot be processed by Avantra UI Update Manager when running agent updates.

      You can now proceed with the standard update as described below.

  2. Select Administration  Agent Updates from the top-level menu. Select the Packages tab. Choose Upload from the toolbar.

  3. Select the previously downloaded package from your computer and start the upload.

  4. Select the Status tab. Select Select Systems for…  Java Update from the toolbar.

    In order to upgrade or install Java on a single or a few servers only, you can go to Systems  Servers, select the servers, and then choose Manage Agent Java … from the context menu.

  5. The Setup Custom Search Criteria dialog appears. Choose criteria to select the servers you want to install or update Java on. A single or a group of named servers can be chosen with server search criteria Server. Press OK to continue.

  6. The Java Install/Update dialog appears. Please review the information here. Press OK to continue.

  7. You can now verify the process in the Status tab.

Running Agent Update

The Agent Self Updates work as follows:

  1. There is just one(!) upgrade package for the Avantra Agent which is valid for all supported operating systems. It is included in the distribution packages and available as separate download at the Support menu of avantra.com.

    The packages are named agent-20.11.n.bin.

    On Unix-like operating systems these are the same packages you use for the normal installation.

    On Microsoft Windows operating systems this package is used for Agent Self Updates as well, but there is an extra package provided for the initial installation which cannot be used for the automatic upgrade.

  2. You can upload the packages using Avantra UI and the Avantra Agents retrieve the packages through the Avantra Master and avantra-gateway infrastructure.

  3. Avantra UI provides an interface that allows you to select the Avantra Agents supposed to upgrade. You can either choose items from the Server list or define an ad-hoc Selectors.

    In order to avoid too many Avantra Agents trying to download the packages at the same time, the update requests are queued. Only update-simultaneous-downloads update requests are triggered at the same time and there is a delay of schedule-wait-time before the next bunch of update requests is triggered, etc. These two parameters can be configured as described in Procedure: Change Properties for the UI.

  4. As soon as the Avantra Master transfers the update request to the Avantra Agent, the latter one spawns a child process to start downloading the upgrade package while the Avantra Agent continues to run normally.

    Once the download finished successfully, the package is extracted, the Avantra Agent is stopped, old files are replaced, and the newly installed Avantra Agent is started.

  5. If there is anything going wrong, Avantra Agent tries its best to fully recover itself, for example, it tries to roll back to the previous version.

  6. During the upgrade process, verbose status messages are sent back to the Avantra Master. Avantra UI will display the current status and all log messages of the update attempt, so you can watch the update process periodically.

While the whole process usually works very smoothly, there are a few items to observe:

Small is beautiful

If you plan to upgrade your Avantra Agents, start with one or two Physical Servers first and test the upgrade procedure as well as the new Avantra Agent.

If you feel comfortable with the new version, continue with the rest of your Avantra Agents. By default, Avantra Agents running already on the target release are not upgraded, unless you enforce this.

Downgrade

If the upgrade process went well, but the new Avantra Agent does not work as expected, you can also use this feature to downgrade Avantra Agents to the last known good version.

Version Information

On Microsoft Windows operating systems the version information shown in the Programs and Features dialog of the control panel will not be updated!

Uploading Agent Packages

In order to upload packages, perform the following steps:

  1. Select Administration  Agent Updates from the top-level menu. Select the Packages tab. Choose Upload from the toolbar.

  2. Choose the packages from your computer and start the upload.

Starting the Update

In order to trigger the upgrade perform the following steps:

Procedure: Upgrading Avantra Agents automatically

  1. Select Administration  Agent Updates from the top-level menu. Select Select Systems for…  Agent Update from the toolbar.

  2. Fill in appropriate values for the Selectors and push OK.

  3. Choose the appropriate version from the drop-down list and set the flags on the Servers you want to update.

  4. Confirm your selection by pushing the Start Agent Update button.

  5. The Status tab contains the latest status information about the recently scheduled agent updates. You may want to choose the value Running and Errors from the drop-down list in the toolbar to watch the update progress.

See Troubleshooting Agent Updates in case of any issues.

Upgrading Avantra Agents Manually

Java 8 or 11 is required.

Upgrading Avantra Agent manually on Unix-like operating systems

Make sure the installer file agent-[version].bin is located in the installation directory of the Avantra Agent, i.e. typically /syslink.

Run the agent-[version].bin file with the same operating system user the agent is running currently.

Please make sure that the OS user can (at least temporarily) write to /syslink directory. Otherwise the installation will fail.

The installer will notice that a previous version already exists and takes care of the upgrade.

Please make sure that the link to the agent start scripts in your init.d directory (depends on your Unix) are updated to the new start scripts at /syslink/agent/rc.agent.

Upgrading Avantra Agent manually on Microsoft Windows operating systems

Simply install the new version of Avantra Agent as described in Installing the Agent on Microsoft Windows.

Upgrading to the new Transport Requests

You can import the new transport requests delivered with Avantra 20.11.0 only after upgrading to Avantra Agents 20.11.0.

Please perform the following steps:

  1. Identify both transports that need to be used, see the description and release information in the ReadMe.txt file within the transports' .zip.

  2. Import both (corresponding to your release) transports (customizing and workbench) in the client where the RFC User XANDRIA_RFC or AVANTRA_RFC. You may select Ignore Invalid Component Version.

  3. If you have this user defined in another client, please also import the customizing (role) transport in this additional client.

  4. Be sure that the profile has been generated correctly and that it is the only one granted to this user, i.e. delete all other profiles and roles not specified here.

Upgrading Avantra Gateways

The upgrade is described in this solution document: Replace Gateway with Xandria Agent 7.3

Applying Patches

Permissions

You must have local administrator permissions in order to apply patches on Microsoft Windows operating systems. On Unix-like operating systems you need to have the permissions of the user running the Avantra Server components.

Downloading Avantra patches

Before you start your installation, please ensure to read the release notes for Avantra 20.11 and use the latest software versions and patches of Avantra, as described in the Components section.

Starting with Syslink Xandria 7.3, the patch level of the Avantra Master must be equal to or higher than that of the Avantra Agent.

You can download the latest patches at the Support menu of avantra.com.

For the remainder of this section, we assume that you save the downloaded component in C:\temp (on Microsoft Windows operating systems) or /syslink (on Unix-like operating systems).

Patching the Avantra Agent

Applying patches to the Avantra Agent works exactly as described in Upgrading Avantra Agents.

Patching the Avantra Server

  1. Depending on your operating system, proceed as follows:

    • On Microsoft Windows operating systems, run the installer avantra-server-20.11.0-win64.exe from C:\temp.

    • On Unix-like operating systems, run the installer avantra-server-20.11.0-[os].bin from /syslink.

  2. Open Avantra UI as any User having the Permission Administrator Functions and perform any post-upgrade steps eventually available.

Updating Avantra

Avantra automatically monitors versions of its components and informs you in case a newer version is available. The Admin users receive a browser update notification upon login, however, you can always manually check for updates.

To manually check if newer version is available:

  1. In the top menu, select > About.

    The About page displays your current components versions.

  2. Click the Check For Update button.

    Check for Update

    The Avantra Update tab opens where you can see what components are up to date (green) and outdated (red).

    Avantra Update

  3. If you want to update the component, click the Open syslink Download site link to go to the Avantra Download page.

  4. In the Components section, select the component you want to update.

  5. In the Versions list, click the relevant version to start downloading.

    Versions