test

Sun GlassFish Web Space Server 10.0 Installation Guide

Upgrading an Existing Web Space Server Installation

This section provides instructions for upgrading an existing Web Space Server 10.0 installation with the latest Update release.

Upgrades to Web Space Server and Web Space Server plugins are performed in either of thre ways:

Note –

Update Tool can be used to upgrade Web Space Server and Web Space Server plugins. However, when using a Web Space Server administrator account from within a Web Space Server session, only plugins can be upgraded, and it is recommended that only community or private plugins be upgraded in this way. In general, you should perform all upgrades using Upgrade Tool.

Using Update Tool

After installing the core Web Space Server 10.0 software, updates to Web Space Server and any plugins can be performed entirely through the Update Tool that is bundled with Web Space Server 10.0.

Note –

The version of Update Tool included with some versions of GlassFish Enterprise Server is not compatible with the Web Space Server update repositories. You must use the version of Update Tool that comes with Web Space Server 10.0 software rather than the version that is bundled with GlassFish .

Update Tool also includes a command-line (CLI) Image Packaging System (IPS) utility, called pkg, that provides the same core functionality as its GUI-based counterpart. This IPS tool is started with the ws-install-dir/bin/pkg command. See the Update Center wiki for complete information about Update Tool and the pkg command.

You can install Web Space Server 10.0 Update components through either the Update Tool GUI or with the pkg CLI utility.

ProcedureTo Determine the Current Web Space Server Version

Before installing a Web Space Server Update package, or when performing Web Space Server maintenance tasks in general, it is often useful to know the full version information about the currently running Web Space Server installation. This information can be displayed through Update Center, but the quickest and most complete information is found the Web Space Server version file.

  1. In a command shell, change to the ws-install-dir/var/webspace directory, and display the contents of the version.


    cd ws-install-dir/var/webspace
less version

    For example, the following version information is returned for Web Space Server Update 5:


    Version=10.0.5
Build=1.19
Revisions=1626-31998-26479
VanityVersion=Web Space Server 10.0 Update 5

ProcedureTo Install the Update Components Using the GUI-Based Update Tool

This procedure explains how to install an Update patch on top of an existing Web Space Server 10.0 installation using the GUI-based Update Tool. If you prefer to use the pkg command line tool, see To Install the Update Components Using the CLI-Based pkg Tool.

Before You Begin

Note the following before you begin the Update installation:

  1. In a command shell for your operating system, change to the ws-install-dir/bin directory and run the updatetool command.

    If this is the first time you have launched updatetool, the full Update Tool product will not yet be installed, and you are prompted to allow installation to proceed.

    1. Type y when prompted to install Update Tool.

      The installer downloads and installs the full Update Tool product and then exits.

    2. Enter the updatetool command again to launch Update Tool.

    The Update Tool main window is displayed, with Available Updates highlighted.

  2. (Optional) Specify proxy server settings, if necessary.

    This step is only required if you are using Update Tool from behind a firewall that implements a proxy server.

    1. Click Preferences in the Update Tool main window to display the proxy server settings dialog.

    2. Enter your proxy settings, and then close the dialog to return to the Update Tool main screen.

  3. Click the Web Space node in the Application Images pane on the left in Update Tool.

    Details about the currently selected software repositories are displayed. To get the Web Space Server updates, the update repository URL must be modified in this list.

  4. Click Edit Properties on the right side of the Image Details pane.

    The repositories displayed by default depend on the version of Web Space Server you are using.

    • If you are using Web Space Server Update 6:

      1. Select the webspace.sun.com repository in the Image Properties dialog, and then click Edit.

      2. In the Repository Properties dialog, modify the Repository URL so it reads:


        http://pkg.sun.com/webspace/10/_support_

      3. Click OK twice to return to the Update Tool main window.

    • If you are using Web Space Server Update 5 or earlier:

      1. Select the support.sun.com repository in the Image Properties dialog, and then click Edit.

      2. In the Repository Properties dialog, modify the Repository URL so it reads:


        http://pkg.sun.com/webspace/10/_support_

      3. Click OK twice to return to the Update Tool main window.

    • Verify that the support.sun.com repository is now Enabled and selected as Preferred.

  5. Back in the Update Tool main window, choose the Available Updates node in the Application Images pane to display the list of available Updates.

    The available updates and their associated WAR files are displayed. It is recommended that you always choose the latest available update.

  6. Select the Web Space Server update package you want to install, and then click Install to install the update.

  7. Restart the application server.

    For example, if running GlassFish Enterprise Server, use the following commands:


    cd gf-install-dir/bin
