| Sun ONE Web Server 6.1 Installation and Migration Guide |
Chapter 6
Migrating from Version 4.1 to 6.1This chapter contains migration information to help you understand the changes that take place when you migrate your Sun ONE Web Server from version 4.1 to 6.1.
This chapter contains the following information:
Migration OverviewYou can migrate the following iPlanet Web Server 4.1 information to work with Sun ONE Web Server 6.1.
- Document roots and any other directory mappings
- Configuration styles information
- Software and hardware virtual server settings
- Access Control List (ACL) information
- Secure Socket Layer (SSL) information
- Certificates and keys
- NSAPI information
- JavaServer Pages (JSPs)
- Simple Session Manager and JDBC Session Manager (deprecated)
- Server Side HTML (SHTML)
- Simple Network Management Protocol (SNMP) settings (the snmp.conf file).
- The file cache tuning configuration settings (the nsfc.conf file).
Migrating Settings and Data
To migrate settings and data from a 4.1 server to the 6.1 server, follow these steps:
- In the Administration Server page, click the Migrate Servers tab.
- Click Migrate Server.
Migrate Server Page
- Enter the server root of the server from which you want to migrate and click Search. For example:
/usr/netscape/server4
C:\netscape\server4
Sun ONE 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.
- Choose a server from the drop-down list and click Migrate.
Select a Server to Migrate
- In the new Migration parameters window that is launched, specify the migration parameters.
Specify the Migration Parameters
The sections on the form that you see depend upon which features your 4.1 iPlanet Web Server is using and which components you installed. The following sections of parameters are possible:
- Click Migrate.
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.1 server that are not supported in 6.1.
The Migrate server-name Page
- Click Configure Migrated Server to configure your migrated server instance in the Server Manager, or click Close to close the migration window.
The Migrate server-name 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.1 that are not supported in Sun ONE Web Server 6.1. 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 and 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.1 Administration Server.
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.
Migrating Virtual Servers
iPlanet Web Server 4.1 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.1 hardware virtual servers were created using the object method, these hardware virtual server settings are migrated from the 4.1 obj.conf file to the 6.1 server.xml file.
- If your iPlanet Web Server 4.1 hardware virtual servers were created using the virtual method, these hardware virtual server settings are migrated from the 4.1 virtual.conf file to the 6.1 server.xml file.
iPlanet Web Server 4.1 software virtual servers settings are migrated from the 4.1 obj.conf file to the 6.1 server.xml file.
Migrating ACLs
If you had ACLs set up in your Administration Server 4.1 for distributed administration, these ACLs are not migrated. You must add them manually to your new Administration Server.
Migrating Certificates
The migration process copies the database files in the 4.1_server_root/alias directory, such as key3.db and cert7.db, to the 6.1_server_root/alias directory.
In addition, the SSL parameters located in the 4.1 server’s magnus.conf file are automatically added to the 6.1 server.xml configuration file.
The ACL-related files, secmod.db and dbswitch.conf files are overwritten during migration.
For more information on using certificates with Sun ONE Web Server, see the Sun ONE Web Server Administrator’s Guide.
Migrating Applications
After migrating your server settings and data, you may also need to make changes to your applications so that they run on Sun ONE Web Server 6.1.
Migrating NSAPI Applications
Most NSAPI programs you used with iPlanet Web Server 4.1 will work in Sun ONE Web Server 6.1 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 Sun ONE Web Server 6.1 NSAPI Programmer’s Guide.
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.
What Does Not Get MigratedThe migration process does not migrate the following:
See Java Servlets for more information.
See Searchfor more information.
See Start and Stop Scripts for more information.
See Cron Control for more information.
See The certmap.conf File for more information.
See Web Publishing for more information.
See Server Side JavaScript (SSJS)/LiveWire for more information.
Summary of Migration-Related ChangesWhen you migrate information from iPlanet Web Server 4.1 to Sun ONE Web Server 6.1, the changes are made in the following areas:
Access and Error Logs
The access and error server log files record your server’s activity. During migration, new access logs are created. Error logs from the 4.1server-instance/logs directory is copied to the server-instance/logs in Sun ONE Web Server 6.1.
Configuration Files
Certain directives found in the iPlanet Web Server 4.1 magnus.conf file are now located in the Sun ONE Web Server 6.1 server.xml file. During the migration process, these directives are automatically removed from the 6.1 server’s magnus.conf file and added to the server.xml file.
In addition, Init functions located in the iPlanet Web Server 4.1 obj.conf file are moved to the Sun ONE Web Server 6.1 magnus.conf file.
For a list of deprecated directives, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.
Note
During migration, multi-line Init directives are compressed to single-line directives in the Sun ONE Web Server 6.1 magnus.conf file.
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.2. Version 0.92 is no longer supported in Sun ONE Web Server 6.1. JSPs must be rewritten according to the version 1.2 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.
JSPs written in JSP 1.2 that are part of a web application can reside in any directory that the server can serve from.
JSP 1.2 samples are in server_root/plugins/samples/servlets/jsp.10.
Java Servlets
Netscape Enterprise Server / iPlanet Web Server 4.0 and 4.1 supported the Java Servlet 2.1 specification. This specification did not include web applications. A deployment scheme was developed to make servlet deployment simpler. With the advent of Java Web Applications (.war files) and their deployment descriptors, it is no longer necessary to maintain a proprietory deployment system.
iPlanet Web Server 6.0 supported both types of deployment schemes, but the 4.x implementation (referred to as legacy servlets) was marked as deprecated (See Chapter 8: “Legacy Servlet and JSP Configuration” of the iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets).
Sun ONE Web Server 6.1 no longer supports Legacy Servlets. The legacy-style properties files for the server you want to migrate - servlet.properties, context.properties, and rules.properties - are removed during migration.
Because there is no one-to-one mapping for all of the features, legacy servlets cannot be migrated automatically.
For documentation and samples to help you migrate your 4.1 legacy-style servlets to the web applications structure, see the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.
Cron Control
Cron file names have been changed in Sun ONE Web Server 6.1. The file ns-cron.conf is called schedulerd.conf in Sun ONE Web Server 6.1, and the file cron.conf is now called scheduler.conf. These are located in the https-admserv/config directory.
Cron settings from the previous version of your Web server are however not migrated to Sun ONE Web Server 6.1during migration. Please copy the cron settings for the migrated instance to the cron files.
The certmap.conf File
The certificate mapping file, certmap.conf, is not migrated during the migration process. During migration you receive a message that you need to manually migrate existing entries in the certmap.conf of the server instance you want to migrate.
Simple Session Manager
Simple Session Manager and JDBC Session Manager are not supported by Sun ONE Web Server 6.1. For more details about session managers, see the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.
If your iPlanet Web Server 4.1 web applications specified SimpleSessionManager, you should change the name of the class to IWSSessionManager. You then have the option of adding persistence. Persistence-type must be set to s1ws60. Other Init attributes such as timeOut and reapInterval are unchanged.
If your iPlanet Web Server 4.1 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'. Persistence-type must be set to s1ws60.
Other attributes such as provider and url remain unchanged.
The package name of the MMapSessionManager has been changed from com.netscape.server.http.session in the 4.1 version of the Web Server to com.iplanet.server.http.session in the 6.0 and 6.1versions.
Virtual Servers
In iPlanet Web Server 4.1, you could create multiple server instances using hardware and software virtual servers, but these instances were required to share the same configuration information. With Sun ONE Web Server 6.1, 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 Sun ONE Web Server 6.1 Administrator’s Guide for more information about virtual servers.
Web Publishing
Sun ONE Web Server 6.1 does not support the iPlanet Web Server 4.1 Web Publishing feature. It provides a new feature called WebDAV that enables collaborative file sharing and authoring on the Web. See the Sun ONE Web Server 6.1 Administrator’s Guide for more information about WebDAV.
Search
Because the search engine used in iPlanet Web Server 4.1 has been replaced by a new search engine in Sun ONE Web Server 6.1, existing search collections and indexes are not migrated during the migration process. To use the Search functionality in Sun ONE Web Server 6.1, you will have to create and configure new search collections and indexes. For more details, see the Sun ONE Web Server 6.1 Administrator’s Guide.
Start and Stop Scripts
If you’ve made modifications to your start or stop scripts in your 4.1server, those changes will not be carried forward by the migration program. This applies to the reconfig, restart and rotate scripts as well.
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.
Server Side JavaScript (SSJS)/LiveWire
Data and settings are not migrated applications that use SSJS/Livewire.
See the Sun ONE Web Server 6.1 Programmer’s Guide to WebApplications 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.
