Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Portal Server 6 2004Q2 Migration Guide 

Chapter 6
Migrating Certificates

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.

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 Tool

The 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

  1. On the Sun ONE Portal Server 3.0 system, change to the migration tool directory:

    2. cd BaseDir/SUNWps/migration/bin/

  2. Run the exportps command:

    3. ./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.

    Table 6-1  Options Available for Exporting Sun ONE Portal Server 3.0 certificate databases

    Option

    Description

    -a

    Runs all modules without a menu.

    To choose to export only certificate databases 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.

  3. The system displays a message similar to the following:

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

  4. The system displays a message similar to the following:

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

  5. The system displays a message similar to the following:

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

  6. Type 3 and press Enter to export the certificate databases only.
  7. The system displays the following message:

    8. Copying certificates

    Successful completion of export process at Wed Jul 31 12:56:27 PDT 2003

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

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

    Table 6-2  Directories Created by the Export Tool When Exporting Certificate Databases 

    Directory

    Description

    ExportDir/logs

    Contains error.PID, export_metrics.PID, and report.PID files (where PID is the process ID)

    ExportDir/webcert

    Contains exported web server certificates.

    ExportDir/gatecert

    Placeholder for Sun ONE Portal Server 6.2 Secure Remote Access Pack migration.

  9. 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.
  10. 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.

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

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

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

    2. For example, if you used the default directory (/tmp/psExport) for exporting the certificate databases, you would type:

    cd /tmp

  2. Save the export directory using the tar command. For example:

    3. tar cvf export.tar psExport

  3. Use an FTP program to transfer the export.tar file to the Sun ONE Portal Server 6.2 system.
  4. Extract the files from export.tar using the tar command. For example:

    5. tar xvf export.tar

  5. On the Sun ONE Portal Server 6.2 system, change to the migration tool directory:

    6. cd BaseDir/SUNWps/migration/bin

  6. Run the convertps command:

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

    Table 6-3  Options Available for Converting Certificate Databases 

    Option

    Description

    -a

    Runs all modules without a menu.

    To choose to convert only certificate databases 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.

  7. The system displays the following messages:

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

  8. After you choose the output directory, you see output similar to the following:

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

  9. Type 4 and press Enter to convert only certificate databases.

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

  10. Change to the import directory making sure to substitute the import directory that you selected in Step 7. For example:

    11. cd ImportDir

    Substitute the import directory for ImportDir. If you used the default import directory, for example, use /tmp/psImport.

  11. Type ls to see the directories created by the conversion tool.

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

    Table 6-4  Directories Created by the Conversion Tool When Converting Certificate Databases

    Directory

    Description

    ImportDir/logs

    Contains error.PID, export_metrics.PID, and report.PID files (where PID is the process ID)

    ImportDir/webcert

    Contains converted web server certificates.

    ImportDir/gatecert

    Placeholder for Sun ONE Portal Server 6.2 Secure Remote Access Pack migration.

    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.

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

  1. On the Sun ONE Portal Server 6.2 system, change to the import tool directory. For example:

    2. cd BaseDir/SUNWps/migration/bin

  2. Run the importps command:

    3. ./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.

    Table 6-5  Options Available for Importing Certificate Databases 

    Option

    Description

    -a

    Runs all modules without a menu.

    To choose to import only the certificate databases 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.

  3. The system displays messages similar to the following:

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

  4. Type 4 and press Enter to import only the Desktop.

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

  5. 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 Installation

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

  1. Create the instance.
  2. Create the certificate database for the instance.
  3. Change to the BaseDir/SUNWam/servers/alias directory and copy the cert7.db and key3.db over the newly created db files. For example:

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

  4. Restart the server.

Migrating Open Mode SSL Sun ONE Portal Server 3.0 to Sun ONE Portal Server 6.2

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

  1. Obtain a copy the backup of the certificate from the Sun ONE Portal Server 3.0 server.
  2. Copy the certificate to the Sun ONE Portal Server 6.2 server.

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:

  1. Go to the directory BaseDir/SUNWps/bin.

    2. cd BaseDir/SUNWps/bin

  2. Type the following to create a new Sun ONE Portal Server 6.2 instance.

    3. ./multiserverinstance

  1. When prompted by the mutliserverinstance script, enter the instance nickname and port number.
  2. Open a browser window and go to http://server:admin_port. For example, http://host1.siroe.com:8088
  3. When the popup window appears enter the Admin UserId and password.
    • The default value for the Admin UserId is admin.
    • The password is the passphrase entered during installation.
  4. Select the new server instance name.
  5. Choose manage.
  6. 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.

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

  1. Click on Request a certificate on the sidebar.
  2. Select New Certificate or Renew Certificate.
  3. Select a CA to send the request to.
  4. Select Internal for Cypotgraphic module.
  5. Enter the password name.
  6. Enter in the appropriate information and select OK.

Installing the Certificate

  1. Click Install Certificate.
  2. Select the server on which to install the certificate.
  3. Leave the certificate name blank.
  4. If the certificate is in a file, select Message is in this file, or cut and paste the certificate into the text area.
  5. Choose OK.

    6. A new screen appears with the certificate information.

  6. Choose Add Server Certificate.
  7. Select the Servers tab.
  8. Select the server that you want to run SSL and select Manage.
  9. Select the Preferences tab and select Add Listen Socket.
  10. Select Edit listen Sockets on the sidebar.
  11. Choose on from the Security drop down and Click OK.
  12. Restart the servers using the following command.

    13. BaseDir/SUNWam/bin/amserver startall

  13. 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.
    1. cd /etc/opt/SUNWps/desktop/default/Login
    2. In any of the display*.html files, add https://server_name:port/ to the following:

      3. <FORM ACTION=”https://server_name:port/amserver/UI/login” ...>

      <A HREF=”https://server_name:port/amserver/UI/login ...”>



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.