Migrate an existing Access Manager software environment to the appliance

We can migrate an existing Access Manager software environment to the appliance with the provided mechanism. To achieve the migration, ensure that Perl is installed and available on the policy server to be migrated. To migrate from an environment that is using Active Directory as the user registry, ensure that:

The appliance provides a Perl script to help with the collection of files that are necessary for the migration. These files include the IBM Security Verify Access configuration files, key files, and the authorization database. Such migration is supported for the following versions:

Steps

  1. In the appliance top menu, go to...

      System > File Downloads > common > migrate isam_migrate.pl file

    This file is a Perl utility to help facilitate the collection of files required by the migration.

  2. Copy the isam_migrate.pl file to the existing Access Manager software environment.

  3. Run the isam_migrate.pl script, specifying the location of the runtime environment and policy server configuration path.

      perl isam_migrate.pl [-c <config-path>] [-d <working-dir>] [-o <zip-file>] {-v}

      -c <config-path>
      The path of the IBM Security Access Manager configuration files.

      -d <working-dir>
      The name of the working directory. This directory must not exist on the file system.

      -o <zip-file>
      The name of the configuration bundle .zip file to produce. This file must not exist on the file system.

      -v
      Display more status messages during the execution of the script.

    The following script is an example:

      perl isam_migrate.pl -c /opt/PolicyDirector/etc/ -d /tmp/isam -o /tmp/isam.zip -v

    In most situations, the existing user registry is used by the migrated policy server. An exception to this situation is the environment where Active Directory is used as the user registry. In this situation, the ISAM metadata must be migrated from the existing user registry to a new user registry. The isam_migrate.pl utility also provides this capability.

    To migrate from a Windows computer that runs the Security Access Manager policy server, that uses Active Directory as the user registry, we can use the following commands:

      -U
      Unconfigure the old Active Directory policy server. This parameter is used to clean up the ISAM user data from the Active Directory server after the data is migrated.

      -i
      The user registry that is embedded in the appliance is used by the policy server. If this parameter is not present, then the LDAP server is external to the destination appliance.

      -h <ldap-host>
      The host name of the user registry against which the policy server is configured. This option is not required if the -i option is used.

      -p <ldap-port>
      The port of the user registry against which the policy server is configured. This option is not required if the -i option is used.

      -s
      If this parameter is present, then SSL is used by the policy server when it is communicating with the external user registry. This option is not required if the -i option is used.

      -D <ldap-admin-dn>
      The distinguished name of the administrator of the external user registry used. This option is not required if the -i option is used.

      -a <authority-suffix>
      The LDAP suffix used to hold the ISAM secAuthority data. This option is not required if the -i option is used.

      -w <ldap-pwd>
      The password for the administrator of the external or internal user registry.

      -b
      Migrate the users as Security Verify Access basic users.

      -k <keyfile>
      A GSKit CMS keyfile containing the Active Directory CA certificate. If the option -i was not supplied and -s was supplied, then it must also contain the external LDAP server SSL CA certificate.

      -W <keyfile-pwd>
      The password for the specified keyfile.

      -f <usergroup-ldif-file>
      The file that stores all non-system user and group metadata in LDIF format. This file must be added after the policy server is migrated. This file is not used for the migration on the appliance. Do not include this file in the <zip-file>.

    • Generate a migration .zip file that can be used to configure a policy server on the appliance with the embedded LDAP server.

        perl isam_migrate.pl -i -c <config-path> [-v] -d <working-dir> -o <zip-file> -w <ldap-pwd> [-b ] -f <usergroup-ldif-file> -k <keyfile> -W <keyfile-pwd>

      As an example, use the following set of assumptions:

      • The user is logged in to the Active Directory machine running the policy server and has administrative access to Active Directory.
      • Perl is installed into the directory C:\perl.
      • The isam_migrate.pl file is in C:\.
      • The current working directory is C:\.
      • A temporary directory is created: C:\tmp.
      • The appliance has the default LDAP administrator password of passw0rd.
      • The Active Directory signer certificate is placed in the GSKit CMS file C:\adkeyfile.kdb with the password passw0rd.
      • The destination uses full Security Verify Access users, not basic users. The -b option is not provided.

      The following command is based on the list of assumptions:

        C:\perl\bin\perl.exe isam_migrate.pl -i -c "C:\Program Files\Tivoli \Policy Director\etc" -d "C:\tmp\mig" -o "C:\tmp\migrate.zip" -w passw0rd -k "C:\adkeyfile.kdb" -W passw0rd -f "C:\tmp\usergroup.ldif"
    • Generate a migration .zip file that can be used to configure a policy server on the appliance with an external LDAP server.

        perl isam_migrate.pl -c <config-path> [-v] -d <working-dir> -o <zip-file> -w <ldap-pwd> [-b ] -f <usergroup-ldif-file> -k <keyfile> -W <keyfile-pwd> -h <ldap-host> -p <ldap-port> [-s] -D <ldap-admin-dn> [-a <authority-suffix>]

      As an example, use the following set of assumptions:

      • The user is logged in to the Active Directory machine running the policy server and has administrative access to Active Directory.
      • Perl is installed into the directory C:\perl.
      • The isam_migrate.pl file is in C:\.
      • The current working directory is C:\.
      • A temporary directory is created: C:\tmp.
      • The external LDAP server administrator is cn=root with password of passw0rd.
      • The Active Directory signer certificate is placed in the GSKit CMS file C:\adextkeyfile.kdb with the password passw0rd.
      • The external LDAP server, host name of extldap.ibm.com, requires SSL access on port 636 and its signer certificate is placed in C:\adextkeyfile.kdb.
      • The external LDAP server has a suffix secAuthority=Default at which the ISAM metadata is placed.
      • The destination uses full Security Verify Access users, not basic users. The -b option is not provided.

      The following command is based on the list of assumptions:

        C:\perl\bin\perl.exe isam_migrate.pl -c "C:\Program Files\Tivoli \Policy Director\etc" -d "C:\tmp\mig" -o "C:\tmp\migrate.zip" -D "cn=root" -w passw0rd -h extldap.ibm.com -p 636 -s -k "C:\adextkeyfile.kdb" -W passw0rd -f "C:\tmp\usergroup.ldif"
    • Unconfigure the Active Directory server. This command is used to clean up the ISAM user data from the Active Directory server after the data is migrated.

        perl isam_migrate.pl -U -c <config-path> [-v]
      Use this unconfigure command only after you finish generating the migration .zip file.

      As an example, use the following set of assumptions:

      • The user is logged in to the Active Directory machine running the policy server and has administrative access to Active Directory and the local machine.
      • Perl is installed into the directory C:\perl.
      • The isam_migrate.pl file is in C:\.
      • The current working directory is C:\.

      The following command is based on the list of assumptions:

        C:\perl\bin\perl.exe isam_migrate.pl -U -c "C:\Program Files\Tivoli\Policy Director\etc"

  4. If a compressed file is not automatically created on your platform, create a compressed file where the contents are relative to the location containing the copied files. For example, on a UNIX system, if the directory structure was created in /tmp/isam, the command would be:

      cd /tmp/isam; zip -r /tmp/isam.zip *

  5. In the destination appliance's local management console, import the compressed file created in the previous step.

    1. Go to...

    2. Compressed file containing the necessary migration files.

    3. Click Import.

    4. Deploy the changes.

      • If we are migrating from an environment that uses a local LDAP server, we might need to manually change the host values (localhost) in the pd.conf and ldap.conf files to IP addresses that suit your new environment.

      • The behavior of "[ssl] ssl-v3-enable" in pd.conf changed after version 6.1.1. It now provides the default for all other ISAM servers on the same machine, unless their .conf file explicitly sets its value. Previously this option only affected the pdadmin command. So if "[ssl] ssl-v3-enable = yes" is set in the migrated pd.conf, and is not explicitly set in the migrated ivmgrd.conf file, then the policy server starts with SSLv3 enabled. To obtain the behavior before migration, add "[ssl] ssl-v3-enable = no" into the ivmgrd.conf file. It would be better to not use SSLv3 at all and set "[ssl] ssl-v3-enable = no" in the migrated pd.conf file.


What to do next

To add the <usergroup-ldif-file> after migration, we must apply this file to the LDAP server used by the new policy server using an LDIF tool.

For example, use the following ldapadd command:

Parent topic: Migration