./asadmin stop-domain domain_name
./asadmin start-domain domain_name

  8. Change to the ws-install-dir/webspace/application directory.

  9. Run the Ant install.xml script to regenerate and redeploy the Web Space Server WAR files.


    ant -f install.xml

  10. Restart the application server once again.

    For example, if running GlassFish Enterprise Server:


    cd gf-install-dir/bin
./asadmin start-domain domain_name

ProcedureTo Install the Update Components Using the CLI-Based pkg Tool

This procedure explains how to install an Update patch on top of an existing Web Space Server 10.0 installation using the CLI-based pkg utility. If you prefer to use the GUI-based Update Tool, see To Install the Update Components Using the GUI-Based Update Tool.

Before You Begin

Note the following before you begin the Update installation:

  1. In a command shell for your operating system, change to the ws-install-dir/bin directory and run the updatetool command.

    If this is the first time you have launched updatetool, the full Update Tool product will not yet be installed, and you are prompted to allow installation to proceed.

  2. Type y when prompted to install Update Tool.

    The installer downloads and installs the full Update Tool product and then exits.

  3. Change to the ws-install-dir/pkg/bin directory.

  4. Use the pkg command to download the Update components.

    • If you are using Web Space Server Update 6, enter the following command:


      pkg set-publisher -O http://pkg.sun.com/webspace/10/_support_ webspace.sun.com

    • If you are using Web Space Server Update 5 or earlier, enter the following command:


      pkg set-authority -P --enable -O http://pkg.sun.com/webspace/10/_support_ support.sun.com

  5. Enter the following command to install the Update components:


    pkg image-update

  6. Restart the application server.

    For example, if running GlassFish Enterprise Server, use the following commands:


    cd gf-install-dir/bin
./asadmin stop-domain domain_name
./asadmin start-domain domain_name

  7. Change to the ws-install-dir/webspace/application directory.

  8. Run the Ant install.xml script to regenerate and redeploy the Web Space Server WAR files.


    ant -f install.xml

  9. Restart the application server.

    For example, if running GlassFish Enterprise Server:


    cd gf-install-dir/bin
./asadmin start-domain domain_name

ProcedureTo Use Update Tool With an Older Version of Web Space Server Behind a Proxy That Requires Authentication

When using Update Tool to upgrade a version of Web Space Server prior to Update 5, a workaround is required when performing the upgrade from behind a proxy server that requires authentication.

Before You Begin

The workaround presented here is only required when updating Web Space Server versions prior to Update 5. Web Space Server Update 5 and later are bundled with Update Center 2.2, which supports proxy authentication and therefore does not require this workaround. See To Determine the Current Web Space Server Version for instructions on displaying the current Web Space Server version.

  1. Download Update Center 2.2 package suitable for your platform from the Update Center wiki.

  2. Unzip the Update Center 2.2 package to the temporary directory of your choice.

    In this example, the temporary directory is named /tmp/uc2.2, and the package is for the Sun Solaris x86 operating environment.

  3. Copy the pkg-bootstrap.jar and pkg-client.jar files from /tmp/uc2.2/pkg-toolkit-platform_name/pkg/lib to the ws-install-dir/pkg/lib directory.

  4. Change to the ws-install-dir/bin directory and run the updatetool command.

    You are prompted to specify the proxy host and port.

  5. Enter the proxy information as prompted.

    The latest versions of the updatetool and pkg files are downloaded and installed.

  6. Run updatetool again, and proceed with the Web Space Server update, as described in To Install the Update Components Using the GUI-Based Update Tool or To Install the Update Components Using the CLI-Based pkg Tool.

Using a Web Space Server Administrator Account

In addition to Using Update Tool, upgrades to Web Space Server plugins can be performed directly from a Web Space Server Administrator account.

Note –

Performing upgrades in this way requires that Update Tool be installed and upgrade servers configured as described in Using Update Tool. Also note that only plugins can be upgraded from within aWeb Space Server session; Web Space Server core components cannot be upgraded from within a running Web Space Server session. Moreover, it is recommended that only community or private plugins be upgraded in this way. Because of this, performing upgrades through a Web Space Server Administrator account in a running Web Space Server session is typically only a supplementary means for performing upgrades using Update Tool.

ProcedureTo Perform Upgrades Through a Web Space Server Administrator Account

Before You Begin

Update servers must be initially configured using Update Tool, as described in Using Update Tool.

  1. Log in to Web Space Server using an Administrator account.

    If updates are available, a prompt is displayed at the top of the Web Space Server window.

  2. Click the “Updates are available for Web Space” link.

    Click Close if you do not want to perform updates at this time.

    Clicking the “Updates are available” link displays the Update Manger Page. Components for which updates are available are displayed with Update Available in the Status column.

  3. Click the Action button next to the updates you want to install.

