|Previous Contents Index DocHome Next|
|iPlanet Web Server, Enterprise Edition Installation Guide|
Chapter 4 Migrating Your Web Server
You can migrate the following iPlanet Web Server 4.x information to work with iPlanet Web Server 6.0.
All user and group information stored in a local database (if you choose to migrate it)
iPlanet Web Server 6.0 Changes
When you migrate information from iPlanet Web Server 4.x to iPlanet Web Server 6.0, the changes are made in the following areas:
Certain directives found in the iPlanet Web Server 4.x magnus.conf file are now located in the iPlanet Web Server 6.0 server.xml file. During the migration process, these directives are automatically removed from the 6.0 server's magnus.conf file and added to the server.xml file.
In addition, Init functions located in the iPlanet Web Server 4.x obj.conf file are moved to the iPlanet Web Server 6.0 magnus.conf file.
Java Configuration Files
When you install the Java subcomponent, the configuration files that are installed include a set of files that end in .default. These files are preserved only for backward compatibility and are deprecatedin iPlanet Web Sever 6.0. These files may not be supported in future versions of the product. In iPlanet Web Server 6.0, you should create servlets and JSPs in web applications and configure them using the web-apps.xml file, as described in the Programmer's Guide to Servlets in iPlanet Web Server, rather than using .default files. See the Programmer's Guide to iPlanet Web Server for mappings between old .default file properties, and the per-virtual server web-apps.xml, as well as the standard Servlet 2.2 deployment descriptor web.xml.
Java Server Pages
iPlanet Web Server 4.0 Java Server Pages (JSPs) were written in JSP 0.92. The iPlanet Web Server 4.1 and 6.0 JSPs are written in JSP 1.1. Version 0.92 is no longer supported in iPlanet Web Server 6.0. JSPs must be rewritten according to the version 1.1 standard. In addition, it is recommended that developers create JSPs as part of web applications. Style examples can be found in server_root/plugins/servlets/examples/web-apps.
Any JSPs you have written in 0.92 will still work on iPlanet Web Server 6.0 as long as they are in a designated legacy directory. To designate a directory as a legacy directory, access the Class Manager, click the Services tab, and click Legacy JSP Directory. Use this page to designate your legacy directories.
JSPs written in JSP 1.1 that are part of a web application can reside in any directory that the server can serve from.
JSP 1.1 samples are in server_root/plugins/samples/servlets/jsp.10.
iPlanet Web Server 6.0 deprecates but maintains backward compatibility for the 4.1 style of servlets configuration using servlets.properties, rules.properties and contexts.properties files. These files may not be supported in future releases of the product. For more information, see the Programmer's Guide to Servlets in iPlanet Web Server.
Simple Session Manager
Simple Session Manager and JDBC Session Manager are supported by iPlanet Web Server 6.0, but deprecated. Users are encouraged to use IWS Session Manager instead, which is described in the Programmer's Guide to Servlets in iPlanet Web Server.
If your iPlanet Web Server 4.x web applications specified SimpleSessionManager, you should change the name of the class to IWSSessionManager. You then have the option of adding persistence. Other Init attributes such as timeOut and reapInterval are unchanged.
If your iPlanet Web Server 4.x web application specified JDBCSessionManager, you should change the name of the class to IWSSessionManager and add the following attribute to the init-param element of the session manager: session-data-store='com.netscape.server.http.session.JdbcStore'
Other attributes such as provider and url remain unchanged.
If your iPlanet Web Server 4.x web application specified MMapSessionManager as the class name for the session manager, the application remains unchanged.
iPlanet Web Server 4.x you could create multiple server instances using hardware and software virtual servers, but these instances were required to share the same configuration information. With iPlanet Web Server 6.0, you can set up multiple classes of virtual servers. Each class has separate configuration information.
The settings for virtual servers are stored in the server.xml file, found in the server_root/server_ID/config directory. See the iPlanet Web Server Administration Guide for more information about virtual servers.
The following iPlanet Web Server 4.x features are not supported in iPlanet Web Server 6.0:
See the Programmer's Guide to Servlets in iPlanet Web Server for an appendix explaining how to convert SSJS applications to JSPs. In addition, find an example of a converted application in server_root/plugins/samples/servlets/jsp.10/hangman.
Obsolete obj.conf Directives
The following directives are not used with iPlanet Web Server 6.0. If the migration program finds them in your 4.x server's obj.conf file, it does not carry them forward to the 6.0 server.
Init directives: iPlanet Web Server 4.x Init directives are automatically moved from the 4.x obj.conf file to the iPlanet Web Server 6.0 magnus.conf file.
Start and Stop Scripts
If you've made modifications to your start or stop scripts in your 4.x server, those changes will not be carried forward by the migration program.
Symbolic Links in Configuration Files (Unix and Linux)
Symbolic or relative links in server configuration files may cause problems when upgrading. Make sure that server configuration files that contain absolute references to files under the server root always reference the path to the server root in the same way. Preferably, these links should not transverse any symbolic links.
Migrating Settings and Data
To migrate settings and data from a 4.x server to the 6.0 server, follow these steps:
In the Administration Server page, click the Servers tab.
Click Migrate Server.
Enter the server root of the server from which you want to migrate and click Search. For example:
Choose a server from the drop-down list and click Migrate.
- iPlanet Web Server detects whether there are server instances installed in the directory you specified and displays the servers you can migrate in a section of the page called "Installed Servers." The Administration Server cannot be migrated.
Fill in the form.
- A new window appears showing the migration parameters.
- The sections on the form that you see depend upon which features your 4.x iPlanet Web Server is using and which 6.0 components you installed. The following sections of parameters are possible:
General Migration Parameters
- For more information, see the Migration Parameters Page in the online help..
Click Configure Migrated Server to configure your migrated server instance in the Server Manger, or click Close to close the migration window.
- The Migrate Server_name page appears. It shows the results of the migration, including the parameters successfully migrated and the parameters that you need to migrate manually. It also shows any features of your 4.x server that are not supported in 6.0.
The Migrate Server Page
When you migrate, you see a page (Migrate Server_name) that logs all the migration information, including all errors encountered. You receive warnings for the features you used in iPlanet Web Server 4.x that are not supported in iPlanet Web Server 6.0. The migration program does not migrate entries in obj.conf that are for obsolete features.
If you get fatal errors while migrating, the migration continues. The results page shows what errors occurred an you can use this information to troubleshoot.
Migrating the Administration Server
You can only migrate individual server instances. You cannot migrate your administration server. After you have migrated your iPlanet Web Server instances, you need to set up features such as distributed administration and clusters again in your 6.0 Administration Server.
When you migrate an iPlanet Web Server instance, you have the option of migrating user and group information, which spans multiple server instances. Once you have migrated user and group information or set up your 6.0 environment, you do not need to migrate users and groups again. The user and group information is in the /server_root/userdb/server_name.ldif file.
You can also migrate keys and certificates.
Migrating User and Group Information
If you used the Directory Server, you do not need to do anything during the migration process to migrate users and groups. After migrating, in the Administration Server, on the Global Settings tab, use the Configure Directory Service page to point to a Directory Server. You must use a 4.x or 6.0 Directory Server.
Migrating Virtual Servers
iPlanet Web Server 4.x provided two methods for creating hardware virtual servers: the object method and the virtual method. How hardware virtual server information is migrated depends upon which method you used:
If your iPlanet Web Server 4.x hardware virtual servers were created using the object method, these hardware virtual server settings are migrated from the 4.x obj.conf file to the 6.0 server.xml file.iPlanet Web Server 4.x software virtual servers settings are migrated from the 4.x obj.conf file to the 6.0 server.xml file.
If your iPlanet Web Server 4.x hardware virtual servers were created using the virtual method, these hardware virtual server settings are migrated from the 4.x virtual.conf file to the 6.0 server.xml file.
iPlanet Web Server 6.0 has a default ACL called es-internal. It controls who can change files internal to iPlanet Web Server, for example, help files, onscreen icons, and so on. This new default ACL is added when you migrate.
If you had ACLs set up in your administration server 4.x for distributed administration, these ACLs are not migrated. You must add them manually to your new Administration Server.
The migration process copies the database files in the 4.x_server_root/https-server_id directory, such as key3.db and cert7.db, to the 6.0_server_root/https-server_id directory.
In addition, the SSL parameters located in the 4.x server's magnus.conf file are automatically added to the 6.0 server.xml configuration file.
For more information on using certificates with iPlanet Web Server, see the iPlanet Web Server Administrator's Guide.
Migrating Search Collections
You need to choose which search collections, if any, you want to migrate. The Migration Parameters page has checkboxes for you to select the collections you want to migrate. If you don't migrate a collection when you migrate the server, you cannot go back and migrate it in the future.
If you choose to use your old document root, the search collections you migrated work automatically. If you choose to use a new document root instead of your old one, you may need to recreate some of your collections before they will work.
Migrating Search Pattern Files
You have the option of migrating the search pattern files. You should only do this if you have customized the default pattern files.
After migrating your server settings and data, you may also need to make changes to your applications so that they run on iPlanet Web Server 6.0.
Migrating NSAPI Applications
Most NSAPI programs you used with iPlanet Web Server 4.x will work in iPlanet Web Server 6.0 without being recompiled. Some undocumented data structures have been moved out of nsapi.h and are no longer public. Going forward, if your plugins use any of these data structures, you should re-write them to use accessor functions. The data structures that are now private are defined in nsapi_pvt.h, which is shipped with the build for informational purposes only.
Custom NSAPI plug-ins are not automatically copied to the new server directory. If you have custom plug-ins, make sure you copy your plug-ins to the upgraded path as shown in the magnus.conf of the new server.
For more information on these data structures and the new accessor functions, see the NSAPI Programmer's Guide to iPlanet Web Server 6.0.
Migrating Java Servlets
After you've migrated your server, Java servlets that ran in iPlanet Web Server 4.x should run in 6.0 without being recompiled. The migration leaves 4.x servlets in their original directory. The migrated servlets run in compatibility mode, which may make them a little slower than other 6.0 servlets.
Also, if your 4.x servlet referenced any additional files, you need to add the path to these files to your JVM classpath. To update the classpath, use the Configure JVM Attributes page, which you can find in the Server Manager on the Servlets tab.
Although 4.x servlets and JavaServer Pages run properly without modification on iPlanet Web Server 6.0, application developers should rewrite these as web applications to take advantage of new features.
When you install the Java subcomponent, the configuration files that are installed include a set of files that end in .default (for example, rules.properties.default). These files contain the default values for the Java configuration files. During migration, the Java configuration files are not changed from the previous version. If you want to update the old files to the new settings, refer to the .default files. You can also refer to the .default files in the future if you want to revert to the iPlanet Web Server 6.0 default settings.
Server-side Java Applets (HttpApplets)
Server-side Java applets (HttpApplets) are not supported. Instead use Java servlets. You will need to rewrite your server-side Java applets as servlets and reinstall them.
Previous Contents Index DocHome Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated May 07, 2001