7 Managing Agents

Oracle Cloud Infrastructure Database Migration uses agents to connect with source databases that are that are not directly accessible from the cloud.

When you configure a migration resource with no direct connection to the source database, you must first download and install an agent to use as a bridge to the source database.

Note:

This option only allows offline migrations.

About the Database Migration Agent

In Oracle Cloud Infrastructure Database Migration, when you want to migrate a source database that doesn't have a direct connection with the target database on OCI, you must deploy a agent to act as the bridge between the source database and the cloud target.

Note that migrations from indirect sources can only be done in offline mode.

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.

Prepare a Host for Database Migration Agent Installation

If a host has not had Database Migration agent software installed on it previously, verify that it complies with the requirements listed here.

Provision a host with the following prerequisites and complete the following tasks before installing the agent on it.

  • The agent requires a standalone Linux host running Oracle Linux 7 or later release.

  • The agent host should be a dedicated system, but it can be shared for other purposes; however, the agent host should not have Oracle Grid Infrastructure running on it.

  • The agent host must be able to connect to both the source and the target database servers.

  • Ensure that the Linux host has 100 GB of free storage space.

  • You may use an existing user, or, as root user on the agent host create a dms group and add dmsuser user to the group.

    For example,

    root> groupadd dms
    root> useradd –g dms dmsuser
  • Verify that the glibc-devel and expect packages are installed.

    For Oracle Linux 7 installations with Base Environment "Minimal Install" you also need to install the packages unzip libaio oraclelinux-developer-release-el7.

  • Verify that the /etc/hosts entry for the host name and IP address are configured as expected, so that the agent host resolves to the correct IP address and the IP address is reachable with ping.

  • During the installation, the script might report any missing packages and instructions for setting appropriate values for kernel parameters. Be sure to install the missing packages and set the kernel parameters before installing the agent.

  • Optionally, set a DMS_HOME environment variable to the absolute path of the directory where the Database Migration agent will be installed. All of the examples in this document use $DMS_HOME.

    dmsuser> export DMS_HOME=absolute_path_to_dms_home

Create a Stream

The Oracle Cloud Infrastructure Database Migration agent requires a stream, created in Oracle Streaming, to communicate asynchronously with the service.

  1. In the Oracle Cloud Interface Console menu, go to Analytics > Streaming.

  2. Select Create Stream.

  3. Enter the following values, otherwise leave defaults:

    • Stream Name: Enter a name, for example, DMSStream

      • Press Create

  4. Wait until the stream becomes active, then open the stream from list

  5. Copy the OCID of the stream. You will need it later to configure the Database Migration agent installer.

See Creating and Managing Streams for additional information about streams.

Create an API Key

  1. Create an API key in the Oracle Cloud Interface Console, or use an existing one. See Required Keys and OCIDs for more information about creating an API key.

    Note that there is a limit of 2 API keys per user.

  2. Note the fingerprint value (for example, 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00) and the private key file location (for example, ~/agent/agent_api_key.pem) of the API key. You will need this information to run the agent installer.

  3. Transfer the private key file to your agent host using SFTP or other means.

Installing a Database Migration Agent

The configuration information listed in the table below is required to install the Database Migration agent and register it with Oracle Cloud Infrastructure. Some of this information is gathered from the previous tasks, and some you will collect as you do the steps below.

Table 7-1 Required Database Migration Installation Information

Name Example Where to Find
home ~/agent/home Empty directory for the agent home. You will create this directory in the steps below.
base ~/agent/home Empty directory for the agent base. You will create this directory in the steps below.
ziploc ~/agent/install/dms_home.zip Location of the Home archive that is unpacked from the Installer archive in the steps below.
region us-ashburn-1 OCI region of the Database Migration service to be used.
tenancyId ocid1.tenancy.oc1..[…] OCID of the Tenancy where Migrations will be located. This information can be found in the OCI Console Profile menu.
userId ocid1.user.oc1..[…] OCID of the User using this Agent. This information can be found in the OCI Console Profile menu.
compartmentId ocid1.compartment.oc1.[…] OCID of the Compartment where Migrations will be located. Can be found in the OCI Console Identity > Compartments menu.
streamId ocid1.stream.oc1.[…] OCID of the OCI Streaming Service Stream, which you configured in the previous task for creating the stream object.
userFingerprint 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 Fingerprint of the API Key to be used with the Agent, which you configured in the previous task for creating the API Key.
userPrivateKey ~/agent/agent_api_key.pem Private Key for the API Key to be used with the Agent, which you configured in the previous task for creating the API Key.

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.

Managing Database Migration Agents

The Oracle Cloud Infrastructure Database Migration agent accepts commands to start, stop, list, and delete agents.

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.

Starting and Stopping the Database Migration Agent

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

Getting Database Migration Agent Status

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

Listing Database Migration Agents

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.

Moving a Database Migration Agent

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

To move an agent:

  1. In the list of agents on the Agents page, select Move Resource from the Actions (three dots) menu for the migration you want to move.
  2. In the Move Resource to a Different Compartment dialog, select the compartment to move the agent to from the dropdown.
  3. Click Move Resource.

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.

Deleting a Database Migration Agent

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.

Managing Tags for Database Migration Agents

Tags help you locate resources within your tenancy. You can add and view an agent's tags from the Agents page in Oracle Cloud Infrastructure Database Migration.

On the Agents page, from the agent's Actions (three dots) menu, select Add Tags or View Tags.

Learn more about tagging at Managing Tags and Tag Namespaces.

Using the Agent API

You can use the following operations to manage Database Migration agents:

For information about using the API and signing requests, see REST APIs and Security Credentials. For more information about SDKs, see Software Development Kits and Command Line Interface.