ProcedureTo Enable or Disable Update Prompts in a Web Space Server Administrator Account

The display of update prompts in a Web Space Server Administrator account can be enabled or disabled by setting the plugin.notifications.enabled property to true or false in the portal-ext.properties file.

  1. In a command shell, change to the ws-install-dir/var/webspace/war-workspace/customs/webspace/WEB-INF/classes directory.

  2. Edit the portal-ext.properties file, as follows:

    • To enable update prompts:


      plugin.notifications.enabled=true

    • To disable update prompts:


      plugin.notifications.enabled=fales

  3. Change to the ws-install-dir/var/webspace/war-workspace directory and run the synchronize.xml Ant script.


    cd ws-install-dir/var/webspace/war-workspace
ant -f synchronize.xml

    The Web Space Server domain is stopped by the synchronize.xml script.

  4. Restart the Web Space Server domain.


    cd gf-install-dir/bin
asadmin start-domain

Performing Upgrades in Offline Mode

In some cases, a Web Space Server installation might be configured such that the server cannot access the public Internet. For example, Web Space Server might be installed behind a restrictive firewall, or it might be installed on a LAN that is physically isolated from other networks for security reasons. In such cases, Update Tool cannot contact a remote repository to download updates, so a local repository server must be configured and the updates installed from there.

Configuring Web Space Server for offline updates comprises four general procedures:

  1. Install and configure Update Tool to work without an Internet connection.

  2. Configure and run a local repository server daemon on a locally accessible host.

  3. Configure Update Tool on the machines to be upgraded to use the local repository.

  4. Install the Web Space Server updates.

Figure Figure 2–3 illustrates this process.

Figure 2–3 Offline Update Procedure

Offline Update Procedure

These procedures are described in the following sections:

ProcedureTo Install Update Tool Without an Internet Connection

GlassFish Enterprise Server and Web Space Server both include bundled versions of the GlassFish Update Tool. However, to reduce the size of the product bundles and provide greater cross-platform compatibility, only stub (bootstrap) installer components for Update Tool are actually provided. As described in Using Update Tool, the first time Update Tool is launched after a fresh installation, the full product bits for Update Tool are automatically downloaded and installed. After installing the full Update Tool product bits, Update Tool can be run in online or offline mode, depending on the location of the repository to which you want to connect.

The above default scenario requires an Internet connection to download the full Update Tool product bits. To get around this requirement in environments where an Internet connection is not possible, you must manually obtain and install Update Tool, as described in this procedure.

Note –

When Update Tool is installed as described in this procedure, it can only be run in command-line (CLI) mode. It is not possible to run the Update Tool GUI when installed using this procedure.

Before You Begin

Access to some Internet-connected machine outside your secure network is required for the first part of this procedure. This Internet-connected machine must be one to which Update Tool can be downloaded and saved to some type of removable media, such as CD, DVD, USB drive, or flash memory card.

  1. Download the pre-installed toolkit image ZIP bundle for your server's operating environment from the Pre-installed Toolkit Images and Starter Repositories wiki page and save it to the location of your choice.

  2. Copy the downloaded toolkit image ZIP file or the expanded archive to the removable medium of your choice.

    For example, you might want to copy the ZIP file to a USB flash drive or SD card, or extract the ZIP and burn the files to a CD. The goal is to copy the toolkit image files onto a medium that you can then physically transport into the secured network area and then copy to a server on that secured network.

    In most cases, the download ZIP file size is approximately 4MB. The size of the expanded ZIP file varies depending on the package you download. On Windows, the expanded ZIP is approximately 11MB; on Linux and Solaris, approximately 13MB.

  3. Copy or expand the toolkit image in the directory of your choice on the following host machines:

    • The server on which the secure network repository server daemon will be run

    • The server(s) on which Web Space Server is running and will be updated

    Depending on your secure network configuration and the number of Web Space Server hosts involved, the repository server daemon and the Web Space Server software may be running on different hosts or the same host.

    Regardless of the host machine used, the directory in which the toolkit image is extracted is referred to for the remainder of these instructions as tookit-dir.

  4. In a command shell on the desired host machine, change to the tookit-dir/pkg/bin directory.

  5. Run the following command to verify that the pkg tool is installed correctly.


    ./pkg --help

    A list of available pkg subcommands and options should be displayed.

ProcedureTo Configure a Local Update Repository Server

