docs/upgrade-guide/src/main/jbake/content/upgrading-legacy-installation.adoc

type=page
status=published
title=Upgrading an Installation of Application Server or GlassFish Server
prev=upgrade-compatibility-issues.html
~~~~~~

Upgrading an Installation of Application Server or GlassFish Server
===================================================================

[[GSUPG00003]][[abmbq]]


[[upgrading-an-installation-of-application-server-or-glassfish-server]]
2 Upgrading an Installation of Application Server or GlassFish Server
---------------------------------------------------------------------

The Upgrade Tool that is bundled with GlassFish Server 4.0 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
GlassFish Server to GlassFish Server 4.0.

In addition to Upgrade Tool, there are three Update Center tools that
can be used to perform an in-place upgrade to GlassFish Server 4.0 from
GlassFish Server 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
link:#gjxkx[Supported Releases for Upgrade to GlassFish Server 4.0].

The following topics are addressed here:

* link:#gaejc[Upgrade Overview]
* link:#abmbr[Performing a Side-By-Side Upgrade With Upgrade Tool]
* link:#gkthu[Performing an In-Place Upgrade With the Update Center
Tools]
* link:#gktnh[Upgrading Installations That Use NSS Cryptographic Tokens]
* link:#gfybw[Upgrading Clusters and Node Agent Configurations]
* link:#gkrfh[Correcting Potential Upgrade Problems]

[[gaejc]][[GSUPG00039]][[upgrade-overview]]

Upgrade Overview
~~~~~~~~~~~~~~~~

The subsections that follow provide information that you will need when
you perform an upgrade.

The following topics are addressed here:

* link:#gkxum[Upgrade Paths]
* link:#gdkiw[Upgrade Terminology]
* link:#gktcb[Summary of Upgrade Tools and Procedures]
* link:#gjxkx[Supported Releases for Upgrade to GlassFish Server 4.0]
* link:#gkufi[Upgrading From Version 8.x or Older Product Releases]
* link:#gkxrp[Upgrading GlassFish Server Inside a Closed Network]

[[gkxum]][[GSUPG00059]][[upgrade-paths]]

Upgrade Paths
^^^^^^^^^^^^^

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

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 4.0 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 4.0 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 4.0 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 link:#gktcb[Summary of Upgrade Tools
and Procedures].

