Sun Java System Portal Server 6 2004Q2 Migration Guide |
Chapter 2
Migrating LDAP Data
This chapter provides procedures to migrate LDAP data from Sun ONE Portal Server 3.0 to the Sun ONE Identity Server 6.2. In particular, migration of LDAP data includes the migration of Sun ONE Portal Server 3.0 domains, roles, and users to Sun ONE Identity Server organizations, suborganizations, and users respectively. This chapter contains the following sections:
Before beginning the migration process, ensure that you have installed the Sun ONE Portal Server 6.2 migration tools on your Sun ONE Portal Server 3.0 system and on your Sun ONE Portal Server 6.2 system. See the Sun ONE Portal Server 6.2 Installation Guide for instructions on installing both Sun ONE Portal Server 6.2 and the Sun ONE Portal Server 3.0 Data Migration Tool Suite.
As described in Chapter 1, "Planning the Migration," there are three steps to the migration process. You will need to run the export tool, the conversion tool, and the import tool to migrate the LDAP data.
Using the Export ToolThe export tool, exportps, stores data from the Sun ONE Portal Server 3.0 system in an export directory. To migrate LDAP data, 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 2-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 type 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 can 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.0sp3a
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 2-2 shows the 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.
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 directory above the export directory containing the data output by the export tool.
For example, if you used the default directory (/tmp/psExport) for exporting the Desktop, 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.
- On 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 2-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 type 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. If you have already converted LDAP data, you should delete the directory to avoid conflicts.
- 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 Wed Jul 10 13:23:14 PDT 2003
Error file: /tmp/psImport/logs/error.16125
Report file: /tmp/psImport/logs/report.16125
Metric file: /tmp/psImport/logs/convert_metrics.16125
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 1 and press Enter to convert only the LDAP database.
The system displays messages similar to the following:
Warning - Template data not found in /tmp/psExport
*****
Begin LDAP conversion process at Wed Jul 10 13:27:51 PDT 2003
*** Creating display profile ***
Warning - No templates tar found, some locale information will not be included in the display profile
Converting provider and channel display profile.
Warning: Cannot open locale directory, skipping locale printing for iwtAppProvider
Warning: Cannot open locale directory, skipping locale printing for iwtBookmarkProvider
Warning: Cannot open locale directory, skipping locale printing for iwtIPInfoProvider
Warning: Cannot open locale directory, skipping locale printing for iwtLoginProvider
Warning: Cannot open locale directory, skipping locale printing for iwtMailCheckProvider
Warning: Cannot open locale directory, skipping locale printing for iwtNetletProvider
Warning: Cannot open locale directory, skipping locale printing for iwtPostitProvider
Warning: Cannot open locale directory, skipping locale printing for iwtSampleJSP
Warning: Cannot open locale directory, skipping locale printing for iwtSampleRss
Warning: Cannot open locale directory, skipping locale printing for iwtTabProvider
Warning: Cannot open locale directory, skipping locale printing for iwtUserInfoProvider
Converting domain desktop preferences.
Converting role desktop preferences.
Converting user desktop preferences.
*** Converting LDAP data ***
Converting domain xml data
siroe.com
Converting role xml data
siroe.com/defaultRole
siroe.com/AdminRole
Converting domain/role level attributes
Converting user ldif data
processed 5 entries
Converting ldap user ldif data
Converting component xml data
iwtGateway
Converting Auth Component xml data
End LDAP conversion process at Wed Jul 10 13:28:11 PDT 2003
Successful completion of conversion process at Wed Jul 10 13:28:11 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.
If the locale data is unavailable, locale customizations to channel title and descriptions will not be migrated. If you have installed language packs it is highly recommended that you use a full export to ensure your locale information will not be lost in the migration.
- 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 when converting LDAP data.
Table 2-4 shows the directories created by the conversion tool when converting LDAP data. 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 LDAP data, the tool will prompt you to delete the import directory. Type no if you wish to keep the LDAP data 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 an 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 2-5 describes the options available for importing 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:
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 Fri Jul 12 10:04:43 PDT 2003
Error file: /tmp/psImport/logs/importerror.17206
Report file: /tmp/psImport/logs/importreport.17206
Metric file: /tmp/psImport/logs/import_metrics.17206
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 1 and press Enter to import only the LDAP database.
The system displays messages similar to the following:
Importing Organization xml
siroe.com
Success 0: Successfully completed.
Importing Organization Updates xml
Success 0: Successfully completed.
Success 0: Successfully completed.
Success 0: Successfully completed.
Importing Role xml
siroe.com/defaultRole
Success 0: Successfully completed.
siroe.com/AdminRole
Success 0: Successfully completed.
Importing Component xml
iwtGateway
Success 0: Successfully completed.
Importing user ldif into ldap database
adding new entry uid=root,ou=People,o=AdminRole,o=siroe.com,o=isp
adding new entry uid=authentication,ou=People,o=AdminRole,o=siroe.com,o=isp
adding new entry uid=anonymous,ou=People,o=defaultRole,o=siroe.com,o=isp
adding new entry uid=user1,ou=People,o=defaultRole,o=siroe.com,o=isp
adding new entry uid=gateway-default,ou=People,o=defaultRole,o=siroe.com,o=isp
Any existing users will not be added. /tmp/psImport/ldif/rejected_users.ldif
has all of the existing users. Please manually use
/usr/ldap/shared/bin/ldapmodify to modify the existing users attributes
You see this information about existing users not being added only if you use the -k option.
Importing user ldif modifications into ldap database
Moving PS 6.2 defaultOrg anonymous user to installAnonymous
adding new entry uid=installAnonymous,ou=People,o=siroe.com,o=isp
deleting entry uid=anonymous,ou=People,o=siroe.com,o=isp
Importing dp xml
SUCCESS!
Redeploying portal web application
Deploying to instance host1.siroe.com...
Successful completion of import process at Fri Jul 12 10:20:04 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.
If the role migration type is role to suborganization:
If the role migration type is role to role:
The Sun ONE Portal Server 6.2 installation creates an anonymous user at the default organization level, where the default organization is the Sun ONE Portal Server 6.2 installation organization. The Sun ONE Portal Server 6.2 anonymous user has its own customizations, including a display profile document.
For role to suborganization migrations, the migration tools migrate and place the Sun ONE Portal Server 3.0 anonymous users under a suborganization. This means that the Sun ONE Portal Server 6.2 anonymous user will always be used before the Sun ONE Portal Server 3.0 anonymous user. Therefore, during migration the migration tools rename the Sun ONE Portal Server 6.2 anonymous user to installAnonymous. This solves the conflict problem and uses the migrated anonymous user for the anonymous Desktop.
For role to role migrations, the migration tools migrate and place the Sun ONE Portal Server 3.0 anonymous user under the organization. The migration tools, therefore, rename the Sun ONE Portal Server 6.2 anonymous user before importing the Sun ONE Portal Server 3.0 anonymous user.
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.
Setting the Sun ONE Portal Server 6.2 Organization to the Sun ONE Portal Server 3.0 DomainIf you want to change the Sun ONE Portal Server 6.2 default organization to the domain used in your Sun ONE Portal Server 3.0, you follow these four steps:
- Identify the 3.0 default Domain value.
If you are unsure of the Sun ONE Portal Server 3.0 default domain, open the ExportDir/ldif/application.ldif file and search for the attribute iwtPlatform-defaultDomain-at.
- Using the Sun ONE Identity Server admin console, create an administrative user under the organization you want to have as the default organization. For information on creating users, see the Sun ONE Portal Server 6.2 Administrator’s Guide.
- Edit the BaseDir/SUNWam/lib/AMConfig.properties file and replace the com.iplanet.am.defaultOrg value with the new default organization name.
- Restart the server using /etc/init.d/amserver start.
Post-Migration Issues and TasksAfter migrating LDAP data from Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2, you may find that you receive an Authentication Failed error message and are unable to log in to the admin console. This section describes two possible causes for the problem, the pre-migration and post-migration conditions for each cause, and the solutions to the problem.
Cause 1
The Sun ONE Portal Server 3.0 default domain that corresponds to the Sun ONE Portal Server 6.2 default organization has LDAP authentication customized to authenticate against an external LDAP server. The Sun ONE Portal Server 6.2 amAdmin user will be unable to authenticate to the admin console after migration.
Pre-Migration Conditions
- The Sun ONE Portal Server 3.0 default domain name matches the Sun ONE Portal Server 6.2 default organization name. For example, you installed Sun ONE Portal Server 3.0 with the domain name of siroe.com and you installed Sun ONE Portal Server 6.2 with the organization name of siroe.com.
- The Sun ONE Portal Server 6.2 admin super user, amAdmin, is a user in the default organization. By default, the Sun ONE Portal Server 6.2 amAdmin user uses internal LDAP authentication.
- Sun ONE Portal Server 3.0 has been configured at the default domain level to have LDAP Authentication use an External LDAP server for user authentication.
Post-Migration Condition
Solution
The amAdmin user cannot authenticate because it is trying to authenticate against an External LDAP server and the amAdmin UID does not exist in the External LDAP server. To resolve the problem, follow these steps:
- Authenticate with the amAdmin user's full dn. For example:
login: uid=amAdmin,ou=People,o=defaultorg,o=rootsuffix|dc=defaultorg, dc=rootsuffix passwd: passwd
where
- default organization = response to the Sun ONE Portal Server 6.2 installation question:
What is the organization name? [host1.siroe.com] siroe.com
- root suffix = response to the Sun ONE Portal Server 6.2 installation question:
What is the root suffix of the directory tree? [o=isp]
- passwd = response to the Sun ONE Portal Server 6.2 installation question:
What is the passphrase for this server? Again?
With the answers to the installation questions, the login might look like:
login: uid=amAdmin,ou=People,o=siroe.com,o=isp passwd: adminpassword
or if the domain container naming attributes were used
login: uid=amAdmin,ou=People,dc=siroe,dc=com passwd: adminpassword
- Configure the admin super user. Note that this step is customer dependent.
The easiest approach would be to add the amAdmin user userid to the external LDAP server.
Another approach would be to create an admin user under a suborganization of the default organization. For example, you could create a suborganization under the default organization for the super admin user:
- Select the organization.
- Select New to create a new suborganization.
- Enter a name. For example, enter admin.
- Select Create.
- Select the suborganization. For example, select admin.
- Select Services from the choice menu.
- Select Register.
- Select Core, LDAP, and Register in same view.
- Select Core properties and then select Create.
- Select LDAP properties and then select Create.
- Select Users from the choice menu.
- Select New.
- Enter the following information, as you prefer. For example:
- Select Create.
- Select root suffix from Location in top frame, for example ‘isp’.
- Select Roles from the choice menu.
- Select Top-level Admin Role.
- Select Add.
- Enter sadmin in User Id field.
- Select Search.
- Select sadmin checkbox.
- Select Submit.
- Select Logout.
- Access the admin console with http://host:port/amconsole/login?org=admin
The admin user will only authenticate with this URL.
- Enter sadmin/sadmin.
Cause 2
The Sun ONE Portal Server 3.0 default domain that corresponds to the Sun ONE Portal Server 6.2 default organization has the authentication admin authenticator customized. The Sun ONE Portal Server 6.2 amAdmin user may be unable to authenticate to the admin console after migration.
Pre-Migration Conditions
- The Sun ONE Portal Server 3.0 default domain name matches the Sun ONE Portal Server 6.2 default organization name. For example, Sun ONE Portal Server 3.0 is installed with siroe.com as the default domain name and Sun ONE Portal Server 6.2 is installed with siroe.com as the default organization name.
- The Sun ONE Portal Server 6.2 admin super user (amAdmin) is a user in the default organization and uses internal LDAP authentication.
Post-Migration Condition
The Sun ONE Portal Server 6.2 admin console authentication type is not LDAP.
Solution
When trying to authenticate to the admin console, if the authenticator type is not LDAP, then you can set it to LDAP by using the amadmin utility:
BaseDir/SUNWam/bin/amadmin -u "uid=amAdmin,ou=People,o=defaultorg,o=rootsuffix|dc=defaultorg, dc=rootsuffix" -w "adminpassphrase" -t changeAdminAuth.xml
For example, if the base directory is /opt, the domain is siroe.com, the organization naming attribute is o=, and the admin passphrase is passphrase, the command would be:
/opt/SUNWam/bin/amadmin -u "uid=amAdmin,ou=People,o=siroe.com,o=isp" -w "passphrase" -t changeAdminAuth.xml
where changeAdminAuth.xml is:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Requests PUBLIC "-//Sun ONE//iDSAME 5.0 Admin CLI DTD//EN " "file:/opt/SUNWam/dtd/amAdmin.dtd">
<Requests>
<OrganizationRequests DN="o=siroe.com,o=isp">
<ModifyServiceTemplate serviceName="iPlanetAMAuthService" schemaType="Organization">
<AttributeValuePair>
<Attribute name="iplanet-am-auth-admin-auth-module"/>
<Value>LDAP</Value>
</AttributeValuePair>
</ModifyServiceTemplate>
</OrganizationRequests>
</Requests>
In this example, replace siroe.com with your organization and isp with your root suffix.
This will set amAdmin's admin authentication module to LDAP. You will need to restart the server by issuing the following command for the change to take effect:
/etc/init.d/amserver start
Please refer to Cause 1 if you still have problems authenticating.