2 Upgrading an Installation of Application Server or GlassFish Server

Upgrade Paths

There are two general paths you can use when upgrading to GlassFish Server 3.1.2:

Side-by-Side

A side-by-side upgrade means that the new GlassFish Server release is installed in a different directory than the release from which you are upgrading.

In this scenario, you perform the following steps:

1. Perform a basic installation of GlassFish Server 3.1.2 in a location other than the one being used for the older product.

2. Use Upgrade Tool to migrate the old configurations and applications to the new GlassFish Server 3.1.2 directories.

3. Test the new GlassFish Server installation to make sure everything is working properly.

4. 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 GlassFish Server installation before bringing it into production.

In-Place

An in-place upgrade means that the new GlassFish Server 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, the pkg utility, or the Update Notifier in your old installation to overwrite the old installation with the new GlassFish Server 3.1.2 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 GlassFish Server deployments.

Note also that it is only possible to perform an in-place upgrade when upgrading from GlassFish Server 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.

Upgrade Terminology

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:\glassfish3\glassfish\domains).

Master Password

The SSL certificate database password used in operations such as GlassFish Server 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.

Summary of Upgrade Tools and Procedures

There are several tools you can use to upgrade from an earlier GlassFish Server or Enterprise Server installation to GlassFish Server 3.1.2. The general procedures for upgrading to GlassFish Server 3.1.2 vary depending on which tool you use and the product version from which you are upgrading.

The following topics are addressed here:

• Summary of Tools for Performing an Upgrade

• Summary of Procedure for Upgrading With Upgrade Tool

• Summary of Procedure for Upgrading With Update Tool

• Summary of Procedure for Upgrading With the Software Update Notifier

• Summary of Procedure for Upgrading With the pkg Utility

Supported Releases for Upgrade to GlassFish Server 3.1.2

Upgrades to GlassFish Server 3.1.2 are supported from the following earlier GlassFish Server product releases:

• Sun GlassFish Enterprise Server v2.1.1

• Sun GlassFish Enterprise Server v3

• Oracle GlassFish Server 3.0.1

• Oracle GlassFish Server 3.1

• Oracle GlassFish Server 3.1.1

Upgrading From Version 8.x or Older Product Releases

It is not possible to upgrade to GlassFish Server 3.1.2 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 GlassFish Server 3.1.2, you must first upgrade your older product release to one of the releases that are supported for upgrade to GlassFish Server 3.1.2.

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⇒GlassFish Server 3.1.2

Sun GlassFish Enterprise Server 2.1.1 is available for download from the GlassFish Community Downloads page. Instructions for upgrading to Enterprise Server 2.1.1 are provided in Sun GlassFish Enterprise Server 2.1.1 Upgrade Guide.

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 GlassFish Server 3.1.2.

Upgrading GlassFish Server Inside a Closed Network

For instructions on upgrading a GlassFish Server installation in an environment where Internet access is not available, see "Extending and Updating GlassFish Server Inside a Closed Network" in Oracle GlassFish Server Administration Guide.

Upgrade Tool Summary

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:

• To Upgrade From the Command Line Using Upgrade Tool

• To Upgrade Using the Upgrade Tool Wizard

Upgrade Tool Functionality

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 GlassFish Server installation.

• Sends all asadmin command output to the screen and to the upgrade.log file, and sends all server output to the server.log file.

Additional Upgrade Tool functions are explained in the following sections:

• Migration of Deployed Applications

• Upgrade of Clusters

• Upgrade Verification

asadmin> version
Version = Oracle GlassFish Server 3.1 (build 42)
Command version executed successfully.

To Upgrade From the Command Line Using Upgrade Tool

This procedure explains how to use the Upgrade Tool command line to upgrade to GlassFish Server 3.1.2 from any supported older product release. See Supported Releases for Upgrade to GlassFish Server 3.1.2 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.

1. Download and install GlassFish Server 3.1.2 using the Typical Installation path.

   See "Installing GlassFish Server From a Self-Extracting Bundle" in Oracle GlassFish Server Installation Guide for instructions.

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

