Search
SupportConsoleDevelopersStart a trialContact

Patching and Upgrading Guide

download PDF
Red Hat JBoss Enterprise Application Platform 7.4

Instructions for applying patches and implementing upgrades from one minor Red Hat JBoss Enterprise Application Platform release to the next.

Red Hat Customer Content Services

Abstract

This book is a guide for patching or upgrading a Red Hat JBoss Enterprise Application Platform installation.

Providing feedback on JBoss EAP documentation

To report an error or to improve our documentation, log in to your Red Hat Jira account and submit an issue. If you do not have a Red Hat Jira account, then you will be prompted to create an account.

Procedure

  1. Click the following link to create a ticket.
  2. Please include the Document URL, the section number and describe the issue.
  3. Enter a brief description of the issue in the Summary.
  4. Provide a detailed description of the issue or enhancement in the Description. Include a URL to where the issue occurs in the documentation.
  5. Clicking Submit creates and routes the issue to the appropriate documentation team.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Introduction to patching and upgrading

1.1. Patching and upgrading JBoss EAP

Major upgrades

A major upgrade or migration is required when an application is moved from one major release to another, for example, from JBoss EAP 6.4 to JBoss EAP 7.0. If an application follows the Jakarta specifications, does not access deprecated APIs, and does not contain proprietary code, you might be able to run the application in JBoss EAP 7 without any code changes. However, the server configuration has changed in JBoss EAP 7 and requires migration.

This type of migration is addressed in the JBoss EAP Migration Guide.

Minor updates

JBoss EAP periodically provides point releases, which are minor updates that include bug fixes, security fixes, and new features.

Information about the changes made in a point release are documented in the JBoss EAP Migration Guide and in the 7.4.0 Release Notes.

You can use the JBoss Server Migration Tool to automatically upgrade from one point release to another, for example, from JBoss EAP 7.4.0 to JBoss EAP 7.4.1 For information about how to configure and run the JBoss Server Migration Tool, see Using the JBoss Server Migration Tool.

If you prefer, you can perform a manual upgrade of the server configuration. Instructions on how to perform a manual upgrade are documented in this guide. For more information, see Upgrading JBoss EAP.

Cumulative patches

JBoss EAP also periodically provides cumulative patches that contain bug and security fixes. Cumulative patches increment the release by the last digit, for example, from 7.4.0 to 7.4.1.

Patch installation is addressed in the Patching JBoss EAP chapter of this guide.

Chapter 2. Patching JBoss EAP

The method you should choose to apply a patch to JBoss EAP depends on your installation method. If you installed JBoss EAP using the archive or installer methods, you must use the patch management .zip file. If you used RPMs to install JBoss EAP on Red Hat Enterprise Linux, you must use RPM patches.

Important

Before applying or rolling back a patch, back up your JBoss EAP server, including all deployments and configuration files.

If you have a locally installed JBoss EAP Maven repository, you must also patch the Maven repository to the same cumulative patch version as your JBoss EAP server.

2.1. Patching an archive or installer installation

You can download cumulative patches for an archive or installer installation of JBoss EAP from the Red Hat Customer Portal. If you have multiple JBoss EAP hosts in a managed domain environment, you can patch individual hosts from your JBoss EAP domain controller.

Important notes on archive or installer installation patching

Before patching an archive or installer, you must take note of the following:

  • If you apply a patch that updates a module, the new patched JARs used at runtime are stored in EAP_HOME/modules/system/layers/base/.overlays/PATCH_ID/MODULE. The original unpatched files remain in EAP_HOME/modules/system/layers/base/MODULE, and are not used at runtime.

  • To significantly decrease the size of cumulative patch releases for JBoss EAP 7, you must first confirm that there were no issues with the cumulative patch update, then run this CLI command /core-service=patching:ageout-history(). This removes all cumulative patch overlays except the latest and the original base release.

    For example, if you had JBoss EAP 7.0.0 and applied CP01 and then later applied CP02. If you run /core-service=patching:ageout-history(), you will not be able to rollback to CP01. Rolling back CP02 would mean rolling back to JBoss EAP 7.0.0, you would have to download CP01 and apply it again.

    Note
    • The patch only works for archive installations, not RPMs.
    • You do not need to apply intermediate cumulative patches. For example, If you have JBoss EAP 7.0.0 you can apply CP05 without applying CP01-CP04.
    • You can only roll back to a previous cumulative patch if you had installed it previously.

2.1.1. Patching JBoss EAP using the management CLI

