| 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:\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`. |
| |
| [[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. |
| |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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. |
| |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| 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. + |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| as-install/bin/asupgrade -c |
| ---- |
| * On Windows systems + |
| [source,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| asadmin start-domain domain-name |
| ---- |
| Log in to the Administration Console with the user name and password you |
| used in the older server. + |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| asupgrade -c -s /home/glassfish/domains/domain1 -f /root/mypassword |
| -t /home/glassfish3/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. + |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| as-install/bin/asupgrade |
| ---- |
| * On Windows systems + |
| [source,oac_no_warn] |
| ---- |
| as-install\bin\asupgrade.bat |
| ---- |
| :: |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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:\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. + |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| 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 |
| |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| ./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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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. + |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| 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`: + |
| [source,oac_no_warn] |
| ---- |
| -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`: + |
| [source,oac_no_warn] |
| ---- |
| -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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| s1as u,u,u |
| ---- |
| :: |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| > 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 |
| ---- |
| :: |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| >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: + |
| [source,oac_no_warn] |
| ---- |
| verisignc1g1 T,c,c |
| verisignc1g2 T,c,c |
| verisignc1g3 T,c,c |
| ---- |
| 2. `keytool -list -keystore cacerts.jks -storepass` v3-master-password + |
| Example output: + |
| [source,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| >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 |
| ---- |
| :: |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| <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,oac_no_warn] |
| ---- |
| <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,oac_no_warn] |
| ---- |
| <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/glassfish3`. + |
| 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. + |
| |
| [width="100%",cols="<100%",] |
| |======================================================================= |
| a| |
| 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,oac_no_warn] |
| ---- |
| 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. |
| |
| [[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,oac_no_warn] |
| ---- |
| 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 You Begin |
| |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| asadmin> get-health cluster-name |
| ---- |
| For example, for the sample `cluster1` used in this procedure: + |
| [source,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| asadmin> get configs.config.server-config.admin-service.jmx-connector.system.security-enabled |
| ---- |
| * To display the value for the type attribute: + |
| [source,oac_no_warn] |
| ---- |
| asadmin> get configs.config.server-config.admin-service.type |
| ---- |
| |
| If necessary, use the `set` subcommand to set `security-enabled=false`. |
| For example: |
| |
| [source,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| 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,oac_no_warn] |
| ---- |
| asadmin> start-domain --upgrade domain-name |
| ---- |