3. Start Upgrade Tool from a command shell for your operating environment.

   Note:

   Use the Upgrade Tool that is located in the target GlassFish Server 3.1.2 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.

4. 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 named domain1, it will be renamed domain1.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.

5. Review the console output to verify that the upgrade proceeded correctly.

   This output is also written to the output.log file for later review.

   If there are any SEVERE or WARNING messages in the server.log file, the upgrade output will say "Possible error encountered during upgrade. See server log after upgrade process completes."

6. Start the upgraded GlassFish Server 3.1.2 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:

   GlassFish Server 3.1.2 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.

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

asupgrade -c -s /home/glassfish/domains/domain1 -f /root/mypassword
-t /home/glassfish3/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.

Next Steps

• If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1.2. For more information, see "Configuring Web Servers for HTTP Load Balancing" in Oracle GlassFish Server High Availability Administration Guide.

• 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 GlassFish Server 3.1.2 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1.2 installation.

• To register your installation of GlassFish Server 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.

To Upgrade Using the Upgrade Tool Wizard

This procedure explains how to use the graphical Upgrade Tool Wizard to upgrade to GlassFish Server 3.1.2 from any supported older product release. See Supported Releases for Upgrade to GlassFish Server 3.1.2 for a list of supported releases.

Before You Begin

Ensure that the source domains from which you are upgrading are stopped before proceeding.

1. Download and install GlassFish Server 3.1.2 using the Typical Installation path.

   See "Installing GlassFish Server From a Self-Extracting Bundle" in Oracle GlassFish Server Installation Guide for instructions.

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

3. Start the Upgrade Tool wizard from a command shell for your operating environment.

   Note:

   Use the Upgrade Tool that is located in the target GlassFish Server 3.1.2 installation, not the older source installation.

   • On UNIX systems

     as-install/bin/asupgrade
     

   • On Windows systems

     as-install\bin\asupgrade.bat
     

   Tip:

   You may find it faster to run the asupgrade command with the s source-domain-directory option, which will prefill the Source Domain Directory field in the next step.

4. 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 type c:\glassfish\domains\domain1.

5. In the Target Domains Root Directory field, type the location of the GlassFish Server 3.1.2 installation to which to transfer the configuration, or click Browse.

   The default is the full path name of the domains directory of your GlassFish Server 3.1.2 installation (for example, c:\glassfish3\glassfish\domains).

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

   GlassFish Server 3.1.2 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.

7. 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 named domain1, it will be renamed domain1.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.

8. Review the output in the Upgrade Results page to verify that the upgrade proceeded correctly.

   If there are any SEVERE or WARNING messages in the server.log file, the upgrade output will say "Possible error encountered during upgrade. See server log after upgrade process completes."

9. Click Finish to exit the Upgrade Tool when the upgrade process is complete.

10. Start the upgraded GlassFish Server 3.1.2 domain.

    asadmin start-domain domain-name
    

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

• If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1.2. For more information, see "Configuring Web Servers for HTTP Load Balancing" in Oracle GlassFish Server High Availability Administration Guide.

• 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 GlassFish Server 3.1.2 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1.2 installation.

• To register your installation of GlassFish Server 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.

Update Center Tool Procedures

Unlike when using Upgrade Tool, when you use the Update Tool, the Software Update Notifier, or the pkg utility to perform a GlassFish Server 3.1.2 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:

• To Upgrade Using the Update Tool GUI

• To Upgrade Using the Software Update Notifier

• To Upgrade From the Command Line Using the pkg Utility

To Upgrade Using the Update Tool GUI

This procedure explains how to use the graphical Update Tool to perform an in-place upgrade to GlassFish Server 3.1.2 from GlassFish Server 3.0.1 or Enterprise Server v3. Note that it is not possible to use this procedure with any other product releases.

1. Ensure that all domains on the source server from which you are upgrading are stopped before proceeding.

