EnterpriseDB · zefengzhi · May 29, 2025 · Jul 23, 2025
@@ -0,0 +1,206 @@
+---
+title: "Configuring and running the EDB DMS Agent"
+deepToC: true
+---
+
+Create migration credentials to enable the EDB DMS Agent on your [auxiliary machine](../terminology/#auxiliary-machine) to connect to the Hybrid Manager for migrations. You need one set of credentials per destination [Hybrid Manager project](../../../hybrid-manager/using_hybrid_manager/projects/).
+
+For example, if you are using a single Hybrid Manager project for all migrations, you only need one set of credentials on your auxiliary machine.
+
+1.  On the HM Console, select the project you are using for your migration activities.
+
+2.  Within your project, select **Migrate** > **Credentials**.
+
+3.  Select **Create Migration Credential**, enter a name for your credentials, and select **Create Migration Credential**.
+
+4.  After the credentials are generated, select **Download Credential**.
+
+    !!!note
+
+        This is the only opportunity you have to download the credentials. If you don't download them at this time, you will have to revoke them and create new credentials.
+
+5.  Unzip the downloaded zip file and copy the generated folder to the host where the reader is installed.
+
+## Configuring the agent
+
+1.  Ensure your machine has Java/OpenJDK 17 or later installed.
+
+1.  Open the EDB DMS Agent located in `/opt/cdcagent/run-cdcagent.sh` and ensure you have write permissions.
+
+1.  Set the variables according to your environment. Uncomment the lines as you edit or review them, the DMS can only perform migrations when all necessary values are provided. See [parameters](#parameters) for further guidance. The script is reproduced below.
+
+```shell
+#!/bin/bash -e
+# run_cdcagent.sh
+#
+# This script provides a convenient place to specify
+# environment variables used to configure the
+# EDB Data Migration Service Agent.
+#
+
+##########################################
+# DMS Agent General Configuration       #
+##########################################
+
+# This ID is used to identify DMS Agent
+# and is specified by the user.
+#export DBCONFIG_ID=
+
+# Determine the run mode of the DMS Agent
+# The run mode can be set to either 'reader' or 'writer'
+# 'reader' mode is used to read changes from a source database
+# 'writer' mode is used to write changes to a target database
+#export RUN_MODE=reader
+
+# This is the DMS backend service used by the Agent
+# Consult your system administrators
+#export RW_SERVICE_HOST=https://${RW_SERVICE_HOST}/transporter
+
+##########################################
+# DMS Agent TLS Configuration           #
+##########################################
+
+# You need to create migration credentials in EDB Postgres AI platform
+# and set set the path of the credentials directory
+#export CREDENTIAL_DIRECTORY_PATH=$HOME/credentials
+
+##########################################
+# DMS Agent DB Configuration     #
+##########################################
+
+# A sample configuration to create a single postgres database connection:
+#export DBCONFIG_DATABASES_0__TYPE=POSTGRES
+#export DBCONFIG_DATABASES_0__HOSTNAME=localhost
+#export DBCONFIG_DATABASES_0__PORT=5432
+# The CATALOG is the database name
+#export DBCONFIG_DATABASES_0__CATALOG=source
+#export DBCONFIG_DATABASES_0__USERNAME=postgres
+# The password env can be set without specifying it here
+# but the env structure looks like this
+#export DBCONFIG_DATABASES_0__PASSWORD=password
+
+# You can increase the index to configure more than
+# one database for the DMS Agent
+#export DBCONFIG_DATABASES_1__TYPE=ORACLE
+#export DBCONFIG_DATABASES_1__HOSTNAME=localhost
+#export DBCONFIG_DATABASES_1__PORT=1521
+# The CATALOG is the database name
+#export DBCONFIG_DATABASES_1__CATALOG=ORCLCDB/ORCLPDB1
+#export DBCONFIG_DATABASES_1__USERNAME=oracle
+# The password env can be set without specifying it here
+# but the env structure looks like this
+#export DBCONFIG_DATABASES_1__PASSWORD=password
+
+##########################################
+# Optional Parameters Below              #
+##########################################
+
+# FIPS mode can be enabled by setting the FIPS_MODE env variable to true
+#export FIPS_MODE=true
+
+# Configure logging
+# Generic loglevel
+#export QUARKUS_LOG_LEVEL=DEBUG
+# Loglevel for a single package
+#export QUARKUS_LOG_CATEGORY__COM_ENTERPRISEDB__LEVEL=DEBUG
+
+cd "$(dirname "$0")"
+
+echo "Starting in mode: $RUN_MODE"
+
+case "$RUN_MODE" in
+  reader)
+    java -jar ./reader/quarkus-run.jar
+    ;;
+  writer)
+    java -jar ./writer/quarkus-run.jar
+    ;;
+  *)
+    echo "Unknown RUN_MODE: $RUN_MODE"
+    exit 1
+    ;;
+esac
+
+```
+
+## Parameters
+
+### DMS Agent general configuration
+
+These parameters define the information the EDB DMS Agent requires to access the HCP instance and project that you are using for the migration.
+
+#### `DBCONFIG_ID`
+
+This is the name you assign to identify a source/destination. This name will later appear as a _destination_ in the **Migrate** > **Sources** or **Migrate** > **Destinations** section of the HCP Portal.
+
+Consider the following ID guidelines:
+
+- The maximum character length for the ID is 255 characters.
+- You can use lowercase and uppercase characters, numbers, underscores(_) and hyphens(-) for the ID. Other special characters are not supported.
+- The ID must be unique within a project. Do not use the same ID for two or more source/destinations in the same project.
+
+#### `RUN_MODE`
+This is the run mode of the EDB DMS Agent. Set it to `reader` if you are configuring the EDB DMS Reader, or to `writer` if you are configuring the EDB DMS Writer.
+*Configure and run the EDB DMS Writer only if the destination for your migration is a self-managed Postgres database.
+
+#### `RW_SERVICE_HOST`
+
+Specifies the URL of the service that will host the migration. Set `RW_SERVICE_HOST` to the domain name or host associated with the HCP ingress.
+
+Derive `RW_SERVICE_HOST` from the `TRANSPORTER_RW_SERVICE_DOMAIN_NAME` that was assigned by the administrators or installers of your HCP instance via the `values.yaml` file. Alternatively, derive `RW_SERVICE_HOST` from the URL you use to access the HCP portal.
+
+For example, if the URL for an HCP Portal is:
+
+`https://portal.foo-bar.enterprise.network`
+
+The `RW_SERVICE_HOST` will be:
+
+`https://transporter-rw-service.foo-bar.enterprise.network/transporter`
+
+where you replace `portal` with `transporter-rw-service` and add `/transporter` at the end of the endpoint.
+
+#### `CREDENTIAL_DIRECTORY_PATH`
+
+Directory path to the credential you downloaded from the HCP Portal.
+
+### DMS Agent database configuration
+
+These parameters (`DBCONFIG_DATABASES` section) define a list of source/destination database information you require for the EDB DMS Agent to be able to connect to the correct database for the migration.
+
+You can configure the EDB DMS Agent to migrate multiple databases. The `DBCONFIG_DATABASES_0__TYPE` section delimits the information for the first database. You can use `DBCONFIG_DATABASES_1__TYPE` to provide data for a second database. Add more sections to the EDB DMS Agent (`DBCONFIG_DATABASES_2__TYPE`, `DBCONFIG_DATABASES_3__TYPE`) by increasing the index manually.
+
+#### `DBCONFIG_DATABASES_0__TYPE`
+
+This is the source/target database type. EDB DMS reader supports `ORACLE` and `POSTGRES`. EDB DMS Writer supports `POSTGRES`.
+
+#### `DBCONFIG_DATABASES_0__HOSTNAME`
+
+The hostname of the source/target database.
+
+#### `DBCONFIG_DATABASES_0__PORT`
+
+The port of the source/target database.
+
+#### `DBCONFIG_DATABASES_0__CATALOG`
+
+The database name in the source/target database server.
+
+#### `DBCONFIG_DATABASES_0__USERNAME`
+
+The database username of the source/target database.
+
+#### `DBCONFIG_DATABASES_0__PASSWORD`
+
+The password for the database username of the source/target database.
+
+## Running the EDB DMS Agent
+
+1.  Start the agent:
+
+```shell
+cdcagent
+```
+
+1.  Go to the HCP Portal, and verify that a source/destination with the `DBCONFIG_ID` name is displayed in **Migrate** > **Sources** or **Migrate** > **Destinations**.
+
+You can select this source/destination for your [migration](create_migration).
@@ -6,9 +6,11 @@ navigation:
   - prepare_schema
   - installing
   - installing2
+  - installing_agent
   - preparing_db
   - config_reader
   - config_writer
+  - config_agent
   - create_migration
   - mark_completed
   - apply_constraints
@@ -26,20 +28,24 @@ Creating a migration from an Oracle or Postgres database to EDB Postgres AI invo
 
 2.  **[Prepare the source database schema](prepare_schema.mdx)**: In your source machine, prepare the source database by exporting it and excluding unsupported constraints. Then, import the adapted schema to the destination database.
 
-3.  **[Install the EDB DMS Reader](installing)**: In your source machine, install the EDB DMS Reader from the EDB repository.
+3.  **[Install the EDB DMS Reader(Only applicable to HCP with versions <= 1.2.0)](installing)**: In your source machine, install the EDB DMS Reader from the EDB repository.
 
-4.  **Optional** - [Install the EDB DMS Writer](installing2): Perform this step only if you want to migrate data to a destination database outside of the Hybrid Manager. In your destination machine, install the EDB DMS Writer from the EDB repository.
+4.  **Optional** - [Install the EDB DMS Writer(Only applicable to HCP with versions <= 1.2.0)](installing2): Perform this step only if you want to migrate data to a destination database outside of the Hybrid Manager. In your destination machine, install the EDB DMS Writer from the EDB repository.
 
-5.  **[Prepare your Oracle or Postgres database](preparing_db)**: In your source/destination machine, prepare the database by altering settings and creating users that are required for the migration. Ensure your database can accept SSL connections.
+5.  **[Install the EDB DMS Agent(For HCP with versions > 1.2.0)](installing_agent)**: In your source or destination machine, install the EDB DMS Agent from the EDB repository. DMS Agent is the package that will install the DMS Reader and DMS Writer together on your machine.
 
-6.  **[Configure the EDB DMS Reader](config_reader.mdx)**: In the Hybrid Manager Console, download dedicated migration credentials. In your source machine, configure the EDB DMS Reader by exporting environment variables that allow the Reader to connect to the source. Execute the Reader.
+6.  **[Prepare your Oracle or Postgres database](preparing_db)**: In your source/destination machine, prepare the database by altering settings and creating users that are required for the migration. Ensure your database can accept SSL connections.
 
-7.  **Optional - [Configure the EDB DMS Writer](config_writer.mdx)**: Perform this step only if you want to migrate data to a destination database outside of the Hybrid Manager. In your destination machine, configure the EDB DMS Writer by exporting environment variables that allow the Writer to connect to the destination. Execute the Writer.
+7.  **[Configure the EDB DMS Reader(Only applicable to HCP with versions <= 1.2.0)](config_reader.mdx)**: In the Hybrid Manager Console, download dedicated migration credentials. In your source machine, configure the EDB DMS Reader by exporting environment variables that allow the Reader to connect to the source. Execute the Reader.
 
-8.  **[Create a new migration](create_migration.mdx)**: In the EDB Postgres AI Console, create a new migration by selecting the source generated by the Reader in the Console, and selecting the destination database you created for this purpose.
+8.  **Optional - [Configure the EDB DMS Writer(Only applicable to HCP with versions <= 1.2.0)](config_writer.mdx)**: Perform this step only if you want to migrate data to a destination database outside of the Hybrid Manager. In your destination machine, configure the EDB DMS Writer by exporting environment variables that allow the Writer to connect to the destination. Execute the Writer.
 
-9.  **[Mark the Migration as completed](mark_completed.mdx)**: In the EDB Postgres AI Console, mark the migration as completed to stop the streaming process.
+9. **[Configure the EDB DMS Agent(For HCP with versions > 1.2.0)](config_agent)**: In the Hybrid Control Plane portal, download dedicated migration credentials. In your source or destination machine, configure the EDB DMS Agent by exporting environment variables that allow the Agent to connect to the source and destination databases. Execute the Agent.
 
-10. **[Reapply any excluded constraints](apply_constraints.mdx)**: Apply the constraints you excluded from the schema migration in the new database.
+10.  **[Create a new migration](create_migration.mdx)**: In the EDB Postgres AI Console, create a new migration by selecting the source generated by the Reader in the Console, and selecting the destination database you created for this purpose.
 
-11. **[Verify the migration completed successfully](verify_migration.mdx)**: Use LiveCompare to ensure the destination database has the same data as the source database.
+11.  **[Mark the Migration as completed](mark_completed.mdx)**: In the EDB Postgres AI Console, mark the migration as completed to stop the streaming process.
+
+12. **[Reapply any excluded constraints](apply_constraints.mdx)**: Apply the constraints you excluded from the schema migration in the new database.
+
+13. **[Verify the migration completed successfully](verify_migration.mdx)**: Use LiveCompare to ensure the destination database has the same data as the source database.
@@ -0,0 +1,38 @@
+---
+navTitle: Installing Agent
+title: Installing EDB Data Migration Service Agent on Linux
+indexCards: none
+
+navigation:
+  - linux_x86_64
+---
+
+Select a link to access the applicable installation instructions:
+
+## Linux [x86-64 (amd64)](linux_x86_64)
+
+### Red Hat Enterprise Linux (RHEL) and derivatives
+
+- [RHEL 9](linux_x86_64/edb-dms-agent_rhel_9), [RHEL 8](linux_x86_64/edb-dms-agent_rhel_8)
+
+- [Oracle Linux (OL) 9](linux_x86_64/edb-dms-agent_rhel_9), [Oracle Linux (OL) 8](linux_x86_64/edb-dms-agent_rhel_8)
+
+- [Rocky Linux 9](linux_x86_64/edb-dms-agent_other_linux_9), [Rocky Linux 8](linux_x86_64/edb-dms-agent_other_linux_8)
+
+- [AlmaLinux 9](linux_x86_64/edb-dms-agent_other_linux_9), [AlmaLinux 8](linux_x86_64/edb-dms-agent_other_linux_8)
+
+### SUSE Linux Enterprise (SLES)
+
+- [SLES 15](linux_x86_64/edb-dms-agent_sles_15)
+
+### Debian and derivatives
+
+- [Ubuntu 24.04](linux_x86_64/edb-dms-agent_ubuntu_24), [Ubuntu 22.04](linux_x86_64/edb-dms-agent_ubuntu_22)
+
+- [Debian 12](linux_x86_64/edb-dms-agent_debian_12), [Debian 11](linux_x86_64/edb-dms-agent_debian_11)
+
+## Linux [AArch64 (ARM64)](linux_arm64)
+
+### Debian and derivatives
+
+- [Debian 12](linux_arm64/edb-dms-agent_debian_12)
@@ -0,0 +1,36 @@
+---
+navTitle: Debian 12
+title: Installing EDB Data Migration Service Agent on Debian 12 arm64
+---
+
+## Prerequisites
+
+Before you begin the installation process:
+
+- Set up the EDB repository.
+
+  Setting up the repository is a one-time task. If you have already set up your repository, you don't need to perform this step.
+
+  To determine if your repository exists, enter this command:
+
+  `apt-cache search enterprisedb`
+
+  If no output is generated, the repository isn't installed.
+
+  To set up the EDB repository:
+
+  1. Go to [EDB repositories](https://www.enterprisedb.com/repos-downloads).
+
+  1. Select the button that provides access to the EDB repository.
+
+  1. Select the platform and software that you want to download.
+
+  1. Follow the instructions for setting up the EDB repository.
+
+## Install the package
+
+Install the EDB DMS Agent (packaged as `cdcagent`):
+
+```shell
+sudo apt-get install cdcagent
+```
@@ -0,0 +1,14 @@
+---
+title: "Installing EDB Data Migration Service Agent on Linux AArch64 (ARM64)"
+navTitle: "On Linux ARM64"
+indexCards: none
+
+navigation:
+  - edb-dms-agent_debian_12
+---
+
+Operating system-specific install instructions are described in the corresponding documentation:
+
+### Debian and derivatives
+
+- [Debian 12](edb-dms-agent_debian_12)
@@ -0,0 +1,36 @@
+---
+navTitle: Debian 11
+title: Installing EDB Data Migration Service Agent on Debian 11 x86_64
+---
+
+## Prerequisites
+
+Before you begin the installation process:
+
+- Set up the EDB repository.
+
+  Setting up the repository is a one-time task. If you have already set up your repository, you don't need to perform this step.
+
+  To determine if your repository exists, enter this command:
+
+  `apt-cache search enterprisedb`
+
+  If no output is generated, the repository isn't installed.
+
+  To set up the EDB repository:
+
+  1. Go to [EDB repositories](https://www.enterprisedb.com/repos-downloads).
+
+  1. Select the button that provides access to the EDB repository.
+
+  1. Select the platform and software that you want to download.
+
+  1. Follow the instructions for setting up the EDB repository.
+
+## Install the package
+
+Install the EDB DMS Agent (packaged as `cdcagent`):
+
+```shell
+sudo apt-get install cdcagent
+```