You can apply patches to JBoss EAP using the management CLI.

Note

You cannot use these instructions to update any JBoss EAP servers that you installed using the RPM method. See the RPM instructions for applying a patch instead.

Procedure

  1. Log in to the Red Hat Customer Portal and download the patch file from JBoss EAP Software Downloads.

  2. Apply the patch using the following command from the management CLI, including the appropriate path to the patch file: 

    patch apply /path/to/downloaded-patch.zip
    Note

    To patch a JBoss EAP host in a managed domain, you can specify the JBoss EAP host name using the --host= argument. For example: 

    patch apply /path/to/downloaded-patch.zip --host=my-host

    The patch tool displays a warning message if there are any conflicts when it attempts to apply a patch. If there are conflicts, enter patch --help for the available arguments for resolving patching conflicts.

  3. Restart the JBoss EAP server for the patch to take effect: 

    shutdown --restart=true

Verification

  • You can verify that a patch has been applied successfully by opening the management CLI and running patch info.

    Expected output: 

    Version:             <PATCH_VERSION_NUMBER>.GA
Cumulative patch ID: jboss-eap-<PATCH VERSION NUMBER>.CP
One-off patches:     none

    This displays the version and cumulative patch ID for the newly applied patch.

2.1.2. Patching JBoss EAP using the management console

You can apply patches to JBoss EAP using the management console.

Note

You cannot use these instructions to update any JBoss EAP servers that you installed using the RPM method. See the RPM instructions for applying a patch instead.

Procedure

  1. Log in to the Red Hat Customer Portal and download the patch file from JBoss EAP Software Downloads.
  2. Open the management console and navigate to the Patching tab.

  3. Add the patch using the Add Patch wizard.

    • For a standalone server:

      1. Click the Add (+) button.
      2. Click Choose a file or drag it here, select the downloaded patch to apply, and click Next.
      3. Configure any of the additional options and click Finish.

    • For a managed domain:

      1. Select the host to patch and click the Add (+) button.
      2. Select whether to shut down the servers on the host, and click Next.
      3. Click Choose a file or drag it here, select the downloaded patch to apply, and click Next.
      4. Configure any of the additional options and click Finish.
    • If the patch was applied successfully, restart the server for the changes to take effect.
    • If the patch application fails, review the error message. If there was a conflict, you can use the Override All, Override Modules, and Override fields in the Add Patch wizard to bypass content verification for items that the patch changes. When you override conflicts, the patch contents override your modifications.

Verification

  • To verify that you have applied a patch successfully, open the console to apply a cumulative patch. If it was installed successfully, it should be listed in Patching tab on the management console. This is the same for both standalone and the managed domain servers.

2.1.3. Rolling back to a previously applied patch

You can roll back a previously applied JBoss EAP patch using either the management CLI or the management console.

Important

Rolling back a patch using the patch management system is not intended as a general uninstall functionality. It is only intended to be used immediately after the application of a patch that had undesirable effects.

Warning

When you roll back a patch, be sure to specify the correct value for the Reset Configuration option. You must set one of the following two values before you roll back a patch:

  • If set to TRUE, the patch rollback process rolls back the JBoss EAP server configuration files to their pre-patch state. All changes that were made to the JBoss EAP server configuration files after the patch was applied cannot be recovered.
  • If set to FALSE, the server configuration files cannot be rolled back. In this situation, the server might not start after the rollback, as the patch can alter configurations, such as namespaces, which you can fix manually.

2.1.4. Rolling back a patch using the management CLI

You can roll back a patch on JBoss EAP using the management CLI.

Procedure

  1. Use the patch history command from the management CLI to find the ID of the patch that you want to roll back.

    Note

    If you are using a managed domain, you must add the --host=HOSTNAME argument to the commands to specify the JBoss EAP host.

  2. Roll back the patch with the appropriate patch ID from the previous step. 

    patch rollback --patch-id=PATCH_ID --reset-configuration=TRUE

    The patch tool warns you if there are any conflicts when attempting to roll back the patch. If there are conflicts, enter patch --help for the available arguments and re-run the command with an argument specifying how you want to resolve the conflicts.

  3. Restart the JBoss EAP server for the patch roll back to take effect: 

    shutdown --restart=true

Verification

  1. You can verify that a patch has been rolled back successfully Opening the management CLI and running patch info.This displays the version and cumulative patch ID for the previously applied patch.

2.1.5. Rolling back a patch using the management console

You can roll back a patch on JBoss EAP using the management console.