2. In a command shell for your operating environment, navigate to the as-install-parent/bin directory.

3. Use the updatetool command to start the Update Tool GUI.

   The Update Tool main window is displayed.

4. Click on Available Updates.

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

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

7. Start the DAS normally.

   as-install/bin/asadmin start-domain domain-name
   

Next Steps

• If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1.2. For more information, see "Configuring Web Servers for HTTP Load Balancing" in Oracle GlassFish Server High Availability Administration Guide.

• 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 GlassFish Server 3.1.2 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1.2 installation.

• To register your installation of GlassFish Server 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.

To Upgrade Using the Software Update Notifier

This procedure explains how to use the Software Update Notifier to perform an in-place upgrade to GlassFish Server 3.1.2 from GlassFish Server 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 GlassFish Server or Enterprise Server release from which you are upgrading. Software Update Notifier installation is typically performed during the initial GlassFish Server 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.

1. Wait for the Software Update Notifier to pop up a notification balloon informing you that updates are available.

2. Click the balloon prompt to open the Software Update GUI.

3. Manually stop all domains and server instances.

4. Using the Software Update GUI, select the items you want to upgrade and start the installation.

   Ensure that GlassFish Server 3.1.2 is one of the items you select for upgrade. This upgrades the server and selected components to the latest available versions.

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

6. Start the DAS normally.

   as-install/bin/asadmin start-domain domain-name
   

Next Steps

• If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1.2. For more information, see "Configuring Web Servers for HTTP Load Balancing" in Oracle GlassFish Server High Availability Administration Guide.

• 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 GlassFish Server 3.1.2 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1.2 installation.

• To register your installation of GlassFish Server 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.

To Upgrade From the Command Line Using the pkg Utility

This procedure explains how to use the pkg utility to perform an in-place upgrade to GlassFish Server 3.1.2 from GlassFish Server 3.0.1 or Enterprise Server v3. Note that it is not possible to use this procedure with any other product releases.

1. Ensure that all domains on the source server from which you are upgrading are stopped before proceeding.

2. In a command shell for your operating environment, navigate to the as-install-parent/bin directory.

3. Use the pkg image-update command to update your entire GlassFish Server 3.0.1 or Enterprise Server v3 installation to GlassFish Server 3.1.2.

   ./pkg image-update
   

   This upgrades the server components to the latest available versions.

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

5. Start the DAS normally.

   as-install/bin/asadmin start-domain domain-name
   

Next Steps

• If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1.2. For more information, see "Configuring Web Servers for HTTP Load Balancing" in Oracle GlassFish Server High Availability Administration Guide.

• 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 GlassFish Server 3.1.2 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1.2 installation.

• To register your installation of GlassFish Server 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.

To Prepare for the Upgrade

This procedure explains how to prepare for modifying an NSS-based GlassFish Server 2.x installation when upgrading to GlassFish Server 3.1.2.

1. Download and install GlassFish Server 3.1.2 using the Typical Installation path.

   Ensure that you install the new GlassFish Server 3.1.2 product in a directory that is different than the one used for the older installation from which you are upgrading.

   See "Installing GlassFish Server From a Self-Extracting Bundle" in Oracle GlassFish Server Installation Guide for instructions.

2. Rename the new GlassFish Server 3.1.2 domain-dir (the default is as-install/domains/domain1) to a name of your choice.

   In this procedure, 31domain is used for the renamed GlassFish Server 3.1.2 domain.

3. Copy the older source domain to be upgraded to the new GlassFish Server 3.1.2 as-install/domains directory.

   In this procedure, domain1 is used for the older source domain that is copied to the new GlassFish Server 3.1.2 installation.

   Note:

   The 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 GlassFish Server 3.1.2 upgrade on a copy of your old domain rather than on the original.

4. Copy the server.policy, keystore.jks, and cacerts.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.

