Sun Java System Portal Server 6 2004Q2 Migration Guide |
Chapter 6
Migrating Certificates
This chapter provides procedures to migrate Sun ONE Portal Server 3.0 certificates to the Sun ONE Portal Server 6.2 system. If the name of the Sun ONE Portal Server 6.2 system is different from the Sun ONE Portal Server 3.0 system, you will need new certificates. Migrating certificates involves using the export, conversion, and import tools. The migration tools do not migrate gateway certificates. This chapter contains the following sections:
Using the Export ToolThe export tool, exportps, stores data from the Sun ONE Portal Server 3.0 system to an export directory. To migrate Sun ONE Portal Server 3.0 certificates, you need to begin by running the export tool to store certificate data 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 6-1 describes the options available for exporting Sun ONE Portal Server 3.0 certificate databases. 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:
Export directory /tmp/psExport already exists.
If you do not wish to overwrite data within this directory, please exit this migration process and rename the directory.
Delete the directory /tmp/psExport?
You see this message only if there is already exported data in the export directory. If you have not already exported the certificate databases, you may keep the export directory without risking any conflicts in the data. If you have already exported the certificate databases, 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 Wed Jul 31 12:50:12 PDT 2003
Error file: /tmp/psExport/logs/error.7926
Report file: /tmp/psExport/logs/report.7926
Metrics file: /tmp/psExport/logs/export_metrics.7926
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 3 and press Enter to export the certificate databases only.
- The system displays the following message:
Copying certificates
Successful completion of export process at Wed Jul 31 12:56:27 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 and files created by the export tool.
Table 6-2 shows the directories and files 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 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 certificate databases, 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 6-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.
If you do not wish to overwrite data within this directory, please exit this migration process and rename the directory.
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 the certificate databases, you should exit this migration process by pressing Ctrl-C and rename the directory before converting the data.
- After you choose the output directory, you see output similar to the following:
Begin conversion process at Thu Aug 1 16:21:48 PDT 2003
Error file: /tmp/psImport/logs/error.12111
Report file: /tmp/psImport/logs/report.12111
Metric file: /tmp/psImport/logs/convert_metrics.12111
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 4 and press Enter to convert only certificate databases.
The system displays messages similar to the following:
*** Extracting templates ***
*****
Begin certificate conversion process at Thu Aug 1 16:25:24 PDT 2003
End certificate conversion process at Thu Aug 1 16:25:24 PDT 2003
Successful completion of conversion process at Thu Aug 1 16:25:25 PDT 2003
- 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 6-4 shows the directories created by the conversion tool when converting certificate databases. 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 certificate databases, the tool will prompt you to delete the import directory. Type no if you wish to keep the certificate databases 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 6-5 describes the options available for importing certificate databases. This two-column table lists the options in the first column and their descriptions in the second column.
- The system displays messages 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 Thu Aug 1 16:43:15 PDT 2003
Error file: /tmp/psImport/logs/importerror.12362
Report file: /tmp/psImport/logs/importreport.12362
Metric file: /tmp/psImport/logs/import_metrics.12362
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 4 and press Enter to import only the Desktop.
The system displays messages similar to the following:
Importing Certificates
Redeploying portal web application
Deploying to instance host1.siroe.com...
Successful completion of import process at Thu Aug 1 16:46:30 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.
Migrating SSL Certificates on a Multi-Instance InstallationFor details on using SSL with Sun ONE Portal Server 6.2, see the Sun ONE Portal Server 6.2 Administrator’s Guide.
To migrate SSL certificates on a multi-instance installation:
- Create the instance.
- Create the certificate database for the instance.
- Change to the BaseDir/SUNWam/servers/alias directory and copy the cert7.db and key3.db over the newly created db files. For example:
cp https-host1.siroe.com@8443-host1-cert7.db https-instance2-host1-cert7.db
cp https-host1.siroe.com@8443-rose16-key3.db https-instance2-host1-key3.db
- Restart the server.
Migrating Open Mode SSL Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2This section contains the procedures for migrating open mode SSL from Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2. The overall process for migrating SSL includes the following procedures:
Obtaining the Certificate
If migrating to a machine with the same server name:
If migrating to a machine with a different server name:
Creating and Initializing a New Sun ONE Portal Server 6.2 Instance
As root, from the command line interface, perform the following steps on the Sun ONE Portal Server 6.2 server:
- When prompted by the mutliserverinstance script, enter the instance nickname and port number.
- Open a browser window and go to http://server:admin_port. For example, http://host1.siroe.com:8088
- When the popup window appears enter the Admin UserId and password.
- Select the new server instance name.
- Choose manage.
- If the Trust Database has not been initialized previously, enter a database password in both text boxes and click OK. If the Trust Database has been initialized previously do not perform this step.
You will receive a popup confirmation that the database has been initialized.
Requesting a Certificate
If you already have a certificate, you can skip this section and proceed with Installing the Certificate.
Installing the Certificate
- Click Install Certificate.
- Select the server on which to install the certificate.
- Leave the certificate name blank.
- If the certificate is in a file, select Message is in this file, or cut and paste the certificate into the text area.
- Choose OK.
A new screen appears with the certificate information.
- Choose Add Server Certificate.
- Select the Servers tab.
- Select the server that you want to run SSL and select Manage.
- Select the Preferences tab and select Add Listen Socket.
- Select Edit listen Sockets on the sidebar.
- Choose on from the Security drop down and Click OK.
- Restart the servers using the following command.
BaseDir/SUNWam/bin/amserver startall
- Because the Sun ONE Portal Server 3.0 iwtLoginProvider templates are not being migrated, the Sun ONE Portal Server 6.2 templates must be manually edited.