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.
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
andexpect
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 withping
. -
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.
-
In the Oracle Cloud Interface Console menu, go to Analytics > Streaming.
-
Select Create Stream.
-
Enter the following values, otherwise leave defaults:
-
Stream Name: Enter a name, for example, DMSStream
-
Press Create
-
-
-
Wait until the stream becomes active, then open the stream from list
-
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
-
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.
-
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. -
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.
-
In the OCI Console Menu, go to Database Migration > Agents.
-
Click Download Agent Installer, located above the agent list.
-
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. -
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
-
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
-
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
-
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:
- 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.
- In the Move Resource to a Different Compartment dialog, select the compartment to move the agent to from the dropdown.
- 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
-
In the list of agents on the Agents page, select Delete from the Actions (three dots) menu for the agent you want to move.
-
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.