This procedure describes how to get the standalone Web Space Server repository and then configure a local repository server in a secure (not connected to the Internet or other network) LAN. This local repository server will subsequently be used to provide updates to other Web Space Server hosts within the secure LAN.

Before You Begin

This procedure assumes that Update Tool has been installed as described in To Install Update Tool Without an Internet Connection. As described in that procedure, access to some Internet-connected machine outside your secure network is required for the first part of the procedure in this section. This Internet-connected machine must be one to which the standalone Web Space Server repository can be downloaded and saved to some type of removable media.

  1. Download the standalone Web Space Server repository and save it to the location of your choice.

    Ask your Web Space Server support representative for the location of the correct repository to use.

  2. Copy the downloaded repository ZIP file or the expanded archive to the removable medium of your choice.

    The goal here is to copy the repository files onto a medium that you can then physically transport into the secure network area and then copy to a server on that secured network.

    The Web Space Server standalone repository ZIP file is approximately 2.6GB, and approximately 3GB when expanded. Because of this large file size, the most practical media format for the standalone repository is, in most cases, either DVD or removable hard drive (USB or hot swappable).

  3. Expand (unzip) the Web Space Server repository archive in the directory of your choice on the server that will be used to run the Update Tool repository server daemon.

    This directory should be different than the directory in which the Update Tool toolkit image was expanded, as described in To Install Update Tool Without an Internet Connection.

    The directory in which the Web Space Server repository image is extracted is referred to for the remainder of these instructions as repository-dir. The directory in which the Update Tool toolkit image is extracted is referred to as toolkit-dir.

  4. Start the repository server daemon from a command prompt on the desired secure network machine.

    Use the following command syntax:


    toolkit-dir/pkg/bin/pkg.depotd  --readonly -d repository-dir -p port

    For port, specify the port number of your choosing. The default port is 80.

    Several startup messages are displayed as the repository daemon initializes; for example:


    [date/time] ENGINE Listening for SIGHUP.
[date/time] ENGINE Listening for SIGTERM.
[date/time] ENGINE Listening for SIGUSR1.
[date/time] ENGINE Bus STARTING
[date/time] ENGINE Started monitor thread '_TimeoutMonitor'.
[date/time] ENGINE Serving on 0.0.0.0:81
[date/time] ENGINE Bus STARTED

ProcedureTo Configure Update Tool to Use a Local Repository

After downloading the Web Space Server repository image and starting the repository server daemon on the secure network, as described in To Configure Update Tool to Use a Local Repository, the next step is to configure the secure Web Space Server host on which updates are to be performed. The goal in this procedure is to configure the Web Space Server host to use the local update repository image rather than the default behavior of going out on the Internet to access a remote update repository.

Before You Begin

The Update Tool repository toolkit must be installed on each Web Space Server host for which updates will be performed, as described in To Install Update Tool Without an Internet Connection.

  1. From a command shell on the Web Space Server host you want to upgrade, use the pkg set-publisher command to redirect Update Tool to use the local repository rather than a remote repository.

    Use the following command syntax:


    toolkit-dir/pkg/bin/pkg -R ws-install-dir set-publisher -Pe -O http://repo-host:port/ pubname

    Where:

    • ws-install-dir is the path to the directory containing the Web Space Server installation that is to be updated

    • repo-host is the name of the server on which the pkg.depotd repository server daemon is running

    • port is the port use for the pkg.depotd daemon, as specified in To Configure a Local Update Repository Server.

    • pubname is the name of the preconfigured Web Space Server publisher. For Web Space Server, use webspace.sun.com

    For example, to specify a Web Space Server installation directory named /opt/wssonfoo, and a Web Space Server repository server running on port 81 on a host named foo, enter the following command:


    toolkit-dir/pkg/bin/pkg -R /opt/wssonfoo set-publisher -Pe -O http://foo:81 webspace.sun.com

ProcedureTo Install Updates From a Local Repository

The final procedure in the offline update process is to use install the Web Space Server updates on the desired Web Space Server host(s).

Before You Begin

Note the following before you begin the Update installation:

  1. In a command shell on the Web Space Server host on which updates will be installed, enter the following command to install the Update components:


    toolkit-dir/pkg/bin/pkg image-update

  2. Restart the application server.

    For example, to restart GlassFish Enterprise Server:


    cd gf-install-dir/bin
./asadmin stop-domain domain_name
./asadmin start-domain domain_name

  3. Change to the ws-install-dir/webspace/application directory.

  4. Run the Ant install.xml script to regenerate and redeploy the Web Space Server WAR files.


    ant -f install.xml

  5. Restart the application server once more.

    For example, if using GlassFish:


    cd gf-install-dir/bin
./asadmin start-domain domain_name