[[gdkiw]][[GSUPG00060]][[upgrade-terminology]]

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:\glassfish7\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`.

[[gktcb]][[GSUPG00061]][[summary-of-upgrade-tools-and-procedures]]

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 4.0. The
general procedures for upgrading to GlassFish Server 4.0 vary depending
on which tool you use and the product version from which you are upgrading.

The following topics are addressed here:

* link:#gktdx[Summary of Tools for Performing an Upgrade]
* link:#gktdz[Summary of Procedure for Upgrading With Upgrade Tool]
* link:#gktcl[Summary of Procedure for Upgrading With Update Tool]
* link:#gkuef[Summary of Procedure for Upgrading With the Software Update Notifier]
* link:#gktnb[Summary of Procedure for Upgrading With the `pkg` Utility]

[[gktdx]][[GSUPG00045]][[summary-of-tools-for-performing-an-upgrade]]

Summary of Tools for Performing an Upgrade
++++++++++++++++++++++++++++++++++++++++++

There are several tools you can use to perform an upgrade to GlassFish
Server 4.0 are described below.

* link:#gktcz[Upgrade Tool]
* link:#gktha[Update Tool and the `pkg` Utility]
* link:#gkuff[Software Update Notifier]

[[gktcz]][[GSUPG00004]][[upgrade-tool]]

Upgrade Tool

The GlassFish Server Upgrade Tool is tended solely for performing
side-by-side upgrades from any compatible older product version to
GlassFish Server 4.0.

Upgrade Tool provides a number of features that aid in the migration of
older configurations and applications to a new GlassFish Server 4.0
installation. These features are described in more detail in
link:#gdkix[Upgrade Tool Functionality].

In GlassFish Server 4.0 Upgrade Tool is installed in the
as-install``/bin`` directory.

[NOTE]
====
Upgrade Tool is the only tool you can use when upgrading to GlassFish
Server 4.0 from product versions prior to GlassFish Server 3.0.1 or
Enterprise Server v3.
====

See link:#gktdz[Summary of Procedure for Upgrading With Upgrade Tool]
for an overview of the general procedure for performing an upgrade with
Upgrade Tool.

[[gktha]][[GSUPG00005]][[update-tool-and-the-pkg-utility]]

Update Tool and the `pkg` Utility

The GlassFish Server Update Tool is a graphical utility that is
typically used for the day-to-day maintenance of GlassFish Server
components and additional features. For example, Update Tool can be used
to update GlassFish Server 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 GlassFish Server 4.0, 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
GlassFish Server 3.0.1 or Enterprise Server v3 installation to the
GlassFish Server 4.0 or later release.

In GlassFish Server 4.0 Update Tool is installed in the
as-install-parent``/bin`` directory.

[NOTE]
====
It is not possible to use Update Tool to upgrade from GlassFish Server
or Enterprise Server versions prior to 3x. For these older versions, you
must use the Upgrade Tool, described in link:#gktcz[Upgrade Tool].
====

See link:#gktcl[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
"link:../administration-guide/toc.html#GSADG00701[Update Tool]"
in GlassFish Server Open Source Edition Administration Guide.

[[gkuff]][[GSUPG00006]][[software-update-notifier]]

Software Update Notifier

The GlassFish Server Software Update Notifier is similar to Update Tool
and the `pkg` utility in that it enables you to perform an in-place
upgrade from GlassFish Server 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 GlassFish Server 4.0, 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 link:#gkuef[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.

[[gktdz]][[GSUPG00046]][[summary-of-procedure-for-upgrading-with-upgrade-tool]]

Summary of Procedure for Upgrading With Upgrade Tool
++++++++++++++++++++++++++++++++++++++++++++++++++++

The general procedure for using Upgrade Tool to perform an upgrade to
GlassFish Server 4.0 from any compatible older version of GlassFish
Server or Enterprise Server comprises the following steps:

1. Download GlassFish Server 4.0 and perform a Standard Installation,
as described in "link:../installation-guide/toc.html#GSING00007[
To Install GlassFish Server Using the Self-Extracting File]"
in GlassFish Server Open Source Edition Installation Guide.
2. Copy any custom or third-party libraries from the older installation
to their corresponding locations in the new GlassFish Server 4.0
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.
3. Run the `asupgrade` command from the new GlassFish Server 4.0
as-install``/bin`` directory.
4. Start the new GlassFish Server 4.0 DAS with the
`asadmin start-domain` subcommand.

This procedure is described in more detail in link:#abmbr[Performing a
Side-By-Side Upgrade With Upgrade Tool].

[[gktcl]][[GSUPG00047]][[summary-of-procedure-for-upgrading-with-update-tool]]

Summary of Procedure for Upgrading With Update Tool
+++++++++++++++++++++++++++++++++++++++++++++++++++

The general procedure for using Update Tool to perform an upgrade to
GlassFish Server 4.0 from GlassFish Server 3.0.1 or Enterprise Server v3
comprises the following steps:

1. Manually stop all server instances and the domain.
2. Launch Update Tool by using the as-install-parent`/bin/updatetool`
command in the older product directory.
3. In Update Tool, select and install the latest GlassFish Server
product release. This updates your server to the 4.0 release.
4. Upgrade the domain by running the `asadmin start-domain --upgrade`
subcommand. This performs the upgrade and then shuts down the DAS.
5. Restart the DAS normally with the with the `asadmin start-domain`
subcommand.

This procedure is described in more detail in link:#gktjf[To Upgrade
Using the Update Tool GUI].

[[gkuef]][[GSUPG00048]][[summary-of-procedure-for-upgrading-with-the-software-update-notifier]]

Summary of Procedure for Upgrading With the Software Update Notifier
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The general procedure for using the Software Update Notifier to perform
an upgrade to GlassFish Server 4.0 from GlassFish Server3.0.1 or
Enterprise Server v3 comprises the following steps:

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 launch the Software Update GUI.
3. Manually stop all server instances and the domain.
4. Use the Software Update GUI to perform the upgrade. This updates
your server to the 4.0 release.
5. Upgrade the domain by running the `asadmin start-domain --upgrade`
subcommand. This performs the upgrade and then shuts down the DAS.
6. Restart the upgraded DAS normally with the with the
`asadmin start-domain` subcommand.

This procedure is described in more detail in link:#gkuhu[To Upgrade
Using the Software Update Notifier].

[[gktnb]][[GSUPG00049]][[summary-of-procedure-for-upgrading-with-the-pkg-utility]]

Summary of Procedure for Upgrading With the `pkg` Utility
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The general procedure for using the `pkg` utility to perform an upgrade
to GlassFish Server 4.0 from GlassFish Server3.0.1 or Enterprise Server
v3 comprises the following steps:

1. Manually stop all server instances and the domain.
2. Run the as-install-parent`/bin/pkg` command with the desired options
in the older product directory. This updates your server to the 4.0
release.
3. Upgrade the domain by running the `asadmin start-domain --upgrade`
subcommand. This performs the upgrade and then shuts down the DAS.
4. Restart the upgraded DAS normally with the with the
`asadmin start-domain` subcommand.

This procedure is described in more detail in link:#gktks[To Upgrade
From the Command Line Using the `pkg` Utility].

[[gjxkx]][[GSUPG00062]][[supported-releases-for-upgrade-to-glassfish-server-4.0]]

Supported Releases for Upgrade to GlassFish Server 4.0
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* Sun GlassFish Enterprise Server v2.1.1
* Sun GlassFish Enterprise Server v3
* GlassFish Server Open Source Edition 3.0.1
* GlassFish Server Open Source Edition 3.1
* GlassFish Server Open Source Edition 3.1.1

[[gkufi]][[GSUPG00063]][[upgrading-from-version-8.x-or-older-product-releases]]

Upgrading From Version 8.x or Older Product Releases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is not possible to upgrade to GlassFish Server 4.0 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 link:#gjxkx[Supported Releases for Upgrade to GlassFish Server 4.0],
you must first upgrade your older product release to one of the releases
that are supported for upgrade to GlassFish Server 4.0.

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 4.0

Sun GlassFish Enterprise Server 2.1.1 is available for download from the
http://glassfish.java.net/public/downloadsindex.html[GlassFish Community
Downloads] (`http://glassfish.java.net/public/downloadsindex.html`)
page. Instructions for upgrading to Enterprise Server 2.1.1 are provided
in http://download.oracle.com/docs/cd/E19879-01/821-0180/index.html[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 GlassFish Server 4.0.

