The Java Web Server installs "out of the box" with a default configuration. Customizations refer to any changes you have made to that default configuration. For example, you may have changed the port through which clients access documents served by the web server. Or you may have installed and configured your own servlets or CGI scripts.

This document provides guidance on migrating your existing Java Web Server 1.1.3 customizations over to a new Java Web Server 2.0 installation. Because the opportunities for customization are extensive, this document can not address every possibility. However, it should prove a valuable guide and reminder of what to consider when migrating customizations.

Note: If your customizations were minor or few, you may prefer to simply install Java Web Server 2.0 and repeat your customizations on the new installation, rather than attempting to migrate them from the old verions. The choice is yours.

This document has the following sections:

• Requirements
• Approach
• Migrating Customizations
  1. Executables
     • servlets and servletbeans
     • cgi scripts
     • startup scripts
  2. Log information
  3. Security
     • certificates
     • realms
     • custom realms
  4. Environment settings
     • PATH
     • CLASSPATH
     • JAVA_HOME
     • LD_LIBRARY_PATH
  5. Properties
     • ports
     • servlet aliases
     • file aliases
  6. Documents
  7. Other possible customizations

Requirements

These instructions assume two Java Web Server installations--an existing, customized installation of Java Web Server 1.1.3 and a new, default installation of Java Web Server 2.0. These installations must be in separate directories.