Procedure

  1. Open the management console and navigate to the Patching tab.

  2. Roll back the patch using the Rollback wizard.

    • For a standalone server:

      1. Select the patch to roll back and click Rollback.
      2. Configure any of the additional options and click Finish.

    • For a managed domain:

      1. Select the host, select the patch to roll back, and click Rollback.
      2. Select whether to shut down the servers on the host and click Next.
      3. Configure any of the additional options and click Finish.
    • If the patch was rolled back successfully, restart the server for the changes to take effect.
    • If the patch rollback failed, review the error message. If there was a conflict, you can use the Override All, Override Modules, and Override fields in the wizard to bypass content verification for items affected by the patch.

Verification

  • To verify that you have rolled back a patch successfully, open the management console and navigate to the Patching tab. On the left, you can see the patch version that has been previously applied. This is the same for both standalone and the managed domain servers.

2.2. Patching an RPM installation

JBoss EAP supports RPM installation patching. Before patching an RPM installation, you must ensure that your system meets all the following setup prerequisites.

Prerequisites

  • The base operating system is up-to-date, and you get updates from the standard Red Hat Enterprise Linux repositories.

  • You are subscribed to the relevant JBoss EAP repository for the update.

    Warning

    When updating an RPM installation, JBoss EAP is updated cumulatively with all RPM-released fixes for the subscribed repository.

  • Back up all configuration files, deployments, and user data.
Important

In a managed domain, ensure that the JBoss EAP domain controller is updated first.

Procedure

To install a JBoss EAP patch using RPM from your subscribed repository, update your Red Hat Enterprise Linux system using the following command: 

# yum update

2.3. Patching a local JBoss EAP Maven repository

If you have installed the JBoss EAP Maven repository, You must apply the patch to your JBoss EAP Maven.

The JBoss EAP Maven repository is available online or as a downloadable compressed file. If you use the publicly hosted online Maven repository, updates are automatically applied, so you don’t need to update the repository. However, if you installed the Maven repository locally using the compressed file, you are responsible for applying updates to the repository.

Whenever a cumulative patch is released for JBoss EAP, a corresponding patch is provided for the JBoss EAP Maven repository. This patch is available in the form of an incremental compressed file that is decompressed into the existing local repository. It does not overwrite or remove any existing files, so there is no rollback requirement.

Use the following procedure to apply updates to your locally installed JBoss EAP Maven repository.

Prerequisites

  • You have subscribed to the Red Hat Customer Portal.
  • You have downloaded and locally installed JBoss EAP 7.4, Maven repository.

Procedure

  1. Open a browser and log in to the Red Hat Customer Portal.
  2. Select Downloads from the menu bar on the header.
  3. Find Red Hat JBoss Enterprise Application Platform in the list and click on it.
  4. Select the correct version of JBoss EAP from the Version drop-down menu, then click on Patches tab.
  5. Find Red Hat JBoss Enterprise Application Platform 7.4 Update CP_NUMBER Incremental Maven Repository in the list, where CP_NUMBER is the cumulative patch number you want to update to, and then click Download.
  6. Locate the path to your JBoss EAP Maven repository. This is referred to in the commands below as EAP_MAVEN_REPOSITORY_PATH.

  7. Decompress the downloaded Maven patch file directly into the directory of the JBoss EAP 7.4 Maven repository.

    1. For Red Hat Enterprise Linux, open a terminal and run the following command, replacing CP_NUMBER with cumulative patch number you want to update to and EAP_MAVEN_REPOSITORY_PATH with your Maven repository path. 

      $ unzip -o jboss-eap-7.4.CP_NUMBER-incremental-maven-repository.zip -d EAP_MAVEN_REPOSITORY_PATH
    2. For Microsoft Windows, use the Windows extraction utility to extract the compressed file into the root of the EAP_MAVEN_REPOSITORY_PATH directory.

Additional information

Chapter 3. Upgrading JBoss EAP

Learn how to upgrade from one JBoss EAP 7 minor release to another. For example, upgrading from JBoss EAP 7.0 to JBoss EAP 7.1.

Important

If you are migrating from an earlier major release of JBoss EAP, for example, from JBoss EAP 6 to JBoss EAP 7, see the Migration Guide.

3.1. Preparing for an upgrade