[[gkxrp]][[GSUPG00065]][[upgrading-glassfish-server-inside-a-closed-network]]

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
"link:../administration-guide/toc.html#GSADG00575[
Extending and Updating GlassFish Server Inside a Closed Network]"
in GlassFish Server Open Source Edition Administration Guide.

[[abmbr]][[GSUPG00040]][[performing-a-side-by-side-upgrade-with-upgrade-tool]]

Performing a Side-By-Side Upgrade With Upgrade Tool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section explains how to use Upgrade Tool to perform a side-by-side
upgrade to GlassFish Server 4.0 from any compatible older product release.

The following topics are addressed here:

* link:#gktgx[Upgrade Tool Summary]
* link:#gdkix[Upgrade Tool Functionality]
* link:#gktjn[To Upgrade From the Command Line Using Upgrade Tool]
* link:#gaejn[To Upgrade Using the Upgrade Tool Wizard]

[[gktgx]][[GSUPG00066]][[upgrade-tool-summary]]

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:

* link:#gktjn[To Upgrade From the Command Line Using Upgrade Tool]
* link:#gaejn[To Upgrade Using the Upgrade Tool Wizard]

[[gdkix]][[GSUPG00067]][[upgrade-tool-functionality]]

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:

* link:#gebrv[Migration of Deployed Applications]
* link:#gebqm[Upgrade of Clusters]
* link:#gebvn[Upgrade Verification]

[[gebrv]][[GSUPG00050]][[migration-of-deployed-applications]]

Migration of Deployed Applications
++++++++++++++++++++++++++++++++++

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 GlassFish Server Open Source Edition 4.0.
Components that may have incompatibilities are deployed on GlassFish
Server 4.0 with the `compatibility` property set to `v2` and will run
without change on GlassFish Server 4.0. You may, however, want to
consider modifying the applications to conform to Java EE 6 requirements.

The Java EE 6 platform specification imposes stricter requirements than
Java 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
Java EE `library-directory` mechanism. Setting the `library-directory`
property to `v2` removes these Java 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.

