Upgrading to Eclipse GlassFish 8

1 Upgrading an Installation of Application Server or Eclipse GlassFish

This section explains how to upgrade to Eclipse GlassFish 8 from a previous version. The process involves replicating your existing configuration and applications in the new installation.

Key Topics

Upgrade Paths

Choose one of the following upgrade paths:

Side-by-Side (Recommended)

Installs the new version in a separate directory, allowing you to test before switching to production.
Steps:

  1. Install Eclipse GlassFish 8 in a new directory.

  2. Manually copy the configuration from the old installation.

  3. Test the new installation.

  4. Update your production environment to use the new installation.

In-Place (Not Recommended)

Replaces the existing installation. Requires manual steps and significant downtime.
Steps:

  1. Move the current installation to a backup directory.

  2. Install Eclipse GlassFish 8 in the original location.

  3. Manually copy the configuration from the backup.

  4. Test the new installation. If issues arise, restore the backup.

Upgrade Procedure

Use the Upgrade Tool (asadmin start-domain --upgrade) to migrate configurations and applications.

Prerequisites

  • Stop all domains on the source server.

  • Install Eclipse GlassFish 8 (see Eclipse GlassFish Installation Guide).

  • Copy custom/third-party libraries from the old installation to the new one.

Steps

  1. Install Eclipse GlassFish 8 in a new directory.

  2. Copy configurations from the old installation:

    • Domain directory (e.g., glassfish/domains/domain1)

    • Nodes directory (if applicable, e.g., glassfish/nodes)

  3. Run the Upgrade Tool: asadmin start-domain --upgrade`

  4. Start the upgraded domain: asadmin start-domain domain-name`

  5. Verify the upgrade by logging into the Admin Console.

Special Cases

Upgrade of Clusters

When upgrading from a clustered configuration, the older cluster information is retained in a new domain.xml file in the Eclipse GlassFish 8 installation directories. However, it is still necessary to manually re-create the server instances that are contained in the clusters.

To do that:

  1. Perform new (not upgrade) Eclipse GlassFish 8 installations on each node host. Eclipse GlassFish 8 installation instructions are provided in the Eclipse GlassFish Installation Guide.

  2. Correct the node configuration on the upgraded DAS, if necessary. This procedure is described in Correcting Cluster configuration.

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

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

  5. 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 Eclipse GlassFish 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:

  6. After creating the instances, manually copy the instance-dir/imq directory for each instance from the older source installation to the target Eclipse GlassFish 8 installation.

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

Correcting Cluster configuration

Eclipse GlassFish 8 does not support node agents. If you’re upgrading from a version that supports them or you have issues in cluster configuration after an upgrade, after upgrading the DAS:

  1. Install Eclipse GlassFish 8 on each node host.

  2. Correct node configurations using update-node-config or update-node-ssh.

  3. Re-create clusters and instances:

    • Use create-local-instance for each instance.

    • Copy the imq directory from the old installation.

Upgrading Installations Using NSS Cryptographic Tokens

Eclipse GlassFish 8 does not support NSS. If you’re upgrading from a version that supports them, follow these steps:

  1. Prepare for Upgrade:

    • Install Eclipse GlassFish 8 in a new directory.

    • Copy the source domain to the new installation.

    • Update domain.xml to remove NSS references and add JKS keystore paths.

  2. Perform Post-Upgrade Configuration:

    • Migrate NSS keys to PKCS#12 using keytool and certutil.

    • Update the master password if needed.

  3. Upgrade PKCS#11 Hardware Tokens:

    • Configure the token using JDK-JSSE mechanisms.

    • Update domain.xml to reference the hardware token.

Troubleshooting

Cluster Profile Security Setting

If upgrading from Application Server 9.1 or Enterprise Server v2, ensure the admin-service element in domain.xml has:

security-enabled=false

when type=das-and-server.

Common Issues

  • Cluster Profile Upgrade on Windows: Ensure file paths use double backslashes (\\).

  • Upgrade Verification: Check logs for errors and verify deployed applications.

Terminology

Source Domain Directory

Directory of the domain being upgraded (e.g., c:\glassfish\domains\domain1).

Target Root Domain’s Directory

Directory where domains are created in the new installation (e.g., c:\glassfish8\glassfish\domains).

Master Password

SSL certificate database password (default: changeit).