Database Migration Agent Requirements

The Database Migration agent can be configured on Oracle Linux 7 (Linux-x86-64) or later releases.

You can deploy the agent on a standalone server on-premises or on a standalone Linux server (compute instance) in the Oracle Cloud. Oracle Linux is the supported platform for the agent. Note that the agent host can be shared with other applications for other purposes.

The Database Migration agent host needs to access the source and target database servers during a database migration. To perform the migration, the agent requires either root user or SSH key-based access to one of the source database servers, and the agent host requires SSH key-based access to one of the target database servers.

If you are migrating an Oracle RAC database, providing access to one of the Oracle RAC nodes is adequate. The agent host copies the software needed for migration to the source and target servers and cleans it up at the end of the operation.

An SSH private key is required to establish SSH connections. You can create and add a new SSH key to your existing deployment using the Oracle Cloud Service Console.

The examples used in these steps assume that you will install the agent in an on-premises host, but you can use any host that conforms to the agent host requirements, including an Oracle Cloud Infrastructure instance.

All commands are run as dmsuser.

1. In the OCI Console Menu, go to Database Migration > Agents.

2. Click Download Agent Installer, located above the agent list.

3. When the save file dialog opens, save the file dmsagentkit_21_date.zip to your agent host using SFTP or other means.

   For example, save the agent installer file in /tmp/dmsagentkip_21_210303.zip on the agent host.

4. Open an SSH terminal on the agent host as a non-root user, dmsuser for example, and create an agent directory and three subdirectories as shown in this example. You can choose your own names for the directories.

   • mkdir ~/agent
   • mkdir ~/agent/home
   • mkdir ~/agent/base
   • mkdir ~/agent/install

5. Change to the directory to where the agent installer is downloaded and unzip the installer to the installation subdirectory you created, for example /agent/install.

   dmsuser> cd agent_download_directory
   dmsuser> unzip -q -d ~/agent/install dmsagentkip_21_210303.zip

6. Run the following commands using the information listed in the table at the beginning of this task.

   dmsuser> cd ~/agent/install
   
   dmsuser> ./dmsagent_install.sh \
   agentName=agentname \
   home=agent_home_subdirectory_you_created_above \
   base=agent_base_subdirectory_you_created_above \
   ziploc=ziploc \
   region=region \
   compartmentId=compartmentId \
   streamId=streamId \
   tenancyId=tenancyId \
   userId=userId \
   userFingerprint=userFingerprint \
   userPrivateKey=userPrivateKey
   