[[gebqm]][[GSUPG00051]][[upgrade-of-clusters]]

Upgrade of Clusters
+++++++++++++++++++

When upgrading from a clustered configuration, the older cluster
information is retained in a new `domain.xml` file in the GlassFish
Server 4.0 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 link:#gfybw[Upgrading Clusters
and Node Agent Configurations].

[[gebvn]][[GSUPG00052]][[upgrade-verification]]

Upgrade Verification
++++++++++++++++++++

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 GlassFish Server product version; for example:

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

[[gktjn]][[GSUPG00010]][[to-upgrade-from-the-command-line-using-upgrade-tool]]

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 4.0 from any supported older product
release. See link:#gjxkx[Supported Releases for Upgrade to GlassFish
Server 4.0] for a list of supported releases.

[[sthref29]]

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 4.0 using the Typical
Installation path. +
See "link:../installation-guide/toc.html#GSING00025[
Installing GlassFish Server From a Self-Extracting Bundle]"
in GlassFish Server Open Source Edition 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 4.0
installation, not the older source installation.
====
+
* On UNIX systems
+
[source]
----
as-install/bin/asupgrade -c
----
* On Windows systems
+
[source]
----
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 link:#gaejn[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:
+
[source]
----
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 4.0 domain.
+
[source]
----
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 4.0 does not support NSS authentication. If you are
upgrading from a Enterprise Profile configuration that uses NSS
authentication, follow the procedure in link:#gktnh[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
link:#gfybw[Upgrading Clusters and Node Agent Configurations].

[[GSUPG00007]][[gktiu]]
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 GlassFish Server 4.0. The
following command should be entered on a single line.

[source]
----
asupgrade -c -s /home/glassfish/domains/domain1 -f /root/mypassword
-t /home/glassfish7/glassfish/domains
----

[[sthref30]]

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.

[width="100%",cols="<26%,<26%,<48%",options="header",]
|===
|Short Form |Long Form |Description

|`-c`
|`--console`
|Launches the upgrade command line utility.

|`-V`
|`--version`
|The version of the GlassFish Server.

|`-h`
|`--help`
|Displays the arguments for launching the upgrade utility.

|`-s` source-domain-directory
|`--source` source-domain-directory
|The domain-dir directory in the source (older) server installation.

|`-t` target-domains-directory
|`--target` target-domains-directory
|The desired domain-root-dir directory in the GlassFish Server 4.0 target
installation; default is as-install``/domains``

|`-f` password-file
|`--passwordfile` password-file
|The file containing the administration password and the master password.
|===

[[sthref31]]

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

[[gaejn]][[GSUPG00011]][[to-upgrade-using-the-upgrade-tool-wizard]]

To Upgrade Using the Upgrade Tool Wizard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This procedure explains how to use the graphical Upgrade Tool Wizard to
upgrade to GlassFish Server 4.0 from any supported older product
release. See link:#gjxkx[Supported Releases for Upgrade to GlassFish
Server 4.0] for a list of supported releases.

[[sthref32]]

Before You Begin

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

