Payara Server Upgrade Tool

This tool can be used to upgrade an existing Payara Server installation to a newer version. The Upgrade Tool is bundled in Payara Server by default and is maintained as a separate JAR artifact under the fish.payara.extras:payara-upgrade-tool GAV coordinates.

The upgrade tool can be manually upgraded to a newer version in case it is needed. To do so, download the latest 2.x JAR release from Nexus using this link and then replace the older version into your Payara Server installation under the ${PAYARA_SERVER_INSTALL}/glassfish/lib/asadmin folder.

Upgrading to Payara Server 6

It is possible to upgrade a Payara Server 5.x domain to version 6.x. The process should not be any different as to upgrading between different Payara 5 minor versions, though with the following caveats:

  1. The upgrade tool only supports upgrading to Payara Server 6 versions 6.x.y or higher.

  2. When performing an upgrade from Payara 5 to Payara 6, make sure that you’re using JDK 11 as this is the minimum JDK version required to run Payara Server 6.

  3. The upgrade tool will not adjust the default-web.xml configuration file (located in ${as-install}/config) for each domain, so the following changes have are required:

    1. A <servlet-class> entry of org.apache.jasper.servlet.JspServlet must be converted to org.glassfish.wasp.servlet.JspServlet

    2. The <system-jar-includes> initialization parameter of the jsp servlet has had a change in value between Payara Server 5 and Payara Server 6, reflecting the change in modules from Jakarta EE 8 to Jakarta EE 10.

      This is how the parameter looks on a standard Payara Server 6.4.0 domain configuration:

      <init-param>
        <param-name>system-jar-includes</param-name>
        <param-value>
          /lib/
          \lib\
          expressly.jar
          jakarta.servlet-api.jar
          jakarta.servlet.jsp-api.jar
          jakarta.servlet.jsp.jstl-api.jar
          jakarta.servlet.jsp.jstl.jar
          jakarta.jms-api.jar
          jakarta.faces.jar
          wasp.jar
          jspcaching-connector.jar
          web-glue.jar
          hibernate-validator.jar
          jakarta.ejb-api.jar
          jakarta.enterprise.deploy-api.jar
          jakarta.activation-api.jar
          angus-activation.jar
          jakarta.mail-api.jar
          angus-mail.jar
          jakarta.persistence.jar
          jakarta.resource-api.jar
          jakarta.security.auth.message-api.jar
          jakarta.security.jacc-api.jar
          jakarta.transaction-api.jar
          webservices-osgi.jar
          weld-osgi-bundle.jar
          jersey-mvc-jsp.jar
        </param-value>
      </init-param>
      xml

      You’ll have to adjust the value of this parameter by copying the current values of a clean Payara Server 6.4.0 or newer domain after the upgrade tool completes the process.

It is recommended that users should run the latest version of Payara Server 5.x before attempting to upgrade to version 6.x.

Asadmin CLI Commands

The following are the Asadmin CLI commands available to the upgrade tool.

Upgrade Server Command

Usage

asadmin> upgrade-server

Aim

This command can be used to upgrade Payara Server to the specified distribution along with all SSH nodes in the domain.xml configuration file.

The command will also back up the old version and domains in the default location (payara6/glassfish/domains) or the location specified using the --domaindir option to allow for rolling back.

Command Options

Option Type Description Default Mandatory

--username

String

The username for the Payara Nexus server.

Yes, unless --usedownloaded is specified

--version

String

Specifies the version number of the new version of Payara to use.

Yes, unless --usedownloaded is specified

--distribution

Enum

Specifies the distribution of Payara Server to download. This can payara, payara-web, payara-ml, or payara-web-ml.

payara

No

--stage

Boolean

Determines if the upgrade should be installed in-place, or staged into "x.new" directories. Scripts are provided that can be used to apply and rollback the staged install. This option is automatically enabled when running the command on Windows.

False on Unix, True on Windows

No

--domaindir

String

