Migrate an existing WebSEAL instance to the appliance

Migrate an existing WebSEAL instance to the appliance

We can migrate an existing WebSEAL instance to the appliance.

Custom CDAS or EAS libraries are not supported. Make sure there is no dependency on custom CDAS or EAS libraries before you start to migrate the system. For example, any custom CDAS processing must be converted to an EAI.
Local junctions are supported, but a fixed location is used as the document root. A local junction is also not permitted to run any CGI scripts. It can serve only static page content. Any CGI scripts must be migrated to a remote server. The appliance supports only a single local junction. The content for all other local junctions (if any) must also be migrated to a remote server.
As part of the migration process, we must collect the files that are necessary for the migration. We can use either of the following methods to collect the necessary files:

Run the provided Perl script (wga_migrate.pl) to automatically collect the necessary files.
A Perl utility is provided to help facilitate the collection of files required by the WebSEAL instance. This utility can process the configuration for the specified WebSEAL instance. It can also copy the necessary files into the directory structure required by the import facility of the appliance.
To set up and run this utility, follow these steps:

In the appliance top menu, go to System > File Downloads.
Under common > migrate, select the wga_migrate.pl file to download it.
Copy the script to the WebSEAL server.
Ensure that Perl is installed and available on the WebSEAL server.
Locate the name of the configuration file for the WebSEAL instance that is to be migrated.
Run the wga_migrate.pl script, specifying the name of the WebSEAL configuration file and the destination directory. Use the following format for the script:
perl wga_migrate.pl [-c config-file] [-d dst-dir] {-v}

-c config-file

The name of the WebSEAL configuration file.

d dst-dir

The name of the destination directory. This directory must not exist on the file system.

-v

Display more status messages during the execution of the script.

For example, use the following script:
perl wga_migrate.pl -c /var/pdweb/etc/webseald-default.conf -d /tmp/migrate_out

Review the files contained within the destination directory to ensure that all of the necessary files are located.

Manually create the directory structure and copy the files to those directories.On the source WebSEAL server, create the directory structure of configuration files, as defined in the following table. Only those directories for which files are to be migrated must be created. Create these directories as subdirectories under a single source directory.

Directory Description

dynurl Dynamic URL configuration files.

fsso Forms-Based Single Sign-on configuration files.

jmt Junction Mapping Table configuration files.

keytab The key database (kdb/sth) files used by the WebSEAL instance. The files do not include the keyfile used to communicate with the policy server.

ltpa-keys LTPA key files.

tam-keys Key files generated with the cdsso-key-gen utility. They are used for things such as encrypting the failover cookie.

xslt/user-map-cdas XSLT configuration file used by the client certificate user mapping CDAS.

xslt/http-transformation XSLT configuration file used by the HTTP transformation rules function.

doc-root/docs The files served by the WebSEAL local junction. These files are typically located under the /opt/pdweb/www-<instance>/lib/docs directory.

doc-root/errors The error pages served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/errors directory.

doc-root/html The management HTML pages (for example, login.html) which are served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/html directory.

doc-root/oauth The OAuth response files, as defined within the [oauth-eas] stanza of the WebSEAL configuration file.

junctions The XML files that contain the junction definitions for the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/jct directory.

etc Configuration files used by the WebSEAL instance. In particular, the routing file, the webseald-<instance>.conf, and the webseald-<instance>.conf.obf files.

When we create the directory structure, additional subdirectories are not supported for any directory other than the doc-root ones (doc-root/docs, doc-root/errors, doc-root/html, doc-root/oauth). For example, we can create a directory structure such as /doc-root/error/<folder>/<file>, but a structure such as xslt/http-transformation/<folder>/<file> is not valid. For directories other than the doc-root ones, files can be placed only in the default root directories that are listed in Table 1. For example, xslt/http-transformation/<file>.
All files to be copied must have unique file names. If two files have the same name, the migration tool copies only the first file matching the name. For example, we might have the following structure:
[http-transformation]
request_pop1 = <path1>/pop1.xsl
response_pop1 = <path2>/pop1.xsl

