Using the migration tool utility

This topic describes how to run the migration tool utility to migrate authentication and authorization data from the earlier versions of BMC Atrium Orchestrator Platform to 7.9.x. 

In the instructions on this page:

  • AO_Home represents the directories in which you installed your BMC Atrium Orchestrator components, such as the CDP or repository.
  • SSO refers to a BMC Single Sign-On authentication system.
  • In the migration tool file name, migration-tool-version.zip, replace version with the BMC Atrium Orchestrator version to which you are migrating data. For example, if you are migrating data to BMC Atrium Orchestrator version 7.9 the file name will be migration-tool-7.9.00.zip.

Notes

  • Definitions for users already defined in SSO or known to SSO through an external definition are not altered.  User passwords cannot be exported from Access Manager, so a generated password is used during import. The password for a user imported into SSO is set to the userid and padded with as many numbers (12345678) as needed to create a password of the required minimum length (default: 8 characters). The minimum password length is defined by SSO.
    For example, the userid "sam" will be assigned a password of "sam12345."  
  • If you choose to upgrade using embedded Remedy SSO, set up the HA failover configuration (described in Configuring a fail-safe enterprise service bus after installation), before running the the migration utility to import users and roles. This ensures that the imported data gets replicated on all of the embedded Remedy SSO nodes. If a node does not have HA failover configuration, the data has to be imported manually.

Locating the migration tool utility

You can access the migration tool using one of the following options: 

  • Download the migration-tool-version.zip file from the BMC Electronic Product Download site (Support credentials required).
    For more information about downloading the files from EPD, see Downloading the installation files. 
  • When you install the BMC Atrium Orchestrator platform, the migration-tool-version.zip file is located in the AO_Home\tools directory. 
    • (Windows) In the AO_Home\tools, use the runAuthTool.bat file to run the tool. 
    • (Linux) In the AO_Home/tools, the runAuthTool.sh file is available. 

Migrating from BMC Atrium Orchestrator Platform 7.6.03 version to 7.9.x

You can use the migration tool utility in the following scenarios:

  • When upgrading from BMC Atrium Orchestrator Platform 7.6.03 version to 7.9.x. 
  • When installing a new, parallel 7.9.x environment using an independent external repository database. 

Before you begin

Before running the migration tool, ensure that the following conditions are met:

  • You have downloaded the BMC Atrium Orchestrator Platform 7.9.x installation files. 
  • Your current environment is 7.6.03.
  • Stop all services for all Platform server components (including Access Manager) on your 7.6.03 environment.
  • Back up the existing AMREPO and CDP servers or AM, repository, and CDP servers.
  • If you are not installing the embedded Remedy Single Sign-On with the BAO Platform components upgrades, you must have already installed the external version of Remedy SSO. 

Run the migration tool utility to export users, roles, and authorization rules

Run the migration tool utility in your current 7.6.03 environment to export the users, roles, and authentication rules from the current environment. 

  1. In your current 7.6.03 environment, go to the AO_HOME\AmRepo (if you have installed only Access Manager, go to the Access Manager directory) location and paste the migration-tool-version.zip file in the directory.
  2. Extract the contents of the zipped file.
    The migration-tool-version directory is created when you unzip the migration tool. This directory is referenced later in these instructions.

  3. From the command prompt, go to the location where your Access Manager and the repository are installed and enter the following command to export the authorization data into an XML file. 

    • Windows: tools\runAuthTool.bat --export AuthorizationExport.xml

    • UNIX: ./runAuthTool.sh --export AuthorizationExport.xml

      Note

      When you run this command, the AuthorizationExport.xml export file is generated in the migration-tool-version directory.

      Ensure that you copy the AuthorizationExport.xml export file and place it in another location before you upgrade to Platform 7.9.x.

Create role mapping properties file (optional)

This properties file is required only if you want to export the default roles (GRID_ADMIN, REPOSITORY_ADMIN, DESIGNER, and USER) available in Access Manager, except ADMIN, and import them to BMC SSO as roles. 

For more information about the file, see Using a role mapping file to import default roles.

Notes

When you install the repository, an AoAdmin role is created by default in SSO, which is equivalent to the ADMIN role in Access Manager. You do not need to import the default ADMIN role from Access Manager to SSO. If you choose to import it, the ADMIN role will be assigned the same permissions as the USER role in Access Manager.

The following example shows a sample properties file.

ADMIN=adminnew
GRID_ADMIN=gridadminnew
REPOSITORY_ADMIN=repoadminnew			
DESIGNER=designernew
USER=usernew

Upgrading the BAO Platform components or performing a parallel installation of BAO Platform and importing authorization rules, users, and roles

The next steps describe upgrading or installing components. Use the instructions for the BAO setup you are performing for your environment:

  • Upgrading: If you are upgrading your existing 7.6.x environment, see Performing upgrades from 7.6.03 for details.
  • Installing a new, parallel BAO Platform environment: If you are installing a parallel environment, see Installing for installation instructions.
    You will need to use a separate repository from that used in the 7.6.x environment. If you choose to transfer content from the 7.6.03 repository to the 7.9.x repository, see Transferring content between repositories for more information.