1. Download and install GlassFish Server 4.0 using the Typical Installation path. +
See "link:../installation-guide/toc.html#GSING00025[
Installing GlassFish Server From a Self-Extracting Bundle]"
in GlassFish Server Open Source Edition 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 4.0
installation, not the older source installation.
====
+
* On UNIX systems
+
[source]
----
as-install/bin/asupgrade
----
* On Windows systems
+
[source]
----
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 4.0 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 4.0 installation (for example,
`c:\glassfish7\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 4.0 does not support NSS authentication. If you are
upgrading from a Enterprise Profile configuration that uses NSS
authentication, follow the procedure in link:#gktnh[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 4.0 domain.
+
[source]
----
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
link:#gfybw[Upgrading Clusters and Node Agent Configurations].

[[sthref33]]

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

[[gkthu]][[GSUPG00041]][[performing-an-in-place-upgrade-with-the-update-center-tools]]

Performing an In-Place Upgrade With the Update Center Tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section explains how to use the three Update Center tools to
perform an in-place upgrade to GlassFish Server 4.0 from GlassFish
Server 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]
====
GlassFish Server 3.0.1 and Enterprise Server v3 are the only product
releases that can be upgraded to the 4.0 release with the Update Center
tools. If you are upgrading from any other product release, you must use
Upgrade Tool, as described in link:#abmbr[Performing a Side-By-Side
Upgrade With Upgrade Tool].
====

The following topics are addressed here:

* link:#gkthx[Update Center Tool Procedures]
* link:#gktjf[To Upgrade Using the Update Tool GUI]
* link:#gkuhu[To Upgrade Using the Software Update Notifier]
* link:#gktks[To Upgrade From the Command Line Using the `pkg` Utility]

[[gkthx]][[GSUPG00068]][[update-center-tool-procedures]]

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 4.0 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:

* link:#gktjf[To Upgrade Using the Update Tool GUI]
* link:#gkuhu[To Upgrade Using the Software Update Notifier]
* link:#gktks[To Upgrade From the Command Line Using the `pkg` Utility]

[[gktjf]][[GSUPG00012]][[to-upgrade-using-the-update-tool-gui]]

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 4.0 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.
+
[source]
----
as-install/bin/asadmin start-domain --upgrade domain-name
----
This upgrades the domain and then shuts down the DAS.

7. Start the DAS normally.
+
[source]
----
as-install/bin/asadmin start-domain domain-name
----

[[sthref34]]

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

[[gkuhu]][[GSUPG00013]][[to-upgrade-using-the-software-update-notifier]]

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

[[sthref35]]

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 4.0 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.
+
[source]
----
as-install/bin/asadmin start-domain --upgrade domain-name
----
This upgrades the domain and then shuts down the DAS.

6. Start the DAS normally.
+
[source]
----
as-install/bin/asadmin start-domain domain-name
----

[[sthref36]]

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

[[gktks]][[GSUPG00014]][[to-upgrade-from-the-command-line-using-the-pkg-utility]]

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 4.0 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 4.0.
+
[source]
----
./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.
+
[source]
----
as-install/bin/asadmin start-domain --upgrade domain-name
----
This upgrades the domain and then shuts down the DAS.

5. Start the DAS normally.
+
[source]
----
as-install/bin/asadmin start-domain domain-name
----

[[sthref37]]

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

[[gktnh]][[GSUPG00042]][[upgrading-installations-that-use-nss-cryptographic-tokens]]

Upgrading Installations That Use NSS Cryptographic Tokens
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GlassFish Server v2.x EE (Enterprise Edition) uses Network Security
Services (NSS) for cryptographic software tokens. GlassFish Server 4.0
does not support NSS, so when performing an upgrade from v2.x EE to 4.0
additional manual configuration steps must be performed.

The following topics are addressed here:

* link:#gktnq[To Prepare for the Upgrade]
* link:#gktlz[To Perform Post-Upgrade Configuration]
* link:#gktlp[To Upgrade PKCS#11 Hardware Tokens]

[[gktnq]][[GSUPG00015]][[to-prepare-for-the-upgrade]]

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

1. Download and install GlassFish Server 4.0 using the Typical Installation path. +
Ensure that you install the new GlassFish Server 4.0 product in a
directory that is different than the one used for the older installation
from which you are upgrading. +
See "link:../installation-guide/toc.html#GSING00025[
Installing GlassFish Server From a Self-Extracting Bundle]"
in GlassFish Server Open Source Edition Installation Guide for instructions.

2. Rename the new GlassFish Server 4.0 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 4.0 domain.

3. Copy the older source domain to be upgraded to the new GlassFish
Server 4.0 as-install``/domains`` directory. +
In this procedure, `domain1` is used for the older source domain that is
copied to the new GlassFish Server 4.0 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 4.0 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:
+
[source]
----
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`.
[arabic]
.. Add the following `jvm-options` under `server-config` and
`default-config`:
+
[source]
----
-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` under `server-config` and
`default-config`:
+
[source]
----
-Dcom.sun.appserv.nss.db=${com.sun.aas.instanceRoot}/config
----

6. Upgrade `./domain1` by starting the DAS in the new GlassFish Server 4.0
installation with the `--upgrade` option.
+
[source]
----
as-install/bin/asadmin start-domain --upgrade domain1
----
This upgrades the domain and then shuts down the DAS.
7. Start the upgraded DAS normally.
+
[source]
----
as-install/bin/asadmin start-domain domain1
----

[[gktlz]][[GSUPG00016]][[to-perform-post-upgrade-configuration]]

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

[[sthref38]]

Before You Begin

Before proceeding with this procedure, complete the procedure explained
in link:#gktnq[To Prepare for the Upgrade].

1. Start the GlassFish Server 4.0 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 link:#gktnq[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:
+
[source]
----
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.
+
[source]
----
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 4.0 domain. The following command can be used to list all the
`KeyEntries` in the NSS database:
+
[source]
----
certutil -L -d $AS_NSS_DB
----
`AS_NSS_DB` should point to the `${com.sun.aas.instanceRoot}/config` for
the 4.0 instance into which the v2.x domain was copied. The listing with
the attribute combinations `u,u,u` are the `KeyEntries`. +
For example:
+
[source]
----
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:
+
[source]
----
> 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 4.0 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`.
+
[source]
----
>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.
[arabic]
.. `certutil -L -d $AS_NSS_DB` +
Example output:
+
[source]
----
verisignc1g1 T,c,c
verisignc1g2 T,c,c
verisignc1g3 T,c,c
----
.. `keytool -list -keystore cacerts.jks -storepass` v3-master-password +
Example output:
+
[source]
----
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 4.0 domain's
`truststore`.
+
[source]
----
>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 4.0
default `truststore`.
====


[[gktlp]][[GSUPG00017]][[to-upgrade-pkcs11-hardware-tokens]]

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-4.0 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 4.0 to PKCS11.
+
[source,xml]
----
<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.
+
[source,xml]
----
<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:
+
[source,xml]
----
<jvm-options>-Djavax.net.ssl.trustStore=NONE</jvm-options>
<jvm-options>-Djavax.net.ssl.trustStoreType=PKCS11</jvm-options>
----

[[gfybw]][[GSUPG00043]][[upgrading-clusters-and-node-agent-configurations]]

Upgrading Clusters and Node Agent Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section explains additional steps you need to perform when
upgrading cluster and node agent configurations from Application Server
or Enterprise Server to GlassFish Server 4.0.

GlassFish Server 4.0 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 GlassFish Server 4.0
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 GlassFish Server 4.0 on each node host and manually re-create
the server instances that are contained in the clusters.

The following topics are addressed here:

* link:#gkyda[Overview of Cluster and Node Agent Upgrade Procedures]
* link:#gktle[To Correct the Configuration of a Node After an Upgrade]
* link:#gktkx[To Re-Create a Cluster]

[[gkyda]][[GSUPG00069]][[overview-of-cluster-and-node-agent-upgrade-procedures]]

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 4.0 are as follows:

1. Perform a side-by-side upgrade of the DAS. This procedure is
described in link:#abmbr[Performing a Side-By-Side Upgrade With Upgrade Tool].

2. Perform new (not upgrade) GlassFish Server 4.0 installations on each
node host. GlassFish Server 4.0 installation instructions are provided
in the link:../installation-guide/toc.html#GSING[
GlassFish Server Open Source Edition Installation Guide].

