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 oforg.apache.jasper.servlet.JspServlet
must be converted toorg.glassfish.wasp.servlet.JspServlet
-
The
<system-jar-includes>
initialization parameter of thejsp
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>
xmlYou’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 |
---|---|---|---|---|
|
String |
The username for the Payara Nexus server. |
Yes, unless |
|
|
String |
Specifies the version number of the new version of Payara to use. |
Yes, unless |
|
|
Enum |
Specifies the distribution of Payara Server to download. This can payara, payara-web, payara-ml, or payara-web-ml. |
payara |
No |
|
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 |
|
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. |
|
No |
|
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 |
No |
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.
|
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
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
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 toFINER
. AS_TRACE
-
Set to
true
to configure the Upgrade Tool’s logging level toFINESET
.
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. |