Note

If transfer permissions are required, add only the necessary permissions as these will be replaced at a later stage.

  1. Upgrade or install the repository.

    Warning

    Do not start the repository server automatically after the upgrade or installation.

  2. In your 7.9.x environment, from the command prompt, go to the location where the repository or CDP is installed and run the following command to import the authorization data (rules) into the repository or CDP and the role mapping data into SSO. 
    In the command, the options are specified as described in the following table. 

    OptionsDescription

    tools\runAuthTool.bat

    		Specifies the path to the .bat file required to import the data.

    --roleMap RMNEW.properties

    		This is optional. Specifies the name of the role map properties file required to import the default roles. In the sample, the properties file is placed in the <AO_Home>\Repo and <AO_Home>\CDP folders. You can specify the path where your role map properties file is located.

    --import AuthorizationExport.xml

    		Specifies the export file that you want to import. In the sample, the export file is placed in the <AO_Home>\Repo and <AO_Home>\CDP folders. You can specify the path where your export file is located.

    • Windows: tools\runAuthTool.bat --roleMap RMNEW.properties --import AuthorizationExport.xml

    • UNIX: ./runAuthTool.sh --roleMap RMNEW.properties --import AuthorizationExport.xml

  3. Start the BAO-REPO service.
  4. Log into the authentication service and the repository and verify that the roles and permissions were imported successfully. 

  5. Upgrade or install the CDP.

    Warning

    Do not start the CDP server automatically after the upgrade or installation.

  6. From the command prompt, go to the location where CDP is installed and enter the following command to import the authorization data in CDP.
    tools\runAuthTool.bat --roleMap RMNEW.properties --import AuthorizationExport.xml
    Refer to the previous table for command option information. 

  7. Start the BAO-CDP service.
  8. Log into the CDP and verify that the roles and permissions were imported successfully.

  9. Import the 7.6 users and roles into SSO using the following steps:

    1. Verify that all BAO environment components are up and running (see Starting and stopping product components and services).

    2. Complete the failover changes in SSO using the instructions in Configuring a fail-safe enterprise service bus after installation.
    3. Run the appropriate command for the type of SSO instance you are using (embedded or external). You only need to run this for one of the BAO components (repository, CDP, or HA-CDP) with SSO.

      • Embedded SSO

        tools\runAuthTool.bat --roleMap RMNEW.properties -import AuthorizationExport.xml -rssoPassword pass:rssoAdminPassword -rssoUser Admin -rssoURL rssoURL -verbose

        rssoURL represents the URL for the repository or the CDP with the embedded SSO.
        For example

        C:\Program Files\BMC Software\BAO\CDP\tools\runAuthTool.bat --roleMap RMNEW.properties -import AuthorizationExport.xml -rssoPassword pass:AdminABC -rssoUser Admin -rssoURL http://machineABC-12345.bmc.com:8080 -verbose

      • External SSO

        tools\runAuthTool.bat --roleMap RMNEW.properties -import AuthorizationExport.xml -rssoPassword pass:rssoAdminPassword -rssoUser Admin - rssoURL rssoURL -verbose

        rssoURL represents the URL for the external SSO.
        For example

        C:\Program Files\BMC Software\BAO\RSSO\tools\runAuthTool.bat --roleMap RMNEW.properties -import AuthorizationExport.xml -rssoPassword pass:AdminABC -rssoUser Admin -rssoURL http://machineABC-12345.bmc.com:8080 -verbose

Synchronizing two embedded SSO instances

If you add a CDP that is configured to use an embedded SSO, you can use the migration tool to synchronize the new SSO with existing SSO data. For example,

  • If you install a primary CDP, you can use the migration tool to synchronize the repository's embedded SSO data (the source) with the new CDP's embedded SSO (the destination). 
  • If you install an HA-CDP, you can use the migration tool to synchronize the primary CDP's embedded SSO data (the source) with the new HA-CDP's embedded SSO (the destination). 

To synchronize two SSOs, run the following command:

tools\runAuthTool.bat --syncRsso --srcRssoRealm <realmName> --srcRssoUrl http(s)://<src_host>:<src_port> --srcRssoUser <src_RSSO_admin> --srcRssoPassword pass:<src_RSSO_admin_password> --dstRssoUrl http(s)://<dst_host>:<dst_port> --dstRssoUser <dst_RSSO_admin> --dstRssoPassword pass:<dst_RSSO_admin_password>

For example

tools\runAuthTool.bat --syncRsso --srcRssoRealm BAOLocal --srcRssoUrl https://repositoryABC-12345.bmc.com:28080 --srcRssoUser Admin --srcRssoPassword pass:Password --dstRssoUrl https://cdpABC-12345.bmc.com:38080 --dstRssoUser Admin --dstRssoPassword pass:Password


Related topics

Migration tool options
Downloading the installation files