3. Correct the node configuration on the upgraded DAS, if necessary.
This procedure is described in link:#gktle[To Correct the Configuration
of a Node After an Upgrade].

4. Re-create the clusters and server instances on each GlassFish Server 4.0 node host.
This procedure is described in link:#gktkx[To Re-Create a Cluster].

[[gktle]][[GSUPG00018]][[to-correct-the-configuration-of-a-node-after-an-upgrade]]

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 link:#gktkx[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/glassfish7`. +
The default is the parent of the default base installation directory of
the GlassFish Server 4.0 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
"link:../ha-administration-guide/nodes.html#GSHAG00004[Administering GlassFish Server Nodes]" in GlassFish
Server Open Source Edition High Availability Administration Guide.

[[sthref39]]

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 link:#abmbr[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
"link:../ha-administration-guide/ssh-setup.html#GSHAG00003[
Setting Up SSH for Centralized Administration]" in
GlassFish Server Open Source Edition High Availability Administration Guide.

* If you are upgrading from an Enterprise Profile configuration that
uses NSS authentication, ensure that the procedure in
link:#gktnh[Upgrading Installations That Use NSS Cryptographic Tokens]
has been performed. GlassFish Server 4.0 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 link:../reference-manual/update-node-ssh001.html#GSRFM00256[`update-node-ssh`(1)] help
page or the link:../reference-manual/update-node-config.html#GSRFM00255[`update-node-config`(1)] help page.
====