7. Observe the output of the script. Output for a successful installation looks like the following example.

   [opc@dmsagent agent]$ ./install.sh
   ++ cd /home/opc/agent/install
   ++ ./dmsagent_install.sh agentName=testagent home=/home/opc/agent/home
    base=/home/opc/agent/base ziploc=/home/opc/agent/install/zdm_home.zip
    region=us-ashburn-1 compartmentId=ocid1.compartment.oc1..[snip]
    streamId=ocid1.stream.oc1.iad.[snip]
    tenancyId=ocid1.tenancy.oc1..[snip]
    userId=ocid1.user.oc1..[snip]
    userFingerprint=00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
    userPrivateKey=/home/opc/agent/ggsstage_api_key.pem
   Mar 17, 2021 1:01:36 AM com.oracle.bmc.Services create
   INFO: Registering new service: Services.BasicService(serviceName=MIGRATIONDEPLOYMENT,
    serviceEndpointPrefix=migrations,
    serviceEndpointTemplate=https://odms.{region}.oci.{secondLevelDomain})
   Mar 17, 2021 1:01:36 AM com.oracle.bmc.Region getEndpoint
   INFO: Loaded service 'MIGRATIONDEPLOYMENT' endpoint mappings:
    {US_ASHBURN_1=https://odms.us-ashburn-1.oci.oraclecloud.com}
   Mar 17, 2021 1:01:36 AM com.oracle.bmc.util.JavaRuntimeUtils <clinit>
   INFO: Determined JRE version as Java_8
   Mar 17, 2021 1:01:36 AM com.oracle.bmc.http.DefaultConfigurator setConnectorProvider
   INFO: Setting connector provider to HttpUrlConnectorProvider
   Mar 17, 2021 1:01:36 AM com.oracle.zdmcs.MigrationDeploymentClient setEndpoint
   INFO: Setting endpoint to https://odms.us-ashburn-1.oci.oraclecloud.com
   Mar 17, 2021 1:01:36 AM com.oracle.zdmcs.MigrationDeploymentClient <init>
   INFO: Authentication details provider configured for region 'US_ASHBURN_1',
    but endpoint specifically set to 'https://odms.us-ashburn-1.oci.oraclecloud.com'.
    Using endpoint setting instead of region.
   Mar 17, 2021 1:01:36 AM com.oracle.zdmcs.MigrationDeploymentClient setEndpoint
   INFO: Setting endpoint to https://odms.us-ashburn-1.oci.oraclecloud.com
   Mar 17, 2021 1:01:38 AM com.oracle.bmc.ClientRuntime <init>
   INFO: Using SDK: Oracle-JavaSDK/1.19.3-preview1-SNAPSHOT
   Mar 17, 2021 1:01:38 AM com.oracle.bmc.ClientRuntime <init>
   INFO: User agent set to: Oracle-JavaSDK/1.19.3-preview1-SNAPSHOT
    (Linux/5.4.17-2036.102.0.2.el7uek.x86_64; Java/1.8.0_281;
    Java HotSpot(TM) 64-Bit Server VM/25.281-b04)
   
   
   DMS Agent OCID: ocid1.odmsagent.oc1.iad.[snip]

   After the install script has successfully completed, the agent is registered with OCI and is running. No further commands are necessary on the agent instance.

   If the installation outcome is different from the above example, review the log file at ~/install/zdminstall.trc for error messages.

Whether you use the console, the dmsagent commands, or the API depends on what operations you need to perform on the agent. There are different ways to manage Database Migration agents depending on where they are installed.

Using the Console

You can manage agents in the Agents page of the Database Migration console. The console lets you see all of the registered agents at a glance, and also lets you delete agents, move the agent resources, copy OCIDs, and manage tags.

Using the Agent Commands

To run commands on the agent connect to the agent host as the Database Migration agent installer user. The example user dmsuser is used to run agent commands throughout this document.

For example, the following command gets the status of the agent.

dmsuser> ~/agent/home/bin/dmsagent status

Using the API

If you installed the agent on an Oracle Cloud Infrastructure instance, you can use the Agent REST API to manage the agent. This can be done using the OCI CLI. See Using the Agent API.

The Database Migration agent must be running before you can migrate your databases with the OCI Database Migration service. The installation process starts the agent, but if you need to stop and restart the agent use these dmsagent commands.

To start the agent, connect to the agent host and run:

dmsuser> ~/agent/home/bin/dmsagent start

To stop the agent, connect to the agent host and run:

dmsuser> ~/agent/home/bin/dmsagent stop

You can get agent status using the Oracle Cloud Infrastructure console, or use the dmsagent status command.

Using the Console

The Database Migration > Agents page lists all of the agents, their states, versions, and the dates they were created.

Using the Agent Commands

To check the agent status, connect to the agent host and run:

dmsuser> ~/agent/home/bin/dmsagent status

You can install multiple agents in a compartment. To list the agents in a given compartment that are registered with OCI, you can use the Oracle Cloud Infrastructure console, or use the API.

Using the Console

Go to the Database Migration > Agents page and select a compartment where agents are registered. The agents in the given compartment are listed in the table.

You can filter the list by State or tags using the console controls.

Using the API

To list agents the in a given compartment, use the ListAgents API.

You can move a Database Migration agent resource from one compartment to another.

To move an agent:

After you move the agent to the new compartment, inherent policies apply immediately and may affect access to the agent through the Console. For more information, see Managing Compartments.

You can delete an agent using the Oracle Cloud Infrastructure console or the API.

Using the Console

1. In the list of agents on the Agents page, select Delete from the Actions (three dots) menu for the agent you want to move.

2. In the Delete dialog, click Delete.

Go to the Database Migration > Agents page and select a compartment where agents are registered. The agents in the given compartment are listed in the table.

Using the API

To delete agents the in a given compartment, use the DeleteAgent API.