Only <path1>/pop1.xsl are created in the directory structure. All references to <path1>/pop1.xsl and <path2>/pop1.xsl in the configuration file are reduced to pop1.xsl, which now points to the same file.

The WebSEAL configuration file must be included in the set of configuration files to be migrated. The obfuscated configuration file, as defined by the [configuration-database] stanza and file configuration entry, must also be included.
Modify the copied WebSEAL configuration file so that any configuration entries that are not applicable to the new WebSEAL instance are removed. Examples of entries that we might potentially not want to migrate would include network settings. The following configuration entries are ignored when the configuration file is imported into the appliance:

token-card configuration entry from the [authentication-levels] stanza
server-name configuration entry from the [server] stanza
network-interface configuration entry from the [server] stanza
[interfaces] configuration stanza

Create a compressed file, with the contents relative to the location containing the copied files. For example, on a UNIX system, if the directory structure was created in /tmp/migrate, the command would be:
cd /tmp/migrate; zip -r /tmp/migrate.zip *

Migration is supported for the following versions:

IBM Tivoli Access Manager Version 6.1 and later
IBM Security Access Manager Version 7.0 and later

Steps

Create a WebSEAL instance on the appliance with the local management interface.
Import the migration compressed file.

If we are warned that files might be overwritten as a part of the import operation, we must validate the overwrite operation before we can continue. Ensure the overwrite operation does not affect any other WebSEAL instances that might be running on the appliance. For detailed steps when you import with the local management interface, see Import the contents of a compressed file into the administration pages root.
If the appliance is a non-primary node in a clustered environment, and we enabled replication of SSL certificates in the cluster, first manually import the required SSL key files into the primary node and wait for these certificates to be replicated to the non-primary node. After the replication is complete, we can then import the WebSEAL configuration bundle into the non-primary node. If we do not follow this procedure in this type of environment and instead import the WebSEAL configuration directly on the non-primary node, the certificates from the WebSEAL configuration compressed file might be replaced during the next replication event by the certificates from the primary master and this will cause deployment issues.
The import function audits the configuration file changes and logs the auditing details in the file migrate_YYYYMMDDHHMM.log. To access this file, go to Monitor > Manage > Reverse Proxy Log Files, select the instance from Reverse Proxy Instances, this log file is accessible under Log Files for Selected Instance.

Deploy the changes.
Restart the WebSEAL instance.
Examine the WebSEAL log file for any potential migration issues.

Parent topic: Migration

Directory	Description
dynurl	Dynamic URL configuration files.
fsso	Forms-Based Single Sign-on configuration files.
jmt	Junction Mapping Table configuration files.
keytab	The key database (kdb/sth) files used by the WebSEAL instance. The files do not include the keyfile used to communicate with the policy server.
ltpa-keys	LTPA key files.
tam-keys	Key files generated with the cdsso-key-gen utility. They are used for things such as encrypting the failover cookie.
xslt/user-map-cdas	XSLT configuration file used by the client certificate user mapping CDAS.
xslt/http-transformation	XSLT configuration file used by the HTTP transformation rules function.
doc-root/docs	The files served by the WebSEAL local junction. These files are typically located under the /opt/pdweb/www-<instance>/lib/docs directory.
doc-root/errors	The error pages served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/errors directory.
doc-root/html	The management HTML pages (for example, login.html) which are served by the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/lib/html directory.
doc-root/oauth	The OAuth response files, as defined within the [oauth-eas] stanza of the WebSEAL configuration file.
junctions	The XML files that contain the junction definitions for the WebSEAL instance. These files are typically located under the /opt/pdweb/www-<instance>/jct directory.
etc	Configuration files used by the WebSEAL instance. In particular, the routing file, the webseald-<instance>.conf, and the webseald-<instance>.conf.obf files.