Upgrading Avantra

About Versions, Patches, Upgrades, etc.

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

Versioning

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

SAP Transports during upgrades

Not every Avantra release will include updates to the SAP Transports and, where possible, all transports are backward compatible which allows you to upgrade your Server and Agents independent of your SAP Transports. If the latest Avantra release comes with new transport requests it will be listed under the contributions in the download area.

Please make sure to read the release notes prior to upgrades to ensure you are aware of any compatibility notices.

Upgrading Server Components (on Microsoft Windows operating systems)

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

Upgrading the other Avantra server components

Procedure: Running the Avantra Server Installer

  1. Download avantra-server-23.0-win64.exe from the SERVER RELEASE 23.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 Server, 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 Server and push Finish.

Upgrading Server Components (on Unix-like operating systems)

Procedure: Upgrading Avantra Server components

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

    Make sure the file is executable. Otherwise:

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

  2. Perform one of the following steps:

    • If your existing Avantra WebUI installation is listening on a port ≥ 1024, (with or without redirecting some port < 1024 to the actual Avantra WebUI 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 WebUI 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 WebUI port during this upgrade.

  3. In the /syslink directory, run

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

    On Linux operating systems, the Avantra server 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 Runtime Environment to run. It usually finds it automatically based on the existing installation. If no suitable Java Runtime Environment is found, you can specify one like this:

    xandria$ ./avantra-server-23.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 WebUI Post Upgrade Steps page push the Start post upgrade steps button.

  6. Once finished, click Start Avantra UI.

Upgrading Avantra Agents

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

Before upgrading an Avantra Agent, please ensure the required transports are installed to prevent errors. See 21.11 Upgrade Path for more information.

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 Runtime Environment before you upgrade the Avantra Agents.

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-23.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 WebUI and the Avantra Agents retrieve the packages through the Avantra Server and avantra-gateway infrastructure.

  3. Avantra WebUI 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 Change Properties for the WebUI.

  4. As soon as the Avantra Server 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 Server. Avantra WebUI 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 is recommended.

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 take care of the upgrade process. It will test whether the agent directory and therein the file ./lib/xandria_agent.jar exist to decide whether it performs an update or fresh install. That way it is possible to prepare a directory agent/jre, put a JVM installation into a folder agent/jre/1 and then run the agent bin installer. The installer then detects if there is no agent installed and performs a fresh installation.

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

The version of transport required is linked to the Avantra Agent installed. Please check the Avantra transports document to ensure the correct version is installed to prevent errors occurring.

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.