5. Modify the domain.xml file for ./domain1.

   1. Add the following jvm-options under server-config and default-config:

      -Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks
      -Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks
      

   2. Remove the following jvm-option under server-config and default-config:

      -Dcom.sun.appserv.nss.db=${com.sun.aas.instanceRoot}/config
      

6. Upgrade ./domain1 by starting the DAS in the new GlassFish Server 3.1.2 installation with the --upgrade option.

   as-install/bin/asadmin start-domain --upgrade domain1
   

   This upgrades the domain and then shuts down the DAS.

7. Start the upgraded DAS normally.

   as-install/bin/asadmin start-domain domain1
   

To Perform Post-Upgrade Configuration

These instructions explain the post-upgrade configuration steps that must be performed when upgrading from an NSS-based installation to GlassFish Server 3.1.2.

Before You Begin

Before proceeding with this procedure, complete the procedure explained in To Prepare for the Upgrade.

1. Start the GlassFish Server 3.1.2 domain, if it is not already running, and open the GlassFish Server Admin Console in a browser window.

   The default URL is https://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 named s1as and a keystore password changeit was copied into the v2.x domain before the upgrade.

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

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

4. Take note of all the KeyEntries that exist in your NSS database.

   These entries must be migrated to the keystore.jks in the GlassFish Server 3.1.2 domain. The following command can be used to list all the KeyEntries in the NSS database:

   certutil -L -d $AS_NSS_DB
   

   AS_NSS_DB should point to the ${com.sun.aas.instanceRoot}/config for the 3.1.2 instance into which the v2.x domain was copied. The listing with the attribute combinations u,u,u are the KeyEntries.

   For example:

   s1as u,u,u
   

   Note:

   To run the certutil command, your LD_LIBRARY_PATH must point to the directory containing NSS library and DLLs.

5. 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 created keystore.jks file.

   Make sure you use the same alias when importing the KeyEntry 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
   

   Note:

   The reference to v3-master-password could be the same as v2-master-password if you intend to retain the same master password for the 3.1.2 domain after upgrading from v2.x.

6. If the s1as alias represents a KeyEntry with a self-signed certificate, the self-signed certificate must be copied to the truststore.

   >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
   

7. 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 the truststore (cacerts.jks) need to collected.

   1. certutil -L -d $AS_NSS_DB

      Example output:

      verisignc1g1 T,c,c
      verisignc1g2 T,c,c
      verisignc1g3 T,c,c
      

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

8. For each of the aliases from the certutil output in the preceding step that are required but missing in the truststore listing, execute the following commands to export and import them into the 3.1.2 domain's truststore.

   >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 3.1.2 default truststore.

To Upgrade PKCS#11 Hardware Tokens

If you are using GlassFish Server 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-3.1.2 upgrade solution is to directly configure the Hardware Token as a PKCS11 token using the JDK-JSSE supported mechanisms for configuring PKCS#11 tokens.

1. Set the javax.net.ssl.keyStoreType jvm-options in GlassFish Server 3.1.2 to PKCS11.

   <jvm-options>-Djavax.net.ssl.keyStoreType=PKCS11</jvm-options>
   

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

3. Change the password for the truststore and the GlassFish Server MasterPassword to match the PIN of your HardwareToken.

4. Since you are using a Hardware Token, you can delete the keystore.jks for the migrated domain.

5. 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 the domain.xml for the domain.

   For example, the cert-nickname attribute for the <ssl/> element under the protocol configuration.

6. If the Hardware Token is to act as a TrustStore as well, remove the cacerts.jks file from the domain-dir/config directory.

   Ensure that the following two jvm-options are set in the domain.xml file:

   <jvm-options>-Djavax.net.ssl.trustStore=NONE</jvm-options>
   <jvm-options>-Djavax.net.ssl.trustStoreType=PKCS11</jvm-options>
   

Overview of Cluster and Node Agent Upgrade Procedures

The general steps for upgrading a cluster and node agent configuration so it will work in GlassFish Server 3.1.2 are as follows:

1. Perform a side-by-side upgrade of the DAS. This procedure is described in Performing a Side-By-Side Upgrade With Upgrade Tool.

