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 versions starting from release 5.24.0 and is maintained as a separate JAR artifact under the fish.payara.extras: payara-upgrade-tool GAV coordinates.

The upgrade tool can be manually installed to Payara Platform 5.20.0 and newer if needed. To do so, download the latest JAR release from Payara Nexus using this link and then drop it into your Payara Server installation under the payara5/glassfish/lib/asadmin folder, replacing an older version of the artifact in case it exists.

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 (payara5/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 payara-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. payara5/glassfish/bin.new). The following helper scripts are available to interact with staged upgrades.

Apply Staged Upgrade Script

Usage: > ./payara5/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: > ./payara5/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: > ./payara5/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.

This script cannot be used to clean up upgrades from releases prior to 5.26.0, as it uses a config file to determine the directories to delete which is only generated by the upgrade-server command from release 5.26.0 onwards.

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.