[source]
----
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/glassfish7`.
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.

[[GSUPG00008]][[gktoh]]
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.

[source]
----
asadmin> update-node-config --nodedir /export/home/gf/nodes xk01
Command update-node-config executed successfully.
----

[[sthref40]]

Next Steps

Re-create the cluster configuration from the older source installation
in the new GlassFish Server 4.0 installation in as explained in
link:#gktkx[To Re-Create a Cluster].

[[sthref41]]

See Also

* "link:../ha-administration-guide/ssh-setup.html#GSHAG00003[
Setting Up SSH for Centralized Administration]" in
GlassFish Server Open Source Edition High Availability Administration Guide
* "link:../ha-administration-guide/nodes.html#GSHAG00004[Administering GlassFish Server Nodes]"
in GlassFish Server Open Source Edition High Availability Administration Guide
* link:../reference-manual/update-node-config.html#GSRFM00255[`update-node-config`(1)]
* link:../reference-manual/update-node-ssh001.html#GSRFM00256[`update-node-ssh`(1)]

[[gktkx]][[GSUPG00019]][[to-re-create-a-cluster]]

To Re-Create a Cluster
^^^^^^^^^^^^^^^^^^^^^^

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

[[sthref42]]

Before proceeding with these instructions, ensure that you have
completed the following procedures:
--
* Perform the standard upgrade to GlassFish Server 4.0 on the DAS, as
described in link:#abmbr[Performing a Side-By-Side Upgrade With Upgrade Tool].

* Perform a new (not upgrade) installation of GlassFish Server 4.0 on
each node host. See the link:../installation-guide/toc.html#GSING[
GlassFish Server Open Source Edition Installation Guide] for instructions.

* Correct the upgraded node configuration, if necessary, as described
link:#gktle[To Correct the Configuration of a Node After an Upgrade].
--

1. Start the upgraded DAS.
+
[source]
----
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.
+
[source]
----
asadmin> get-health cluster-name
----
For example, for the sample `cluster1` used in this procedure:
+
[source]
----
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
"link:../ha-administration-guide/instances.html#GSHAG00125[
To Resynchronize an Instance and the DAS Offline]"
in GlassFish Server Open Source Edition 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:

** "link:../ha-administration-guide/instances.html#GSHAG00114[
To Create an Instance Locally]"
in GlassFish Server Open Source Edition High Availability Administration Guide

** "link:../ha-administration-guide/instances.html#GSHAG00119[
To Resynchronize an Instance and the DAS Online]"
in GlassFish Server Open Source Edition 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
link:#gktle[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 4.0 installation.

5. If necessary, start the cluster. +
For example:
+
[source]
----
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.

[[GSUPG00009]][[gkyin]]
Example 2-3 Creating Two Local Instances

The following example shows how to create two local instances in a
cluster.

[source]
----
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.

[[gkrfh]][[GSUPG00044]][[correcting-potential-upgrade-problems]]

Correcting Potential Upgrade Problems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section addresses issues that can occur during an upgrade to
GlassFish Server 4.0.

The following topics are addressed here:

* link:#gkrgh[Cluster Profile Security Setting]
* link:#gkrib[Cluster Profile Upgrade on Windows]
* link:#gkyho[`asupgrade` Fails Without Internet Connection]

[[gkrgh]][[GSUPG00070]][[cluster-profile-security-setting]]

Cluster Profile Security Setting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When upgrading a clustered domain configuration from Application Server
9.1 or Enterprise Server v2 to GlassFish Server 4.0, 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:
+
[source]
----
asadmin> get configs.config.server-config.admin-service.jmx-connector.system.security-enabled
----
* To display the value for the type attribute:
+
[source]
----
asadmin> get configs.config.server-config.admin-service.type
----

If necessary, use the `set` subcommand to set `security-enabled=false`.
For example:

[source]
----
asadmin> set configs.config.server-config.admin-service.jmx-connector.system.security-enabled=false
----

[[gkrib]][[GSUPG00071]][[cluster-profile-upgrade-on-windows]]

Cluster Profile Upgrade on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On Windows, when you upgrade cluster profile domains, you could
encounter the following error:

[source]
----
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.

[[gkyho]][[GSUPG00072]][[asupgrade-fails-without-internet-connection]]

`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.
+
[source]
----
asadmin> start-domain --upgrade domain-name
----