Before you upgrade JBoss EAP, you need to be aware of the following potential issues:

  • If you back up and restore your configuration files when upgrading to newer releases of JBoss EAP, you might overwrite the new release’s configurations. This can disable new features in your upgraded JBoss EAP instance. Compare the old configuration to the new configuration, and only reapply specific configurations you need to keep. You can do this manually, or by creating a script that can apply the changes consistently to multiple server configuration files.
  • If you back up and restore an existing configuration for migration to a newer JBoss EAP release, a server restart updates the configuration files. These configurations files would no longer be compatible with the previous JBoss EAP release.
  • The upgrade might remove temporary folders. Back up any deployments stored in the data/content/ directory prior to starting the upgrade. You can restore the directory content after the upgrade. Otherwise, the previous version of the JBoss EAP server does not start because of the missing content.
  • Before to applying the upgrade, handle any open transactions and delete the data/tx-object-store/ transaction directory.
  • Check the persistent timer data in the data/timer-service-data directory to determine whether the data applies to the upgrade.
  • Before the upgrade, review the deployment-* files in data directory to determine active timers.

3.2. Upgrading an archive installer installation

You can upgrade JBoss EAP by downloading, decompressing, and installing a new version of a JBoss EAP release.

Prerequisites

  • Ensure that the base operating system is up-to-date.
  • Back up all configuration files, deployments, and user data.
  • Download the compressed file of the target JBoss EAP version.
Important

For a managed domain, upgrade the JBoss EAP domain controller before you upgrade to a newer release of JBoss EAP.

An upgraded JBoss EAP 7 domain controller can manage other JBoss EAP 7 hosts in a managed domain, provided the domain controller runs in the same version or a more recent version of JBoss EAP that the rest of the managed domain.

Procedure

  1. Move the downloaded compressed file to any location other than the location of the existing JBoss EAP installation.

    Note

    If you want to install the upgraded version of JBoss EAP to the same directory as the existing installation, you will need to move the existing installation to a different location before proceeding. This prevents the loss of modified configuration files, deployments, and upgrades.

  2. Extract the compressed file to install a clean instance of the new JBoss EAP release

  3. Copy the EAP_HOME/domain/ and EAP_HOME/standalone/ directories from the previous installation over the new installation directories.

    Important

    You must compare and update configuration files from the previous JBoss EAP version with files in the new version of JBoss EAP, because files copied from the previous release might not have features from the new release enabled by default.

  4. Review the changes made to the bin directory of the previous installation, and and apply the changes to the bin directory of the new release.

    Warning

    Do not overwrite the files in the bin directory of your JBoss EAP version. You must make changes manually.

  5. Review the remaining modified files from the previous installation, and move these changes into the new installation. These files might include:

    • The welcome-content directory.
    • Custom modules in the modules directory.
  6. Optional: If JBoss EAP was previously configured to run as a service, remove the existing service and configure a new service for the new installation.

3.3. Upgrading an RPM installation

Before upgrading your current JBoss EAP instance with a new JBoss EAP instance by using the RPM installation method, check that your system meets certain setup prerequisites.

Prerequisites

  • The base operating system is up to date, and you get updates from the standard Red Hat Enterprise Linux repositories.

  • You are subscribed to the relevant JBoss EAP repository for the upgrade.

    • If you are subscribed to a previous minor JBoss EAP repository, you have changed to the latest minor repository to get the upgrade.
Important

For a managed domain, upgrade the JBoss EAP domain controller before you upgrade to a newer release of JBoss EAP.

An upgraded JBoss EAP 7 domain controller can still manage other JBoss EAP 7 hosts in a managed domain, as long as the domain controller is running the same or more recent version than the rest of the domain.

Procedure

  1. Upgrade your current JBoss EAP version to the newer JBoss EAP version by issuing the following command in your terminal: 

    # yum update
  2. Enable new features in the upgraded release, such as new subsystems, by manually merging each .rpmnew file into your existing configuration files. The RPM upgrade process does not replace any of your modified JBoss EAP configuration files, but it creates .rpmnew files based on the default configuration of your upgraded JBoss EAP instance.

Additional resources

For more information on JBoss EAP repositories, see the information on choosing a JBoss EAP repository and changing JBoss EAP repositories in the Installation Guide.

3.4. Upgrading a cluster

JBoss EAP does not support the creation of clusters where the nodes include different versions of JBoss EAP servers. All nodes within a cluster must must relate to the JBoss EAP version.

Procedure

  1. Create a new JBoss EAP cluster that comprises of nodes running the newest JBoss EAP version.
  2. Migrate all clustered traffic from your previous JBoss EAP release to a new cluster on your upgraded JBoss EAP release.
  3. Shut down your cluster related to the older JBoss EAP version and then remove its content.

Additional resources

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.