2. Perform new (not upgrade) GlassFish Server 3.1.2 installations on each node host. GlassFish Server 3.1.2 installation instructions are provided in the Oracle GlassFish Server Installation Guide.

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

4. Re-create the clusters and server instances on each GlassFish Server 3.1.2 node host. This procedure is described in To Re-Create a Cluster.

To Correct the Configuration of a Node After an Upgrade

As part of the upgrade process, node agent elements in the DAS configuration are transformed into GlassFish Server node elements of type CONFIG. This transformation does not affect the node agent directories for GlassFish Server instances. To create the equivalent directories for GlassFish Server 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 GlassFish Server:

• The parent of the base installation directory of the GlassFish Server software on the host, for example, /export/glassfish3.

  The default is the parent of the default base installation directory of the GlassFish Server 3.1.2 software on the DAS host. If the GlassFish Server 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 GlassFish Server instances that are to reside on the node.

  The default is as-install/nodes, where as-install is the base installation directory of the GlassFish Server 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 GlassFish Server nodes, see "Administering GlassFish Server Nodes" in Oracle GlassFish Server 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 Oracle GlassFish Server 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. GlassFish Server 3.1.2 does not support NSS authentication.

1. Ensure that the DAS is running.

   Remote subcommands require a running server.

2. Update the node's configuration data to specify the correct directories and, if necessary, change the type of the node.

   Note:

   Only 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 the update-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 the update-node-config subcommand on the node.

   • If you are changing the type of the node to SSH, run the update-node-ssh subcommand on the node.

   as-install-parent

   The full path to the parent of the base installation directory of the GlassFish Server software on the host, for example, /export/glassfish3.

   node-dir

   The path to the directory that will contain GlassFish Server 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.

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 GlassFish Server 3.1.2 installation in as explained in To Re-Create a Cluster.

See Also

• "Setting Up SSH for Centralized Administration" in Oracle GlassFish Server High Availability Administration Guide

• "Administering GlassFish Server Nodes" in Oracle GlassFish Server High Availability Administration Guide

• update-node-config(1)

• update-node-ssh(1)

To Re-Create a Cluster

This procedure explains how to re-create a clustered GlassFish Server or Enterprise Server configuration for GlassFish Server 3.1.2.

Before You Begin

Before proceeding with these instructions, ensure that you have completed the following procedures:

• Perform the standard upgrade to GlassFish Server 3.1.2 on the DAS, as described in Performing a Side-By-Side Upgrade With Upgrade Tool.

• Perform a new (not upgrade) installation of GlassFish Server 3.1.2 on each node host. See the Oracle GlassFish Server Installation Guide for instructions.

• Correct the upgraded node configuration, if necessary, as described To Correct the Configuration of a Node After an Upgrade.

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

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

3. 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 Oracle GlassFish Server 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 Oracle GlassFish Server High Availability Administration Guide

     • "To Resynchronize an Instance and the DAS Online" in Oracle GlassFish Server 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.

4. After creating the instances, manually copy the instance-dir/imq directory for each instance from the older source installation to the target GlassFish Server 3.1.2 installation.

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

host1$ asadmin --host dashost create-local-instance --node na1 --cluster cluster1 instance1
host2$ asadmin --host dashost create-local-instance --node na2 --cluster cluster1 instance2

Cluster Profile Security Setting

When upgrading a clustered domain configuration from Application Server 9.1 or Enterprise Server v2 to GlassFish Server 3.1.2, 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

Cluster Profile Upgrade on Windows

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.

asupgrade Fails Without Internet Connection

This problem only occurs when using GlassFish Server 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 GlassFish Server 3.1.1.

The workaround for this issue is as follows:

1. Copy the older source domain to be upgraded to the new target domain-dir, the default for which is as-install/domains.

   Rename the target domain1 directory, if one exists, before proceeding.

2. Run the upgrade.

   asadmin> start-domain --upgrade domain-name