The directory containing the domains. The domains in this directory are backed up, and their config is used to determine the nodes which will also be upgraded.

${as-install}/domains

No

--usedownloaded

String

The path to the local Payara Server zip archive to use for upgrading instead of downloading from the Payara Enterprise repository. When this parameter is specified, the --username, --password, and --version parameters are not required.

No

Example

This example upgrades a Payara Web distribution to version 5.24.1

asadmin> upgrade-server --username example-user --distribution web --version 5.24.1
shell

Rollback Server Command

Usage

asadmin> rollback-server

Aim

This command can be used to rollback Payara Server to the point before the upgrade-server command was run, restoring the most recent backup of the domain (expected to be the backup created during execution of the upgrade-server command).

This command is not supported on Windows OS, please use the rollbackUpgrade.bat script instead.

Command Options

Option Type Description Default Mandatory

--domaindir

String

The directory containing the domains. The domains in this directory are backed up, and their config is used to determine the nodes which will also be upgraded.

${as-install}/domains

No

Staged Upgrades

When the upgrade-server command is either used on Windows or with the --stage option enabled, the new server files are installed next to the current installation in various .new directories (e.g. payara6/glassfish/bin.new). The following helper scripts are available to interact with staged upgrades.

Apply Staged Upgrade Script

Usage

> ./payara6/glassfish/bin/applyStagedUpgrade

Aim

This script is used to apply an upgrade staged using the upgrade-server command. It will move the current installation into .old directories, and the staged .new installation into the expected "current" location. It will then upgrade the nodes of the domains in the default domain dir, or the domains in the directory provided using --domaindir

Command Options

Option Type Description Default Mandatory

--domaindir

String

The directory containing the domains. The config of the domains in this directory are used to determine the nodes which will also be upgraded.

${as-install}/domains

No

Rollback Upgrade Script

Usage

> ./payara6/glassfish/bin/rollbackUpgrade

Aim

This script is used to rollback a server upgrade applied using the applyStagedUpgrade script. It will move the .old installation back into the expected "current" location, and the applied upgrade back into .new directories. It will then rollback the nodes of the domains in the default domain dir, or the domains in the directory provided using --domaindir

Command Options

Option Type Description Default Mandatory

--domaindir

String

The directory containing the domains. The config of the domains in this directory are used to determine the nodes which will also be rolled back.

${as-install}/domains

No

Cleanup Upgrade Script

Usage

> ./payara6/glassfish/bin/cleanupUpgrade

Aim

This script is used to clean up any leftovers from a staged upgrade: any .old folders and any .new folders will be deleted.

Use of this script will prevent you from rolling back or applying a staged upgrade.

Configure Logging Levels

The upgrade tool commands and helper scripts will print a set of minimum details of the operations executed (upgrade, staging, rollback). For troubleshooting scenarios, or if wanting to review in detail all executed actions, the following 2 environment variables are available to control the level of logging done by the Upgrade tool:

AS_DEBUG

Set to true to configure the Upgrade Tool’s logging level to FINER.

AS_TRACE

Set to true to configure the Upgrade Tool’s logging level to FINESET.

These variables can also be configured as system properties in the Asadmin CLI script file located in the {as-install}/bin folder like this:

AS_INSTALL=`dirname "$0"`/../glassfish
AS_INSTALL_LIB="$AS_INSTALL/lib"
. "${AS_INSTALL}/config/asenv.conf"
JAVA=java
#Depends upon Java from ../config/asenv.conf
if [ ${AS_JAVA} ]; then
    JAVA=${AS_JAVA}/bin/java
fi

exec "$JAVA" -DAS_DEBUG=true  -XX:+IgnoreUnrecognizedVMOptions -jar "$AS_INSTALL_LIB/client/appserver-cli.jar" "$@"
shell
Remember to turn off these logger level settings after executing a server upgrade, as this setting will affect all future executions of any Asadmin CLI commands, which will cause them to print out more information than usual.