• If your existing Java Web Server 1.1.3 is using the default port settings, reset those port numbers before installing Java Web Server 2.0. If you do not reset them, you will experience port conflicts when the Java Web Server 2.0 attempts to install services on the existing, active ports.

  Java Web Server 1.1.3 Service	Default	Temporary	For instructions, see:
  Web Service	8080	8085	Administration Tool: Network Setup online document.
  Secure Service	7070	7075	Administration Tool: Network Setup online document.
  AdminTool (external)	9090	9095	Administration Tool: Properties online document.
  AdminTool (internal	9091	9096	Administration Tool: Properties online document.

  
   
• To install the new Java Web Server 2.0, follow the installation instructions provided with the Java Web Server 2.0 product

Approach

The general approach will be to identify and copy files from the existing Java Web Server 1.1.3 installation to the new installation. Once files have been identified and copied (not moved), the Administration Tool for the two installations is run in parallel and property settings (customizations) verified on a screen-by-screen basis.

Migrating Existing Customizations

The following steps guide you through the steps of migration in the order they need to be performed. If you have made no customizations in a particular area, simply skip that step and move on to the next.

1. Executables
   • Servlets and servlet beans

     Copy all your servlet and servlet bean files from your Java Web Server 1.1.3 to your Java Web Server 2.0 installation.

     • For example, you might have servlets under development located in the servlets or servletbeans directory of the web server:

       % cp /opt/JavaWebServer1.1.3/servlets/myServlet.class 
       /opt/JavaWebServer2.0/servlets/ (on UNIX)
       
       C:\>cp C:\JavaWebServer1.1.3/servlets/myServlet.class  
       C:\JavaWebServer2.0/servlets/myServlet.class (on Windows) 
       

     • Or, you might have servlets ready for deployment located in some other directory you created in the web server:

       % mkdir /opt/JavaWebServer2.0/classes
       % cp /opt/JavaWebServer1.1.3/classes/myServlet.class 
       /opt/JavaWebServer2.0/servlets/ (on UNIX)
       
       

       D:\>mkdir C:\JavaWebServer2.0/classes
       D:\>cp C:\JavaWebServer1.1.3/classes/myServlet.class  
       C:\JavaWebServer2.0/servlets/myServlet.class (on Windows) 
       

       
        

     Changed in 2.0 In Java Web Server 1.1.3, servlet examples resided in server_root/servlets. In Java Web Server 2.0, servlet examples now reside in server_root/servlets/sunexamples.

   • CGI scripts
     1. If you did not use the default CGI script directory, cgi-bin, create your custom CGI script directory in the new installation.
         
     2. Copy all your CGI script files from the old installation to the new. For example, if you used the default CGI script directory, cgi-bin:

          % cp /opt/JavaWebServer1.1.3/cgi-bin/myScript
               to /opt/JavaWebServer2.0/cgi-bin/myScript
        

     3. If you used a custom-named CGI script directory, update the cgi servlet alias in the Administration Tool to reflect that directory name.

        Note: Although the default CGI script directory is the same for both the webpage and secure services, it is possible to designate a different CGI directory for each. If you have done so, you must repeat the CGI script migration instructions for each service.
         

   • Startup files

     If you were starting the old Java Web Server automatically, you will need to remove it from automatic startup and add the new Java Web Server instead.

     (More details on starting the Java Web Server automatically, can be found in the Starting the Java Web Server online document.)

     • Solaris:

       1. Stop your java-server startup script for JWS1.1.3. For example:
          /etc/rc3.d/K42jserv stop
           
       2. If you modified your java-server startup script file(s) for Java Web Server 1.1.3, you need to make similar modifications to your java-server startup script file(s) for Java Web Server 2.0.

          Repeat the instructions in the java-server.startup file, including moving, renaming, and linking the file. Edit the file in the new installation to reflect similar customizations to those you made to the same file in the old installation.
           

       3. Test the new script files by typing:
          /etc/rc3.d/S42jserv start
           
     • NT:
       1. Stop your Java Web Server NT service. For example, click the stop button in the services control panel.
           
       2. If you created and used jservargs.txt file in old-server-root\bin, copy the file to new-server-root\bin.
           
       3. If you have VM arguments in your jservargs.txt file, consider moving them to vmargs.txt file. In addition to jservargs.txt file, you could add vmargs.txt file to each VM, adminserver or javawebserver VM, in the JWS2.0 version.  For more information regarding vmargs.txt, please see the Release Notes document.
           
       4. Remove your Java Web Server NT service.  For example, if you used default Java Web Server NT service name, JavaWebServer:
          D:\> C:\JavaWebServer1.1.3\bin\jservsvc JavaWebServer remove
           
       5. Add your new Java Web Server NT service. For example, if you want to use default Java Web Server NT service name, JavaWebServer:
          D:\> C:\JavaWebServer2.0\bin\jservsvc Java Web Server install
           
       6. You should be able to start it by clicking the start button in the Services control panel.
           
2. Log Information

   We expect little, if any, demand to migrate log information from 1.1.3 to 2.0. Due to changes in the log files and formats for Java Web Server 2.0, such migration is not recommended.

   However, you may wish to simply keep your old logs in the same location as your new logs. This may be accomplished by renaming* the old log files to avoid conflict and then moving them to the new location.

   * We recommend you use a name that indicates the product version and/or date of discontinuation of the log file. For example: rename access_log to jws20_access_03jun99.
    

3. Security

   Follow these instructions only if SSL was setup on the old version. If you are not sure, look for a keys file in old-server-root/ of the old installation. If the file exists, it means SSL was set up and you should follow the migration instructions in this section. If the file does not exist, skip this section.

   • Certificate information

     Copy keys, CAstore, and keys.passphrase files from old-server-rootto new-server-root

     In Java Web Server 1.1.3, the CAstore file might be in the machine's root directory (/ or C:\). For Solaris only, it might instead be in the user's home directory* such as /home/$user CAstore file should be there only if you imported root certificates and keys.passphrase file should be there only if you created this file to contain password of passphrase.

     * This bug, ID 4198423, has been fixed in 2.0 version. CAstore should only be in server-root if you imported root certificates. If you do copy over your CAstore file from 1.1.3 version, it must be placed in 2.0 server-root. keys.passphrase file should be in server-root only if you created this file to contain password of passphrase
      .

   • Realm information
     1. Back up your current realm files in the old installation. For example:
        % mv /opt/JavaWebServer2.0/realms /opt/JavaWebServer2.0/realms_bak
          (UNIX)
         
        D:\> ren c:\JavaWebServer2.0\realms c:\JavaWebServer2.0\realms_bak   (Windows)
         
     2. Copy the realm files recursively from old-server-root/realms to new-server-root/realms. For example:
        % mkdir /opt/JavaWebServer2.0/realms   (UNIX)
        % cp -R /opt/JavaWebServer1.1.3/realms/* /opt/JavaWebServer2.0/realms
         
        D:\> ren c:\JavaWebServer2.0\realms c:\JavaWebServer2.0\realms_bak
        D:\> mkdir c:\JavaWebServer2.0\realms
        D:\> xcopy c:\JavaWebServer1.1.3\realms c:\JavaWebServer2.0\realms /E
         
4. Environment Settings

   If you have modified any environment variables for use with Java Web Server 1.1.3, remove or revise those values to reflect the new Java Web Server 2.0 installation.

   Typical examples of this include:

   • If you have added servlet classes to your CLASSPATH.
   • If you have been using your JAVA_HOME to indicate a JDK other than that bundled with Java Web Server.
   • If you have been using native code--DLLs pointed to by your PATH (on Windows) or SOs pointed to by your LD_LIBRARY_PATH (on UNIX).
   
    
5. Properties
   • Properties available through the Administration Tool
     1. Start both the new and old Java Web Server. Make sure they are using different port numbers.
         
     2. Login to both JavaWebServer Admin Tools.
        

        If you performed the steps in the Security section of this document, the file containing your old administration password was copied over to the new installation. That means your password on the new installation is the same as on the old.

        If you did not perform the steps in the Security section of this document, you can change the default password to one of your choosing using the Administration Tool. 

     3. For each service of Java Web Server, follow the following steps:
        1. Select same service in both Admin GUI and click manage button.
        2. All the settings must be compare from both Admin GUI and modify new Java Web Server setting based on old Java Web Server setting. For security setting, don't forget to check all the realms. Change all the port numbers after all the upgrade steps are done.
            

     Removed in 2.0:The simple Proxy Service has been removed in Java Web Server 2.0.

   • Properties only available in the property files

     If you customized session-tracking properties in your old installation, you'll probably want to perform those same customizations in the new installation.

     To do so, copy the customizations from:
      
     JWS1.1.3/properties/server/javawebserver/server.properties
      
     to each of the following files:
      
     JWS2.0/properties/server/javawebserver/sessionservice/session.properties
     JWS2.0/properties/service_defaults/sessionservice/session.properties

     Changed in 2.0: A session service has been added in Java Web Server 2.0, allowing sessions to be tracked server-wide, across services.

6. Documents
   • If you used a custom document directory in your old installation, rather thatn the default directory (public_html), create the same custom document directory name in the new installation.
   • Copy all the document files from your old installation to the new. For example:

     # cp /opt/JavaWebServer1.1.3/public_html/myHTMLfile      /opt/JavaWebServer2.0/public_html/myHTMLfile

   Changed in 2.0: In Java Web Server 1.1.3, the same default directory was used for both the webpage and secure services (although you could choose to use different ones). In Java Web Server 2.0, the default directory for the webpage service remains the same (public_html), but the default directory for the secure service is now secure_html.

   Changed in 2.0: In Java Web Server 1.1.3, document files needed for the samples, such as sample.jhtml, were kept in the default document directory (public_html). In Java Web Server 2.0, document files needed for the samples are in the examples/ directory of the server installation, under the relevant sample.

Additional possibilities for migration

• Did you add a new service to your old Java Web Server?

  If so, use new-server-root/bin/addservice to add the new service to the Java Web Server 2.0. Once you have added the additional service, follow the instructions under the service/server Properties section to customize the services.

• Did you modify any of the default servlets, CGI scripts, jhtml files, or shtml files?
   
• Did you create any custom realms?

  If so, don't forget to copy all the necessary classes for your custom realm from your old installation to you new.

  An example on UNIX might be:

  % cp /opt/JavaWebServer1.1.3/classes/myCustomRealm.class /opt/JavaWebServer2.0/classes/myCustomRealm.class

  An example on Windows might be:

  D:\> copy C:\JavaWebServer1.1.3\classes\myCustomRealm.class C:\JavaWebServer2.0\classes\myCustomRealm.class

• Were you using any additional native code?
   
• Are there any other files in old-server-root hierarchy that do not appear in the new-server-root hierarchy?

Top java-server-feedback@java.sun.com

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.