Chapter 4 Migrating The Rewriter

Chapter 4
Migrating The Rewriter



Note	All instances of the Sun™ ONE Portal Server 3.0 product refer to what were formerly known as the iPlanet™ Portal Server 3.0, Service Pack 3a, iPlanet™ Portal Server 3.0, Service Pack 4 products, and iPlanet™ Portal Server 3.0, Service Pack 5 products.

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 Rewriter

Converting Gateway Attributes to Rules

Using the Export Tool

Using the Conversion Tool

Using the Import Tool

Writing Data Migration Modules

Overview of the Rewriter

The 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

needs to be translated to

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 Rules

To 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:

and

to include:

</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 Tool

The 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.

Table 4-1 Options Available for Exporting LDAP Data
Option	Description
-a	Runs all modules without a menu. To choose to export only LDAP data from the export menu, do not use the -a option.
-p LDAP passphrase	Sets the LDAP passphrase in order to avoid the LDAP passphrase prompt. If you do not use the -p LDAP passphrase option with the -a option, the tool will prompt you for the LDAP passphrase.
ExportDir	Specifies the directory where the information is to be saved. If you do not use the ExportDir option, the tool prompts you for the export directory.

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

Change to the export directory you specified in Step 2 or Step 3. For example:

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.

Table 4-2 Directories Created by the Export Tool When Exporting LDAP Data
Directory	Description
ExportDir/config	Contains exported configuration data
ExportDir/ldif	Contains exported LDIF files
ExportDir/logs	Contains error.PID, export_metrics.PID, and report.PID files (where PID is the process ID)
ExportDir/xml	Contains exported XML data

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 Tool

The 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.

Table 4-3 Options Available for Converting LDAP Data
Option	Description
-a	Runs all modules without a menu. To choose to convert only gateway rules to Rewriter rules from the conversion menu, do not use the -a option.
-f	Converts Sun ONE Portal Server 3.0 roles to Sun ONE Identity Server roles and places users under the organization. This option retains the multiple role to user assignment similar to Sun ONE Portal Server 3.0, but does not retain the hierarchical role functionality. All roles are created under the organization and are not prioritized. The display profile documents are prioritized and merged accordingly. To see if the roles have been migrated to roles, view the roles under the organization in the admin console. If you do not use the -f option, the conversion tool converts Sun ONE Portal Server 3.0 roles to Sun ONE Identity Server suborganizations and places users under the suborganization. Without the -f option, the conversion tool retains the hierarchical functionality and customizations from Sun ONE Portal Server 3.0. The disadvantage is that it is difficult to move users from one suborganization to another. To see if the roles have been migrated to suborganizations, view the hierarchy in the admin console.
-i ExportDir	Specifies the input directory for the conversion. The input directory is the directory which contains the exported data created by the export tool. The conversion tool searches for export data in /tmp/psExport unless you specify a different input directory using the -i ExportDir option. If you specify a directory which does not contain data exported with the export tool, the conversion tool notifies you that the directory does not have export data and prompts you to enter a valid export directory.
-o ImportDir	Specifies the output directory for the conversion tool. The output directory is the directory used by the import tool. If you choose an import directory which already contains converted data, the conversion tool notifies you that modifying an existing migration may render import data unusable and prompts you to delete the import directory.

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.

Table 4-4 Directories Created by the Conversion Tool When Converting Gateway Rules to Rewriter Rules
Directory	Description
ImportDir/rewriter/ rules	Contains the rules.xml file which is the new ruleset definition.
ImportDir/logs	Contains error.PID, convert_metrics.PID, and report.PID files (where PID is the process ID).

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 Tool

The 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.

Table 4-5 Options Available for Importing Rewriter Rules
Option	Description
-a	Runs all modules without a menu. To choose to import only Rewriter rules from the import menu, do not use the -a option.
-k	Specifies that the tool does not overwrite existing users. When you run importps without the -k option, if it encounters a conflict with an existing user, it will delete the existing user and import the new user entry defined in ImportDir/ldap/user.ldif. If you run importps -k, if it encounters a conflict with an existing user, it leaves the existing user and places the rejected user entry in ImportDir/ldap/rejected_users.ldif. If the user has a display profile document in the ImportDir/dp/user/ directory, the display profile file may change. The -k option does not affect importing user display profile documents. The -k option only affects whether an existing LDAP user’s LDIF record is updated. The updates to the LDIF record include everything except display profile updates.
-m	Merges display profile documents. When you run importps without the -m option, it overwrites any existing display profile documents it finds. This means that the root suffix, organization, suborganization, and user level display profile documents, if they exist, are overwritten. If you run importps -m, when the tool encounters a conflict with an existing display profile document it will merge it.
ImportDir	Specifies the directory where the converted data is located. If the directory does not exist or if the directory does not contain valid converted data, the import tool prompts you to enter a directory containing the converted data to be imported. If you do not specify an import directory, the import tool will search /tmp/psImport.

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 Modules

See Appendix B, "Sun ONE Portal Server 3.0 Data Migration Module Author's Guide" for information on writing your own data migration modules.

Previous Contents Index Next

Previous Contents Index Next
Sun Java System Portal Server 6 2004Q2 Migration Guide