type=page status=published title=Upgrading an Installation of Application Server or {productName} prev=upgrade-compatibility-issues.html ~~
Caution
|
This chapter is obsoleted and must be revided. |
The Upgrade Tool that is bundled with {productName} 7 replicates the configuration of a previously installed server in the target installation. The Upgrade Tool assists in upgrading the configuration and applications from an earlier version of the Application Server or {productName} to {productName} 7.
In addition to Upgrade Tool, there are three Update Center tools that can be used to perform an in-place upgrade to {productName} 7 from {productName} 3.1.1, 3.1, 3.0.1, and Enterprise Server v3. These three Update Center tools are:
-
Update Tool
-
Software Update Notifier
-
The
pkg
command-line utility
Upgrade Tool and the three Update Center tools are explained later in this chapter.
To view a list of the older versions from which you can upgrade, see Supported Releases for Upgrade to {productName} 7.
The following topics are addressed here:
The subsections that follow provide information that you will need when you perform an upgrade.
The following topics are addressed here:
There are two general paths you can use when upgrading to {productName} 7:
- Side-by-Side
-
A side-by-side upgrade means that the new {productName} release is installed in a different directory than the release from which you are upgrading.
In this scenario, you perform the following steps:-
Perform a basic installation of {productName} 7 in a location other than the one being used for the older product.
-
Use Upgrade Tool to migrate the old configurations and applications to the new {productName} 7 directories.
-
Test the new {productName} installation to make sure everything is working properly.
-
When you are satisfied that the new installation works properly, modify your production environment to use the new installation.
The side-by-side upgrade path is typically used for live production environments because it allows you to thoroughly test the new {productName} installation before bringing it into production.
-
- In-Place
-
An in-place upgrade means that the new {productName} release is installed directly over and into the same directory as the previous product release. The existing configuration is reused in the updated installation.
In this scenario, you simply use Update Tool, thepkg
utility, or the Update Notifier in your old installation to overwrite the old installation with the new {productName} 7 product.
Performing an in-place upgrade is easier than performing a side-by-side upgrade, but you lose the ability to switch back and forth between the old and new installations. There is also no way to revert an in-place upgrade back to the previous product version. Because of these limitations, in-place upgrades are typically only used by developers and for non-production {productName} deployments.
Note also that it is only possible to perform an in-place upgrade when upgrading from {productName} 3.1.1, 3.1, 3.0.1, or v3. If you are upgrading from product versions prior to 3x, you must perform a side-by-side upgrade.
For a more detailed overview, see Summary of Upgrade Tools and Procedures.
The following are important terms related to the upgrade process.
- Source Domain Directory
-
The directory of the server domain from which you are upgrading to the new version (for example,
c:\glassfish\domains\domain1
). - Target Root Domain’s Directory
-
The directory where domains are created on the server to which you are upgrading (for example,
c:\glassfish8\glassfish\domains
). - Master Password
-
The SSL certificate database password used in operations such as {productName} startup. This term refers to the master password of the installation from which you want to upgrade. You need to specify this password if you have changed it from the default value of
changeit
.
There are several tools you can use to upgrade from an earlier {productName} or Enterprise Server installation to {productName} 7. The general procedures for upgrading to {productName} 7 vary depending on which tool you use and the product version from which you are upgrading.
The following topics are addressed here:
There are several tools you can use to perform an upgrade to {productName} 7 are described below.
Upgrade Tool
The {productName} Upgrade Tool is tended solely for performing side-by-side upgrades from any compatible older product version to {productName} 7.
Upgrade Tool provides a number of features that aid in the migration of older configurations and applications to a new {productName} 7 installation. These features are described in more detail in Upgrade Tool Functionality.
In {productName} 7 Upgrade Tool is installed in the
as-install/bin
directory.
Note
|
Upgrade Tool is the only tool you can use when upgrading to {productName} 7 from product versions prior to {productName} 3.0.1 or Enterprise Server v3. |
See Summary of Procedure for Upgrading With Upgrade Tool for an overview of the general procedure for performing an upgrade with Upgrade Tool.
Update Tool and the pkg
Utility
The {productName} Update Tool is a graphical utility that is typically used for the day-to-day maintenance of {productName} components and additional features. For example, Update Tool can be used to update {productName} components or install additional features such as OSGi Admin Console.
The command-line counterpart to Update Tool is the pkg
utility. While
the pkg
utility does not provide exactly the same set of features as
Update Tool, for the purposes of upgrading to {productName} 7, the
pkg
utility and Update Tool feature sets are almost identical.
In addition to day-to-day maintenance tasks, Update Tool and the pkg
utility can be used to perform an in-place upgrade of an entire
{productName} 3.0.1 or Enterprise Server v3 installation to the
{productName} 7 or later release.
In {productName} 7 Update Tool is installed in the
as-install-parent/bin
directory.
Note
|
It is not possible to use Update Tool to upgrade from {productName} or Enterprise Server versions prior to 3x. For these older versions, you must use the Upgrade Tool, described in Upgrade Tool. |
See Summary of Procedure for Upgrading With Update Tool for an overview of the general procedure for performing an upgrade with Update Tool. For more information about Update Tool in general, see "Update Tool" in {productName} Administration Guide.
Software Update Notifier
The {productName} Software Update Notifier is similar to Update Tool
and the pkg
utility in that it enables you to perform an in-place
upgrade from {productName} 3.1.1, 3.1, 3.0.1, or Enterprise Server
v3. As with Update Tool and the pkg
utility, you cannot use the
Software Update tool to upgrade from product releases prior 3.0.1 and
v3.
The Software Update Notifier is distributed as a configuration option during {productName} 7, 3.0.1, and Enterprise Server v3 installation. If installed and enabled, the Software Update Notifier monitors your installation and pops up a notification balloon when updates or upgrades are available for your product.
See Summary of Procedure for Upgrading With the Software Update Notifier for an overview of the general procedure for performing an upgrade with the Software Update Notifier. For more information about the Update Notifier, refer to the Update Tool online help.
The general procedure for using Upgrade Tool to perform an upgrade to {productName} 7 from any compatible older version of {productName} or Enterprise Server comprises the following steps:
-
Download {productName} 7 and perform a Standard Installation, as described in " To Install {productName} Using the Self-Extracting File" in {productName} Installation Guide.
-
Copy any custom or third-party libraries from the older installation to their corresponding locations in the new {productName} 7 installation directories. Note that you should only copy custom or third-party libraries here. Do not copy an libraries from the actual domain that will be upgraded.
-
Run the
asupgrade
command from the new {productName} 7 as-install/bin
directory. -
Start the new {productName} 7 DAS with the
asadmin start-domain
subcommand.
This procedure is described in more detail in Performing a Side-By-Side Upgrade With Upgrade Tool.
The general procedure for using Update Tool to perform an upgrade to {productName} 7 from {productName} 3.0.1 or Enterprise Server v3 comprises the following steps:
-
Manually stop all server instances and the domain.
-
Launch Update Tool by using the as-install-parent`/bin/updatetool` command in the older product directory.
-
In Update Tool, select and install the latest {productName} product release. This updates your server to the 7 release.
-
Upgrade the domain by running the
asadmin start-domain --upgrade
subcommand. This performs the upgrade and then shuts down the DAS. -
Restart the DAS normally with the with the
asadmin start-domain
subcommand.
This procedure is described in more detail in To Upgrade Using the Update Tool GUI.
The general procedure for using the Software Update Notifier to perform an upgrade to {productName} 7 from {productName}3.0.1 or Enterprise Server v3 comprises the following steps:
-
Wait for the Software Update Notifier to pop up a notification balloon informing you that updates are available.
-
Click the balloon prompt to launch the Software Update GUI.
-
Manually stop all server instances and the domain.
-
Use the Software Update GUI to perform the upgrade. This updates your server to the 7 release.
-
Upgrade the domain by running the
asadmin start-domain --upgrade
subcommand. This performs the upgrade and then shuts down the DAS. -
Restart the upgraded DAS normally with the with the
asadmin start-domain
subcommand.
This procedure is described in more detail in To Upgrade Using the Software Update Notifier.
The general procedure for using the pkg
utility to perform an upgrade
to {productName} 7 from {productName}3.0.1 or Enterprise Server
v3 comprises the following steps:
-
Manually stop all server instances and the domain.
-
Run the as-install-parent`/bin/pkg` command with the desired options in the older product directory. This updates your server to the 7 release.
-
Upgrade the domain by running the
asadmin start-domain --upgrade
subcommand. This performs the upgrade and then shuts down the DAS. -
Restart the upgraded DAS normally with the with the
asadmin start-domain
subcommand.
This procedure is described in more detail in To Upgrade
From the Command Line Using the pkg
Utility.
Upgrades to {productName} 7 are supported from the following earlier {productName} product releases:
-
Sun GlassFish Enterprise Server v2.1.1
-
Sun GlassFish Enterprise Server v3
-
{productName} 3.0.1
-
{productName} 3.1
-
{productName} 3.1.1
It is not possible to upgrade to {productName} 7 directly from Sun GlassFish Enterprise Server 8.x or older product releases.
To upgrade from a product release that is older than any of those listed in Supported Releases for Upgrade to {productName} 7, you must first upgrade your older product release to one of the releases that are supported for upgrade to {productName} 7.
For example, to upgrade from any Enterprise Server 8.x release, you first need to upgrade that older release to Enterprise Server 2.1.1. That is, your upgrade path would be as follows:
Enterprise Server 8.x⇒Enterprise Server 2.1.1⇒{productName} 7
Sun GlassFish Enterprise Server 2.1.1 is available for download from the
GlassFish Community
Downloads (http://glassfish.java.net/public/downloadsindex.html
)
page. Instructions for upgrading to Enterprise Server 2.1.1 are provided
in Sun
GlassFish Enterprise Server 2.1.1 Upgrade Guide
(http://docs.oracle.com/cd/E19879-01/821-0180/index.html
).
After upgrading your older Enterprise Server installation to Enterprise Server 2.1.1, you can proceed normally with the instructions in this guide to complete the upgrade to {productName} 7.
For instructions on upgrading a {productName} installation in an environment where Internet access is not available, see " Extending and Updating {productName} Inside a Closed Network" in {productName} Administration Guide.
This section explains how to use Upgrade Tool to perform a side-by-side upgrade to {productName} 7 from any compatible older product release.
The following topics are addressed here:
The Upgrade Tool upgrades your domain configurations and deployed applications. When you use the Upgrade Tool, the source server and the target server are normally installed on the same machine, but under different install locations. Both server file systems must be accessible from the system on which you perform the upgrade.
To perform the upgrade, the user who runs the upgrade needs to have read permissions for the source and target directories and write permission for the target directory.
You can perform an upgrade using Upgrade Tool in the following ways:
The Upgrade Tool migrates the configurations and deployed applications from an earlier version of Sun Java System Application Server or Sun GlassFishEnterprise Server to the current version. Database migrations or conversions are not part of this upgrade process.
Briefly, the Upgrade Tool performs the following steps:
-
Copies the older source domain directory to the new target
domains
directory. -
Calls the
asadmin start-domain --upgrade
command to migrate the source configurations to the new target {productName} installation. -
Sends all
asadmin
command output to the screen and to theupgrade.log
file, and sends all server output to theserver.log
file.
Additional Upgrade Tool functions are explained in the following sections:
Application archives (EAR files) and component archives (JAR, WAR, and
RAR files) that are deployed in the source server do not require any
modification to run on {productName} 7.
Components that may have incompatibilities are deployed on {productName} 7 with the compatibility
property set to v2
and will run
without change on {productName} 7. You may, however, want to
consider modifying the applications to conform to Jakarta EE 6 requirements.
The Jakarta EE 6 platform specification imposes stricter requirements than
Jakarta EE 5 did on which JAR files can be visible to various modules
within an EAR file. In particular, application clients must not have
access to EJB JAR files or other JAR files in the EAR file unless they
use a Class-Path
header in the manifest file, or unless references use
the standard Java SE mechanisms (extensions, for example), or use the
Jakarta EE library-directory
mechanism. Setting the library-directory
property to v2
removes these Jakarta EE 6 restrictions.
Applications and components that are deployed in the source server are deployed on the target server during the upgrade. Applications that do not deploy successfully on the target server must be deployed manually on the target server by the user.
If a domain contains information about a deployed application and the installed application components do not agree with the configuration information, the configuration is migrated unchanged, without any attempt to reconfigure the incorrect configurations.
When upgrading from a clustered configuration, the older cluster
information is retained in a new domain.xml
file in the {productName} 7 installation directories. However, it is still necessary to
manually re-create the server instances that are contained in the
clusters. This procedure is explained in Upgrading Clusters
and Node Agent Configurations.
An upgrade log records the upgrade activity. The upgrade log file is
named upgrade.log
and is created in the working directory from which
the Upgrade Tool is run. Additional information is recorded in the
server log of the upgraded domain.
You can also use the asadmin version
subcommand after starting the
upgraded domain to verify the new {productName} product version; for example:
asadmin> version
Version = Eclipse GlassFish 7.0.0 (build 42)
Command version executed successfully.
This procedure explains how to use the Upgrade Tool command line to upgrade to {productName} 7 from any supported older product release. See Supported Releases for Upgrade to {productName} 7 for a list of supported releases.
Before You Begin
Ensure that the domains on the source server from which you are upgrading are stopped before proceeding.
-
Download and install {productName} 7 using the Typical Installation path.
See " Installing {productName} From a Self-Extracting Bundle" in {productName} Installation Guide for instructions. -
Copy any custom or third-party libraries that may be located in the source as-install
/lib
directory to the target as-install/lib
directory.
Custom and third-party libraries should normally be located in the domain-dir/lib
directory. This step is only necessary for custom or third-party libraries that may be located in the nonstandard as-install/lib
directory. -
Start Upgrade Tool from a command shell for your operating environment.
NoteUse the Upgrade Tool that is located in the target {productName} 7 installation, not the older source installation.
-
On UNIX systems
as-install/bin/asupgrade -c
-
On Windows systems
as-install\bin\asupgrade.bat -c
The
-c
option starts Upgrade Tool in console mode. If-c
is omitted, Upgrade Tool starts in GUI mode, which is described in To Upgrade Using the Upgrade Tool Wizard.If you start Upgrade Tool with only the
-c
option, the tool enters interactive CLI mode in which you are asked to supply the needed options. If you prefer to enter all options directly from the command line, you can use the following syntax:asupgrade [-c|--console] [-V|--version] [-h|--help] [-s|--source source-domain-directory] [-t|--target target-domain-directory] [-f|--passwordfile password-file]
Explanations of these options are provided at the end of this procedure.
-
-
Follow the prompts to perform the upgrade.
If a name used for an older domain that you are upgrading already exists in the new target domains directory, Upgrade Tool will ask if you want to rename the new directory so the old directory can be copied to the new installation.-
If you type
y
in response, the directory is renamed domain-name`.original`. If that name already exists, the directory will be renamed domain-name`.orginal.0`. For example, if the old domain directory is nameddomain1
, it will be renameddomain1.original
, or if that name already exists,domain1.original.0
. -
If you type
n
, you are prompted to specify a different directory name or quit.The domain is upgraded and the results are output to the console.
-
-
Review the console output to verify that the upgrade proceeded correctly.
This output is also written to theoutput.log
file for later review.
If there are anySEVERE
orWARNING
messages in theserver.log
file, the upgrade output will say"Possible error encountered during upgrade. See server log after upgrade process completes."
-
Start the upgraded {productName} 7 domain.
asadmin start-domain domain-name
Log in to the Administration Console with the user name and password you used in the older server.
Note{productName} 7 does not support NSS authentication. If you are upgrading from a Enterprise Profile configuration that uses NSS authentication, follow the procedure in Upgrading Installations That Use NSS Cryptographic Tokens.
-
If you are upgrading a clustered configuration or a configuration in which node agents were used, proceed with the instructions in Upgrading Clusters and Node Agent Configurations.
Example 2-1 Using the asupgrade
Command Line
The following example shows how to use the asupgrade
command-line
utility in non-interactive mode to upgrade an existing Sun GlassFish
Enterprise Server v2.1 installation to {productName} 7. The
following command should be entered on a single line.
asupgrade -c -s /home/glassfish/domains/domain1 -f /root/mypassword
-t /home/glassfish8/glassfish/domains
asupgrade Command-Line Options
Listed below are the asupgrade
command-line options, including the
short form, the long form, and a description of each option.
Short Form | Long Form | Description |
---|---|---|
|
|
Launches the upgrade command line utility. |
|
|
The version of the {productName}. |
|
|
Displays the arguments for launching the upgrade utility. |
|
|
The domain-dir directory in the source (older) server installation. |
|
|
The desired domain-root-dir directory in the {productName} 7 target
installation; default is as-install |
|
|
The file containing the administration password and the master password. |
Next Steps
-
Browse to the URL
http://localhost:8080
to view the domain-dir/docroot/index.html
file. This file is brought over during the upgrade. You may want to copy the default {productName} 7 file from thedomain1.original/docroot
directory and customize it for your {productName} 7 installation. -
To register your installation of {productName} from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
This procedure explains how to use the graphical Upgrade Tool Wizard to upgrade to {productName} 7 from any supported older product release. See Supported Releases for Upgrade to {productName} 7 for a list of supported releases.
Before You Begin
Ensure that the source domains from which you are upgrading are stopped before proceeding.
-
Download and install {productName} 7 using the Typical Installation path.
See " Installing {productName} From a Self-Extracting Bundle" in {productName} Installation Guide for instructions. -
Copy any custom or third-party libraries that may be located in the source as-install
/lib
directory to the target as-install/lib
directory.
Custom and third-party libraries should normally be located in the domain-dir/lib
directory. This step is only necessary for custom or third-party libraries that may be located in the nonstandard as-install/lib
directory. -
Start the Upgrade Tool wizard from a command shell for your operating environment.
NoteUse the Upgrade Tool that is located in the target {productName} 7 installation, not the older source installation.
-
On UNIX systems
as-install/bin/asupgrade
-
On Windows systems
as-install\bin\asupgrade.bat
TipYou may find it faster to run the
asupgrade
command with thes
source-domain-directory option, which will prefill the Source Domain Directory field in the next step. -
-
In the Source Domain Directory field, type the domain directory of the existing installation from which to import the configuration, or click Browse.
For example, you might typec:\glassfish\domains\domain1
. -
In the Target Domains Root Directory field, type the location of the {productName} 7 installation to which to transfer the configuration, or click Browse.
The default is the full path name of thedomains
directory of your {productName} 7 installation (for example,c:\glassfish8\glassfish\domains
). -
Provide the master password of the source application server.
The domain will be upgraded using these credentials. If you do not specify a password here, the default master password is used.Note{productName} 7 does not support NSS authentication. If you are upgrading from a Enterprise Profile configuration that uses NSS authentication, follow the procedure in Upgrading Installations That Use NSS Cryptographic Tokens.
-
Click Next.
If a name used for an older domain that you are upgrading already exists in the new target domains directory, Upgrade Tool will ask if you want to rename the new directory so the old directory can be copied to the new installation.-
If you click OK in response, the directory is renamed domain-name
.original
. If that name already exists, the directory will be renamed domain-name.orginal.0
. For example, if the old domain directory is nameddomain1
, it will be renameddomain1.original
, or if that name already exists,domain1.original.0
. -
If you click No, you brought back to the main screen.
The domain is upgraded and the Upgrade Results page displays the status of the upgrade operation.
-
-
Review the output in the Upgrade Results page to verify that the upgrade proceeded correctly.
If there are anySEVERE
orWARNING
messages in theserver.log
file, the upgrade output will say"Possible error encountered during upgrade. See server log after upgrade process completes."
-
Click Finish to exit the Upgrade Tool when the upgrade process is complete.
-
Start the upgraded {productName} 7 domain.
asadmin start-domain domain-name
-
If you are upgrading a clustered configuration or a configuration in which node agents were used, proceed with the instructions in Upgrading Clusters and Node Agent Configurations.
Next Steps
-
Browse to the URL
http://localhost:8080
to view the domain-dir`/docroot/index.html` file. This file is brought over during the upgrade. You may want to copy the default {productName} 7 file from thedomain1.original/docroot
directory and customize it for your {productName} 7 installation. -
To register your installation of {productName} from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
This section explains how to use the three Update Center tools to perform an in-place upgrade to {productName} 7 from {productName} 3.0.1 or Enterprise Server v3. Specifically, the three tools explained in this section are:
-
Update Tool
-
Software Update Notifier
-
The
pkg
command-line utility
Note
|
{productName} 3.0.1 and Enterprise Server v3 are the only product releases that can be upgraded to the 7 release with the Update Center tools. If you are upgrading from any other product release, you must use Upgrade Tool, as described in Performing a Side-By-Side Upgrade With Upgrade Tool. |
The following topics are addressed here:
Unlike when using Upgrade Tool, when you use the Update Tool, the
Software Update Notifier, or the pkg
utility to perform a {productName} 7 upgrade, the older source server directories are overwritten
with the new target server directories, and the existing configuration
and deployed applications are reused in the updated installation.
To perform the upgrade, the user who runs the upgrade needs to have read and writer permissions for the server installation directories.
You can perform an upgrade using the Update Center tools in the following ways:
This procedure explains how to use the graphical Update Tool to perform an in-place upgrade to {productName} 7 from {productName} 3.0.1 or Enterprise Server v3. Note that it is not possible to use this procedure with any other product releases.
-
Ensure that all domains on the source server from which you are upgrading are stopped before proceeding.
-
In a command shell for your operating environment, navigate to the as-install-parent
/bin
directory. -
Use the
updatetool
command to start the Update Tool GUI.
The Update Tool main window is displayed. -
Click on Available Updates.
-
Select all items in the Available Updates list, and then click the Install button in the toolbar at the top of the Update Tool main window.
When the upgrade is complete, exit Update Tool. -
Upgrade the domain by starting the DAS with the
--upgrade
option.as-install/bin/asadmin start-domain --upgrade domain-name
This upgrades the domain and then shuts down the DAS.
-
Start the DAS normally.
as-install/bin/asadmin start-domain domain-name
Next Steps
-
Browse to the URL
http://localhost:8080
to view the domain-dir/docroot/index.html
file. This file is brought over during the upgrade. You may want to copy the default {productName} 7 file from thedomain1.original/docroot
directory and customize it for your {productName} 7 installation. -
To register your installation of {productName} from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
This procedure explains how to use the Software Update Notifier to perform an in-place upgrade to {productName} 7 from {productName} 3.0.1 or Enterprise Server v3. Note that it is not possible to use this procedure with any other product releases.
Before You Begin
The Software Update Notifier must be installed and enabled on the {productName} or Enterprise Server release from which you are upgrading. Software Update Notifier installation is typically performed during the initial {productName} or Enterprise Server installation. The Software Update Notifier can also be installed later using Update Tool. For more information about the Update Notifier, refer to the Update Tool online help.
-
Wait for the Software Update Notifier to pop up a notification balloon informing you that updates are available.
-
Click the balloon prompt to open the Software Update GUI.
-
Manually stop all domains and server instances.
-
Using the Software Update GUI, select the items you want to upgrade and start the installation.
Ensure that {productName} 7 is one of the items you select for upgrade. This upgrades the server and selected components to the latest available versions. -
Upgrade the domain by starting the DAS with the
--upgrade
option.as-install/bin/asadmin start-domain --upgrade domain-name
This upgrades the domain and then shuts down the DAS.
-
Start the DAS normally.
as-install/bin/asadmin start-domain domain-name
Next Steps
-
Browse to the URL
http://localhost:8080
to view the domain-dir`/docroot/index.html` file. This file is brought over during the upgrade. You may want to copy the default {productName} 7 file from thedomain1.original/docroot
directory and customize it for your {productName} 7 installation. -
To register your installation of {productName} from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
This procedure explains how to use the pkg
utility to perform an
in-place upgrade to {productName} 7 from {productName} 3.0.1 or
Enterprise Server v3. Note that it is not possible to use this procedure
with any other product releases.
-
Ensure that all domains on the source server from which you are upgrading are stopped before proceeding.
-
In a command shell for your operating environment, navigate to the as-install-parent
/bin
directory. -
Use the
pkg image-update
command to update your entire {productName} 3.0.1 or Enterprise Server v3 installation to {productName} 7../pkg image-update
This upgrades the server components to the latest available versions.
-
Upgrade the domain by starting the DAS with the
--upgrade
option.as-install/bin/asadmin start-domain --upgrade domain-name
This upgrades the domain and then shuts down the DAS.
-
Start the DAS normally.
as-install/bin/asadmin start-domain domain-name
Next Steps
-
Browse to the URL
http://localhost:8080
to view the domain-dir`/docroot/index.html` file. This file is brought over during the upgrade. You may want to copy the default {productName} 7 file from thedomain1.original/docroot
directory and customize it for your {productName} 7 installation. -
To register your installation of {productName} from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
{productName} v2.x EE (Enterprise Edition) uses Network Security Services (NSS) for cryptographic software tokens. {productName} 7 does not support NSS, so when performing an upgrade from v2.x EE to 7 additional manual configuration steps must be performed.
The following topics are addressed here:
This procedure explains how to prepare for modifying an NSS-based {productName} 2.x installation when upgrading to {productName} 7.
-
Download and install {productName} 7 using the Typical Installation path.
Ensure that you install the new {productName} 7 product in a directory that is different than the one used for the older installation from which you are upgrading.
See " Installing {productName} From a Self-Extracting Bundle" in {productName} Installation Guide for instructions. -
Rename the new {productName} 7 domain-dir (the default is as-install
/domains/domain1
) to a name of your choice.
In this procedure,31domain
is used for the renamed {productName} 7 domain. -
Copy the older source domain to be upgraded to the new {productName} 7 as-install
/domains
directory.
In this procedure,domain1
is used for the older source domain that is copied to the new {productName} 7 installation.NoteThe remaining steps in this procedure are performed on the copy of your source domain that you created in this step, rather than on your original source domain. It is strongly recommended that you perform the {productName} 7 upgrade on a copy of your old domain rather than on the original.
-
Copy the
server.policy
,keystore.jks
, andcacerts.jks
files from the renamed./31domain/config
directory to the./domain1/config
directory to be upgraded.
For example:cp as-install/domains/31domain/config/server.policy as-install/domains/domain1/config cp as-install/domains/31domain/config/keystore.jks as-install/domains/domain1/config cp as-install/domains/31domain/config/cacerts.jks as-install/domains/domain1/config
This will overwrite the master password for
./domain1
with the password used in the./31domain
. -
Modify the
domain.xml
file for./domain1
.-
Add the following
jvm-options
underserver-config
anddefault-config
:-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks -Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks
-
Remove the following
jvm-option
underserver-config
anddefault-config
:-Dcom.sun.appserv.nss.db=${com.sun.aas.instanceRoot}/config
-
-
Upgrade
./domain1
by starting the DAS in the new {productName} 7 installation with the--upgrade
option.as-install/bin/asadmin start-domain --upgrade domain1
This upgrades the domain and then shuts down the DAS.
-
Start the upgraded DAS normally.
as-install/bin/asadmin start-domain domain1
These instructions explain the post-upgrade configuration steps that must be performed when upgrading from an NSS-based installation to {productName} 7.
Before You Begin
Before proceeding with this procedure, complete the procedure explained in To Prepare for the Upgrade.
-
Start the {productName} 7 domain, if it is not already running, and open the {productName} Admin Console in a browser window.
The default URL ishttps://localhost:4848
As part of the To Prepare for the Upgrade procedure, the default keystore with a default self-signed key-certificate pair with an alias nameds1as
and a keystore passwordchangeit
was copied into the v2.x domain before the upgrade. -
If your default server alias in the NSS v2.x domain is not
s1as
, you can delete this entry using the following command:keytool -delete -keystore keystore.jks -storepass changeit -alias s1as keytool -delete -keystore cacerts.jks -storepass changeit -alias s1as
-
If the master password for the v2.x domain is not the default password
changeit
, you need to change the new keystore password to match the v2.x master password.keytool -storepasswd -new v2-master-password \ -keystore keystore.jks -storepass changeit keytool -storepasswd -new v2-master-password \ -keystore cacerts.jks -storepass changeit
-
Take note of all the
KeyEntries
that exist in your NSS database.These entries must be migrated to the
keystore.jks
in the {productName} 7 domain. The following command can be used to list all theKeyEntries
in the NSS database:certutil -L -d $AS_NSS_DB
AS_NSS_DB
should point to the${com.sun.aas.instanceRoot}/config
for the 7 instance into which the v2.x domain was copied. The listing with the attribute combinationsu,u,u
are theKeyEntries
.
For example:s1as u,u,u
NoteTo run the
certutil
command, yourLD_LIBRARY_PATH
must point to the directory containing NSS library and DLLs. -
For each
PrivateKey-Certificate
pair (KeyEntry
) that exists in the v2.x NSS database, use the following commands to export them from the NSS database and import them into the newly createdkeystore.jks
file.
Make sure you use the same alias when importing theKeyEntry
into the JKS keystore. For example, if s1as is the only alias present in the NSS database, the following command can be used:> pk12util -o /tmp/s1as_pk.p12 -n s1as -d $AS_NSS_DB >keytool -importkeystore -srckeystore /tmp/s1as_pk.p12 -destkeystore \ ${com.sun.aas.instanceRoot}/config/keystore.jks -srcstoretype PKCS12 \ -deststoretype JKS -srcstorepass v2-master-password \ -deststorepass v3-master-password -srcalias s1as \ -destalias s1as -srckeypass v2-master-password \ -destkeypass v3-master-password
NoteThe reference to v3-master-password could be the same as v2-master-password if you intend to retain the same master password for the 7 domain after upgrading from v2.x.
-
If the
s1as
alias represents aKeyEntry
with a self-signed certificate, the self-signed certificate must be copied to thetruststore
.>certutil -L -n s1as -r -d $AS_NSS_DB> /tmp/s1as.der>keytool -import -keystore cacerts.jks -storepass v3-master-password \ -file /tmp/s1as.der -alias s1as
-
There is a rare chance that the 2.x NSS database has some CA (Certificate Authority) certificates that are absent in the default created
truststore
. In such cases, all aliases that are missing in thetruststore
(cacerts.jks
) need to collected.-
certutil -L -d $AS_NSS_DB
Example output:verisignc1g1 T,c,c verisignc1g2 T,c,c verisignc1g3 T,c,c
-
keytool -list -keystore cacerts.jks -storepass
v3-master-password
Example output:godaddyclass2ca, Jan 20, 2005, trustedCertEntry, Certificate fingerprint (MD5): 91:DE:06:25:AB:DA:FD:32:17:0C:BB:25:17:2A:84:67 verisignclass1g3ca, Mar 26, 2004, trustedCertEntry, Certificate fingerprint (MD5): B1:47:BC:18:57 1:18:A0:78:2D:EC:71:E8:2A:95:73 secomevrootca1, May 1, 2008, trustedCertEntry, Certificate fingerprint (MD5): 22:2D:A6:01:EA:7C:0A:F7:F0:6C:56:43:3F:77:76 3
-
-
For each of the aliases from the
certutil
output in the preceding step that are required but missing in thetruststore
listing, execute the following commands to export and import them into the 7 domain’struststore
.>certutil -L -n verisignc1g1 -r -d $AS_NSS_DB> /tmp/verisignc1g1.der>keytool -import -keystore cacerts.jks -storepass v3-master-password \ -file /tmp/verisignc1g1.der -alias verisignc1g1
Note
|
Sometimes just the alias names that are used in the NSS database are
different, and the same certificate is, in fact, present in the 7
default |
If you are using {productName} v2.x Enterprise Edition with Hardware Tokens (for example, FIPS-140 compliant Sun Cryptographic Accelerator 6000 or other Sun Cryptographic Accelerators) configured by means of NSS-PKCS11, then the v2.x EE-to-7 upgrade solution is to directly configure the Hardware Token as a PKCS11 token using the JDK-JSSE supported mechanisms for configuring PKCS#11 tokens.
-
Set the
javax.net.ssl.keyStoreType
jvm-options
in {productName} 7 to PKCS11.<jvm-options>-Djavax.net.ssl.keyStoreType=PKCS11</jvm-options>
-
Set the
javax.net.ssl.keyStore
URL should be set to l since this is a hardware token.<jvm-options>-Djavax.net.ssl.keyStore=NONE</jvm-options>
-
Change the password for the
truststore
and the {productName}MasterPassword
to match the PIN of yourHardwareToken
. -
Since you are using a Hardware Token, you can delete the
keystore.jks
for the migrated domain. -
Ensure the
token-alias
for the hardware token (private key) that you intend to use as the Server’s Key for SSL is mentioned in every relevant place in thedomain.xml
for the domain.
For example, thecert-nickname
attribute for the<ssl/>
element under theprotocol
configuration. -
If the Hardware Token is to act as a
TrustStore
as well, remove thecacerts.jks
file from the domain-dir/config
directory.
Ensure that the following twojvm-options
are set in thedomain.xml
file:<jvm-options>-Djavax.net.ssl.trustStore=NONE</jvm-options> <jvm-options>-Djavax.net.ssl.trustStoreType=PKCS11</jvm-options>
This section explains additional steps you need to perform when upgrading cluster and node agent configurations from Application Server or Enterprise Server to {productName} 7.
{productName} 7 does not support node agents. As part of the
upgrade process, any node agent elements in the older source
configuration are transformed into CONFIG
node elements in the
domain.xml
file for the upgraded DAS. If the source node agent
configuration is incompatible with your {productName} 7
installation, you must correct the node configuration on the upgraded DAS.
In addition, although the source cluster configuration is retained in
the domain.xml
file for the upgraded DAS, it is still necessary to
install {productName} 7 on each node host and manually re-create
the server instances that are contained in the clusters.
The following topics are addressed here:
The general steps for upgrading a cluster and node agent configuration so it will work in {productName} 7 are as follows:
-
Perform a side-by-side upgrade of the DAS. This procedure is described in Performing a Side-By-Side Upgrade With Upgrade Tool.
-
Perform new (not upgrade) {productName} 7 installations on each node host. {productName} 7 installation instructions are provided in the {productName} Installation Guide.
-
Correct the node configuration on the upgraded DAS, if necessary. This procedure is described in To Correct the Configuration of a Node After an Upgrade.
-
Re-create the clusters and server instances on each {productName} 7 node host. This procedure is described in To Re-Create a Cluster.
As part of the upgrade process, node agent elements in the DAS
configuration are transformed into {productName} node elements of
type CONFIG
. This transformation does not affect the node agent
directories for {productName} instances. To create the equivalent
directories for {productName} instances after an upgrade, you must
re-create the instances as explained in To Re-Create a
Cluster.
The name of an upgraded node is the name of the node agent from which the node is transformed.
The host that the node represents is obtained from the configuration of the original node agent or, if not specified, is not set. If the configuration of the original node agent did not specify the name of the node host, you must update the node to specify the host that the node represents.
Default values are applied to the remainder of the node’s configuration data.
The default values of the following items in a node’s configuration data might not meet your requirements for the upgraded installation of {productName}:
-
The parent of the base installation directory of the {productName} software on the host, for example,
/export/glassfish8
.
The default is the parent of the default base installation directory of the {productName} 7 software on the DAS host. If the {productName} software is installed under a different directory on the node host, you must update the node’s configuration to specify the correct directory. -
The directory that will contain the {productName} instances that are to reside on the node.
The default is as-install/nodes
, where as-install is the base installation directory of the {productName} software on the host. If you require the instances to be contained in a different directory, you must update the node’s configuration to specify that directory.
If you are using secure shell (SSH) for centralized administration, you
must also change the type of the node to SSH
to enable the node for
remote communication.
For more information about {productName} nodes, see "Administering {productName} Nodes" in {productName} High Availability Administration Guide.
Before You Begin
Ensure that the following prerequisites are met:
-
A side-by-side upgrade on the DAS has been performed. For more information, see Performing a Side-By-Side Upgrade With Upgrade Tool.
-
If you are changing the type of the node to
SSH
, ensure that SSH is configured on the host where the DAS is running and on the host that the node represents. For more information, see " Setting Up SSH for Centralized Administration" in {productName} High Availability Administration Guide. -
If you are upgrading from an Enterprise Profile configuration that uses NSS authentication, ensure that the procedure in Upgrading Installations That Use NSS Cryptographic Tokens has been performed. {productName} 7 does not support NSS authentication.
-
Ensure that the DAS is running.
Remote subcommands require a running server. -
Update the node’s configuration data to specify the correct directories and, if necessary, change the type of the node.
NoteOnly the options that are required to complete this task are provided in this step. For information about all the options for changing the node’s configuration data, see the
update-node-ssh
(1) help page or theupdate-node-config
(1) help page.
-
asadmin> node-update-subcommand [--installdir as-install-parent] [--nodedir node-dir]
[--nodehost node-host] node-name
- node-update-subcommand
-
The subcommand to run to update the node.
-
If you are leaving the type of the node as
CONFIG
, run theupdate-node-config
subcommand on the node. -
If you are changing the type of the node to
SSH
, run theupdate-node-ssh
subcommand on the node.
-
- as-install-parent
-
The full path to the parent of the base installation directory of the {productName} software on the host, for example,
/export/glassfish8
. - node-dir
-
The path to the directory that will contain {productName} instances that are to reside on the node. If a relative path is specified, the path is relative to the as-install directory.
- node-host
-
The name of the host that the node is to represent after the node is updated.
- node-name
-
The name of the node to update. This name is the name of the node agent from which the node was transformed.
Example 2-2 Correcting the Configuration of a Node After an Upgrade
This example updates the path to the directory that will contain
instances that are to reside on the node xk01
to
/export/home/gf/nodes
. Because this node is transformed from a node
agent, the type of the node is CONFIG
. Therefore, type of the node is
not changed.
asadmin> update-node-config --nodedir /export/home/gf/nodes xk01
Command update-node-config executed successfully.
Next Steps
Re-create the cluster configuration from the older source installation in the new {productName} 7 installation in as explained in To Re-Create a Cluster.
See Also
-
" Setting Up SSH for Centralized Administration" in {productName} High Availability Administration Guide
-
"Administering {productName} Nodes" in {productName} High Availability Administration Guide
This procedure explains how to re-create a clustered {productName} or Enterprise Server configuration for {productName} 7.
Before proceeding with these instructions, ensure that you have completed the following procedures:
-
Perform the standard upgrade to {productName} 7 on the DAS, as described in Performing a Side-By-Side Upgrade With Upgrade Tool.
-
Perform a new (not upgrade) installation of {productName} 7 on each node host. See the {productName} Installation Guide for instructions.
-
Correct the upgraded node configuration, if necessary, as described To Correct the Configuration of a Node After an Upgrade.
-
Start the upgraded DAS.
asadmin> start-domain domain-name
If the upgrade succeeded, the migrated cluster configuration exists and the
get-health
subcommand lists the status of the clustered instances as not running. -
Confirm that the cluster configuration exists and contains all its instances.
asadmin> get-health cluster-name
For example, for the sample
cluster1
used in this procedure:asadmin> get-health cluster1 instance1 not started instance2 not started Command get-health executed successfully.
-
Re-create the clustered server instances on each instance host.
The specific commands to use depend on your configuration.-
If remote hosts cannot contact the DAS, export and import the instances' configuration data, as explained in " To Resynchronize an Instance and the DAS Offline" in {productName} High Availability Administration Guide.
-
If remote hosts can contact the DAS, create each instance individually and resynchronize the instance with the DAS, as explained in the following sections:
-
" To Create an Instance Locally" in {productName} High Availability Administration Guide
-
" To Resynchronize an Instance and the DAS Online" in {productName} High Availability Administration Guide
Note that the node name matches that used for the node agent in the 2.x installation. If you get an error stating that some attributes do not match the values in the DAS configuration, follow the instructions in To Correct the Configuration of a Node After an Upgrade.
-
-
-
After creating the instances, manually copy the instance-dir
/imq
directory for each instance from the older source installation to the target {productName} 7 installation. -
If necessary, start the cluster.
For example:asadmin> start-cluster cluster1
This step may or may not be necessary, depending on the procedure you used to create the server instances for the cluster.
Example 2-3 Creating Two Local Instances
The following example shows how to create two local instances in a cluster.
host1$ asadmin --host dashost create-local-instance --node na1 --cluster cluster1 instance1
host2$ asadmin --host dashost create-local-instance --node na2 --cluster cluster1 instance2
dashost
-
The name of the DAS host.
na1
-
The name of the node host.
cluster1
-
The name of the cluster.
instance1
,instance2
-
The names of the instances.
This section addresses issues that can occur during an upgrade to {productName} 7.
The following topics are addressed here:
When upgrading a clustered domain configuration from Application Server
9.1 or Enterprise Server v2 to {productName} 7, you may encounter
problems if the admin-service
element in the DAS domain.xml
file
sets both of the following attributes:
-
security-enabled=true
-
type=das-and-server
The security-enabled
attribute must be set to false
in the
admin-service
element for the DAS when type
is set to
das-and-server
.
You can use the get
subcommand to determine the values for these two
attributes. For example:
-
To display the value for the
security-enabled
attribute:asadmin> get configs.config.server-config.admin-service.jmx-connector.system.security-enabled
-
To display the value for the type attribute:
asadmin> get configs.config.server-config.admin-service.type
If necessary, use the set
subcommand to set security-enabled=false
.
For example:
asadmin> set configs.config.server-config.admin-service.jmx-connector.system.security-enabled=false
On Windows, when you upgrade cluster profile domains, you could encounter the following error:
Fatal error while backing up the domain directory
To resolve this error, look for and remove any hidden files in the source domain’s directory and re-run Upgrade Tool.
This problem only occurs when using {productName} 3.1 Upgrade Tool to perform a side-by-side upgrade on a 2.x domain without an Internet connection. It does not occur when using {productName} 3.1.1.
The workaround for this issue is as follows:
-
Copy the older source domain to be upgraded to the new target domain-dir, the default for which is as-install
/domains
.
Rename the targetdomain1
directory, if one exists, before proceeding. -
Run the upgrade.
asadmin> start-domain --upgrade domain-name