Sun Java System Portal Server 6 2004Q2 Migration Guide |
Chapter 4
Migrating The Rewriter
Migration of the Rewriter involves converting gateway attributes to rules using the export, conversion, and import tools.
This chapter contains the following sections:
Overview of the RewriterThe Rewriter serves two functions. The first function involves gateway-like components which act as a reverse proxy. In this scenario, the Rewriter prepends each URL with the gateway’s URL. For example, in a gateway scenario, an intranet page with the following hyperlink
<a href=”http://mymachine.myintranet.com/mypage.html”>
needs to be translated to
<a href=”https://gateway.siroe.com/http://mymachine.myintranet.com/mypage.html”>
so that when the user clicks a link associated with this anchor, the browser contacts the gateway which then fetches the content of mypage.html from mymachine.myintranet.com. In this way, the user can browse machines through the gateway that are not normally accessible from the intranet.
This chapter discusses the migration of this functionality of the Rewriter.
The second function of the Rewriter is to convert all relative URLs to absolute URLs. Migration of this functionality is not necessary.
Converting Gateway Attributes to RulesTo migrate iPlanet Portal Server 3.0 (Service Pack 3a, 4 or 5) gateway attributes to Sun ONE Portal Server 6.2 rules, you need to run the export, conversion, and import tools. The migration tools migrate the gateway attributes to rules in the Sun ONE Portal Server 6.2 Rewriter service ruleset called idsruleset. Importing the idsruleset does not remove the existing default_ruleset.
After the import tool has successfully imported idsruleset, the tool updates the Sun ONE Portal Server 6.2 display profiles for the URLScraper and XML providers:
<Provider name=”URLScraperProvider” class=”com.sun.portal.providers.urlscraper.URLScraperProvider”>
and
<Provider name=”XMLProvider” class=”com.sun.portal.providers.xml.XMLProvider”>
to include:
<Properties>
<String name=”urlScraperRulesetID” value=”idsruleset”/>
</Properties>
The updates to the display profile only occur for provider definitions defined at the root suffix. For example, the default installation root suffix is o=isp.
Using the Export ToolThe export tool, exportps, stores data from the Sun ONE Portal Server 3.0 system to an export directory. To migrate gateway attributes to rules, you need to begin by running the export tool to gather the LDAP data and store it to disk.
To Run the Export Tool
- On the Sun ONE Portal Server 3.0 system, change to the migration tool directory:
cd BaseDir/SUNWps/migration/bin/
- Run the exportps command:
./exportps [-a] [-p LDAP passphrase] [ExportDir]
Table 4-1 describes the options available for exporting LDAP data. This two-column table lists the options in the first column and their descriptions in the second column.
- The system displays a message similar to the following:
Which directory should be created to store the Portal Server system? [/tmp/psExport]
You see this prompt only if you do not specify the output directory on the command line. You can choose the default directory /tmp/psExport or enter the export directory.
Type the directory and press Enter.
- The system displays a message similar to the following:
Delete the directory /tmp/psExport?
You see this message only if there is already exported data in the ExportDir directory. If you have not already exported the LDAP database, you may keep the export directory without risking any conflicts in the data. If you have already exported the LDAP database, you should delete the directory to avoid conflicts.
- The system displays a message similar to the following:
Found iPS version 3.0sp5
Begin export process at Tue Jul 9 10:10:04 PDT 2003
Error file: /tmp/psExport/logs/error.7644
Report file: /tmp/psExport/logs/report.7644
Metrics file: /tmp/psExport/logs/export_metrics.7644
Export Menu:
1) LDAP Database
2) Desktop
3) Certificate Databases
4) All of the above
5) Exit
Select one of the listed options to export:
You see the export menu only if you do not specify the -a option.
- Type 1 and press Enter to export LDAP data only.
- The system displays the following message:
Enter the LDAP admin passphrase :
You see this prompt only if you select a full export using the -a option and you do not specify the -p LDAP passphrase option.
Type the LDAP admin passphrase and press Enter.
You see output similar to the following:
Dumping the ldap database
organizationalPerson
user
role
domain
application
Dumping xml
.....................
Successful completion of export process at Tue Jul 9 10:21:25 PDT 2003
cd ExportDir
Substitute the export directory for ExportDir. If you used the default export directory, for example, use /tmp/psExport.
Type ls to see the directories created by the export tool.
Table 4-2 shows the four directories created by the export tool. This two-column table lists the directories in the first column and their descriptions in the second column.
After the export has completed, or if you run into problems, check the ExportDir/logs directory for the report.PID, error.PID, and export_metrics.PID files (where PID is the process ID). The report.PID file contains actions the export tool has or has not taken. The error.PID file contains warnings or errors so that you can correct any problems. The export_metrics.PID file contains metrics detailing when various elements of the export tool started, stopped, and the total time it took to export the data. You can look at the stdout header to know which log and report files to examine for the exportps command you are running.
- Examine the exported data and manually change, before converting the data, all instances of the name of the Sun ONE Portal Server 3.0 system to the name of the Sun ONE Portal Server 6.2 system. If the port numbers on the two systems are different, you must change these manually as well.
If you are performing a single-system migration, server names will be the same, but port numbers will be different. You need to change port numbers manually before converting the data.
The migration tools do not modify server names and port numbers.
For example, in the following extract of the exported data in the ExportDir/config/platform.config file, you need to change manually all instances of host1.siroe.com, which is the name of the Sun ONE Portal Server 3.0 system, to the name of the Sun ONE Portal Server 6.2 system if the systems use different names. If the systems use different port numbers, you need to change them as well.
ips.defaultDomain=siroe.com
ips.server.protocol=http
ips.server.host=host1.siroe.com
ips.server.port=8080
ips.profile.host=host1.siroe.com
ips.profile.port=8080
ips.gateway.protocol=https
ips.gateway.host=host1.siroe.com
ips.gateway.port=443
ips.gateway.trust_all_server_certs=false
ips.virtualhost=host1.siroe.com 192.18.66.42
ips.naming.url=http://host1.siroe.com:8080/namingservice
ips.notification.url=http://host1.siroe.com:8080/
notificationservice
Using the Conversion ToolThe conversion tool, convertps, enables you to select which data to convert from the data exported from a valid installation of Sun ONE Portal Server 3.0. Because the conversion tool runs on the Sun ONE Portal Server 6.2 system, you need to move the export directory from the Sun ONE Portal Server 3.0 system to the Sun ONE Portal Server 6.2 system.
To Run the Conversion Tool
- On the Sun ONE Portal Server 3.0 system, change to the export directory containing the data output by the export tool. For example:
cd ExportDir
If you used the default directory for exporting the LDAP data, you would type:
cd /tmp
- Save the export directory using the tar command. For example:
tar cvf export.tar psExport
- Use an FTP program to transfer the export.tar file to the Sun ONE Portal Server 6.2 system.
- Extract the files from export.tar using the tar command. For example:
tar xvf export.tar
- On the Sun ONE Portal Server 6.2 system, change to the migration tool directory:
cd BaseDir/SUNWps/migration/bin/
- Run the convertps command:
./convertps [-a] [-f] [-i ExportDir] [-o ImportDir]
Table 4-3 describes the options available for the convertps command. This two-column table lists the options in the first column and their descriptions in the second column.
- The system displays the following messages:
Found Portal Server version 6.2
Enter Identity Server Internal LDAP Authentication User password:
Type in a valid password.
Which directory should be created to store the converted data? [/tmp/psImport]
You see this prompt only if you do not specify the output directory using the -o ImportDir option. You can choose the default directory or enter another import directory.
Import directory /tmp/psImport already exists.
Modifying an existing migration may render import data unusable.
Delete the directory /tmp/psImport?
You see the message about an existing import directory only if the import directory already contains converted data. In this example, option 2 is chosen to convert Gateway rules to Rewriter rules. In Chapter 2, only LDAP data was migrated. Since the migration of gateway rules to Rewriter rules has not yet been performed, the import directory need not be deleted.
- After you choose the output directory, or if you specified the output directory using the -o ImportDir option on the command line, you see output similar to the following:
Begin conversion process at Mon Jul 15 10:42:46 PDT 2003
Error file: /tmp/psImport/logs/error.18106
Report file: /tmp/psImport/logs/report.18106
Metric file: /tmp/psImport/logs/convert_metrics.18106
Conversion Menu
1) LDAP Database
2) Gateway Rules to Rewriter Rules
3) Desktop
4) Certificate Databases
5) All of the above
6) Exit
Select one of the listed options to convert:
You see the conversion menu only if you do not specify the -a option.
- Type 2 and press Enter to convert only the gateway rules to Rewriter rules.
After you select an option, you see output that includes the option you selected, the end of the Gateway Rules to Rewriter Rules migration process, and the successful completion of the conversion process similar to the following:
Warning - Template data not found in /tmp/psExport
*****
Begin gateway rule conversion process at Mon Jul 15 11:24:52 PDT 2003
Converting gateway rules data
End gateway rule conversion process at Mon Jul 15 11:24:54 PDT 2003
Successful completion of conversion process at Mon Jul 15 11:24:55 PDT 2003
You see the warnings about the templates not being found because only LDAP data was exported. If you export Desktop data in addition to LDAP data or if you choose to export all data using exportps -a, you will not see these warnings.
- Change to the import directory making sure to substitute the import directory that you selected in Step 7. For example:
cd ImportDir
Substitute the import directory for ImportDir. If you used the default import directory, for example, use /tmp/psImport.
- Type ls to see the directories created by the conversion tool.
Table 4-4 shows the two directories created by the conversion tool when converting gateway rules to Rewriter rules. This two-column table lists the directories in the first column and their descriptions in the second column.
After the conversion has completed, or if you run into problems, check the ImportDir/logs directory for the report.PID, error.PID, and convert_metrics.PID files (where PID is the process ID). The report.PID file contains actions the conversion tool has or has not taken and also alerts you to any customizations which you need to convert manually. The error.PID file contains warnings or errors so that you can correct any problems. The convert_metrics.PID file contains metrics detailing when various elements of the conversion tool started, stopped, and the total time it took to convert the data. You can look at the stdout header to know which log and report files to examine for the convertps command you are running.
- If you run the convertps tool again in order to convert data other than Gateway rules to Rewriter rules, the tool will prompt you to delete the import directory. Type no if you wish to keep the Rewriter rules you have already converted.
Using the Import ToolThe import tool, importps, enables you to import the data exported and converted using the export and conversion tools to a Sun ONE Portal Server 6.2 system. The import tool searches for a directory containing valid data created by the conversion tool.
To Run the Import Tool
- On the Sun ONE Portal Server 6.2 system, change to the import tool directory. For example:
cd BaseDir/SUNWps/migration/bin
- Run the importps command:
./importps [-a] [-k] [-m] [ImportDir]
Table 4-5 describes the options available for importing gateway rules to Rewriter rules. This two-column table lists the options in the first column and their descriptions in the second column.
- The system displays a message similar to the following:
Found Portal Server version 6.2
Enter Identity Server Internal LDAP Authentication User password:
Type in a valid password.
Enter Appserver Administrator password.
You see this prompt only if you are migrating onto a Sun ONE Application Server web container.
Begin import process at Mon Jul 15 13:42:42 PDT 2003
Error file: /tmp/psImport/logs/importerror.18302
Report file: /tmp/psImport/logs/importreport.18302
Metrics file: /tmp/psImport/logs/import_metrics.18302
Import Menu:
1) LDAP Database
2) Rewriter Rules
3) Desktop
4) Certificate Databases
5) All of the above
6) Exit
Select one of the listed options to import:
You see the import menu only if you do not specify the -a option.
- Type 2 and press Enter to import only Rewriter rules.
The system displays messages similar to the following:
Importing Rewriter Rules
SUCCESS!
Updating URLScraperProvider urlScraperRulesetID
SUCCESS!
Updating XMLProvider urlScraperRulesetID
SUCCESS!
Redeploying portal web application
Deploying to instance host1.siroe.com...
Successful completion of import process at Mon Jul 15 13:56:51 PDT 2003
After the import has completed, or if you run into problems, check the ImportDir/logs directory for the importreport.PID, importerror.PID, and import_metrics.PID files (where PID is the process ID). The importreport.PID file contains actions the import tool has or has not taken and also alerts you to any customizations which you need to import manually. The importerror.PID file contains warnings or errors so that you can correct any problems. The import_metrics.PID file contains metrics detailing when various elements of the import tool started, stopped, and the total time it took to import the data. You can look at the stdout header to know which log and report files to examine for the importps command you are running.
Writing Data Migration ModulesSee Appendix B, "Sun ONE Portal Server 3.0 Data Migration Module Author's Guide" for information on writing your own data migration modules.