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:

The upgrade tool only supports upgrading to Payara Server 6 versions 6.x.y or higher.
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.

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:

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

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>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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" "$@"

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.