All Products
Search

This Product

    Data Online Migration:Agent management

    Document Center

    Data Online Migration:Agent management

    Last Updated:Oct 10, 2025

    This topic describes how to create, deploy, scale, and upgrade agents.

    Create an agent

    Agents support two network types: the Internet and a virtual private cloud (VPC) that uses a leased line or VPN. You can select a network type based on your requirements. When you create an agent, you must associate it with an existing channel. You must create a channel in advance. For more information about how to create a channel, see Channel management.

    Important

    • You must create a channel and an agent for scenarios such as migrating data to the cloud over a leased line or VPN, migrating data from self-managed storage to the cloud, or using LocalFs as the source.

    • You must deploy the agent on a machine that runs a 64-bit Linux operating system with kernel version 2.6 or later. Prepare a machine that meets these requirements in advance.

    • You can create a maximum of 100 agents in each region. Plan your resources accordingly.

    • Purchase ECS instances of the 7th generation or later, such as ecs.c7.xlarge.

    1. Log on to the Data Online Migration console.

    2. In the navigation pane on the left, choose Agent Management.

    3. On the Agent Management page, click Create Agent.

    image

    1. In the Create Agent dialog box, configure the following parameters and click OK.

      image

      Parameter

      Required

      Description

      Name

      Yes

      The name of the agent.

      • The name cannot be empty and must be 3 to 63 characters in length.

        • It can contain lowercase English letters, digits, hyphens (-), and underscores (_). The name is case-sensitive.

        • The name must be in UTF-8 encoding and cannot start with a hyphen (-) or an underscore (_).

      Network Type

      Yes

      The network connection method for the agent. It includes the following two types:

      • VPC (Recommended): The agent connects to the Data Online Migration service through a VPC. This method requires the machine where the agent is deployed to be able to access the internal same-region endpoint of the Data Online Migration service in the corresponding region. For example, if you use the migration service in the China (Beijing) region, the agent machine must be able to access the internal same-region endpoint {TunnelId}.cn-beijing.mgw-tc-internal.aliyuncs.com. Use an ECS instance in the same region as the Data Online Migration console to deploy the agent.

      • Internet: The agent connects to the Data Online Migration service over the Internet. This method requires the machine where the agent is deployed to be able to access the public endpoint of the Data Online Migration service in the corresponding region. For example, if you use the migration service in the China (Beijing) region, the agent machine must be able to access the public endpoint {TunnelId}.cn-beijing.mgw-tc.aliyuncs.com.

      Note

      • TunnelId indicates the channel ID.

      • You can use the ping command to test the network connectivity between the agent and the migration service.

      Deployment Method

      Yes

      The deployment method of the agent. Currently, only the standalone process deployment method is supported.

      Channel

      Yes

      The channel to which the agent belongs. An agent can be associated with only one channel. The bandwidth of the agent is affected by the total bandwidth of the channel.

      For example, a channel named tunnel-1 has a maximum bandwidth of 10 Gbit/s. tunnel-1 is associated with three agents: agent-1, agent-2, and agent-3. The total bandwidth of the three agents cannot exceed 10 Gbit/s. If you set the bandwidth of agent-1 to 3 Gbit/s, only 7 Gbit/s of bandwidth is available for agent-2 and agent-3. Plan and allocate bandwidth carefully.

    Generate a deployment script for an agent

    Prerequisites

    • The machine must have at least 4 CPU cores, 8 GB of memory, and 4 GB of available log space.

    • Create a new Resource Access Management (RAM) user to deploy the agent. Grant the AliyunOSSImportReadOnlyAccess permission to the RAM user and set Authorization Scope to Entire Alibaba Cloud Account.

      Note

      The AccessKey of a RAM user can be used to deploy multiple agents simultaneously without conflicts.

    Procedure

    1. On the Agent Management page, click the name of the agent to go to its details page.

    2. Click Deploy And Run. In the Deploy And Run dialog box, configure the following parameters in the Key section.

      Parameter

      Required

      Description

      AccessKey ID

      Yes

      Used for identity authentication when the agent establishes a transmission channel with the Data Online Migration service. The mgw:VerifyAgentTunnel permission is required.

      Note

      Follow the principle of least privilege. Grant only a custom policy that includes the mgw:VerifyAgentTunnel permission. You can also grant one of the following system policies as needed:

      • AliyunOSSImportReadOnlyAccess (read-only permission to manage Data Online Migration)

      • AliyunOSSImportFullAccess (full management permission)

      AccessKey Secret

      Yes

    3. Click the image.png icon in the Advanced Settings area to configure the following parameters.

      Parameter

      Required

      Description

      Number Of CPU Cores

      No

      The number of CPU cores that the agent can use.

      • If you do not set this parameter, all CPU cores of the machine are used by default.

      • If you set this parameter, carefully evaluate the value based on the prompt in the console.

      Maximum Memory (GB)

      No

      The maximum memory that the agent can use.

      • If you do not set this parameter, all memory of the machine is used by default.

      • If you set this parameter, carefully evaluate the value based on the prompt in the console.

      Log Space (GB)

      No

      The maximum disk space that agent logs can occupy. When the maximum value is reached, logs are discarded based on their age.

      • If you do not set this parameter, logs occupy 4 GB by default.

      • If you set this parameter, evaluate the value based on the number of files to be migrated. Refer to the prompt in the console. Migrating one million files generates about 4 GB of disk logs.

      Maximum Available Bandwidth

      No

      The maximum bandwidth of the agent. This is affected by the total bandwidth of the associated channel and cannot be higher than the maximum bandwidth set for the channel. For example:

      • If the maximum bandwidth of the channel is set to 5 Gbit/s, the maximum available bandwidth for a single agent cannot exceed 5 Gbit/s.

      • If no maximum bandwidth is set for the channel, the maximum available bandwidth for the agent cannot exceed 100 Gbit/s.

      Note

      An agent can be associated with only one channel. The bandwidth of the agent is affected by the total bandwidth of the channel.

      For example, a channel named tunnel-1 has a maximum bandwidth of 10 Gbit/s. tunnel-1 is associated with three agents: agent-1, agent-2, and agent-3. The total bandwidth of the three agents cannot exceed 10 Gbit/s. If you set the bandwidth of agent-1 to 3 Gbit/s, only 7 Gbit/s of bandwidth is available for agent-2 and agent-3. Plan and allocate bandwidth carefully.

    4. Click Deploy Agent Using Command.

    Deploy an agent

    Important

    • The automatically generated agent deployment command contains unique information, such as the agent ID, and can be used to deploy only the current agent. To deploy multiple agents, you must generate a separate deployment command for each agent and run it on a different machine. Otherwise, the deployment may fail or the agent status may become abnormal.

    • If the data type for migration is LocalFS (including LocalFS to OSS, OSS to LocalFS, and LocalFS to LocalFS migrations), the agent must be deployed and run as the root user. Otherwise, file migration may fail because of system calls such as chown and chmod.

    Deploy an agent online

    If you set Network Type to Internet for the agent, you must deploy the agent online.

    image

    1. View the content in the Deploy And Run The Agent Using A Command dialog box. Log on to the machine where you want to install the agent. You can use connection tools provided by Alibaba Cloud, such as Workbench or VNC, or use third-party client tools.

    2. On the deployment machine, confirm that the curl command is installed and available. Then, run the curl -I https://www.aliyun.com command to check the Internet connectivity.

    3. Copy the command to run and deploy the agent from the dialog box. Run the command in a local disk directory on the deployment machine. Do not run the command in a remotely mounted directory such as a NAS directory. If the command runs successfully, the agent is deployed. The command format and parameter descriptions are as follows. The actual command and parameters in the console may be different due to updates.

      wget https://gosspublic.alicdn.com/data_online_migration/agent/aliyun_import_agent_deploy.sh -O aliyun_import_agent_deploy.sh;chmod 755 aliyun_import_agent_deploy.sh;./aliyun_import_agent_deploy.sh -t <TunnelID> -u <UID> -i <AK> -k <SK> -n <AgentName> -v <AgentID> -e <Endpoint> -f <AgentDeployMethod> -c <CpuUsage> -m <MemoryUsage> -d <LogMemoryUsage> -b <MaxBandwidth>

      Parameter

      Description

      TunnelID

      The channel ID.

      UID

      The Alibaba Cloud account ID.

      AK

      The AccessKey ID.

      SK

      The AccessKey secret.

      AgentName

      The agent name.

      AgentID

      The agent ID.

      Endpoint

      The Endpoint. `public` indicates the Internet.

      AgentDeployMethod

      The deployment method of the agent. `default` indicates the standalone process method.

      CpuUsage

      Specifies the number of CPU cores. This parameter is displayed only when a value is set.

      MemoryUsage

      Specifies the memory to use (in GB). This parameter is displayed only when a value is set.

      LogMemoryUsage

      Specifies the log space (in GB). This parameter is displayed only when a value is set.

      MaxBandwidth

      Specifies the maximum available bandwidth (in MB). This parameter is displayed only when a value is set.

    4. After the agent is deployed, you can create a data address and associate it with the agent. Migration tasks that are created using this data address are executed on the agent machine.

    Deploy an agent offline

    If you set Network Type to Leased Line/VPN (VPC) for the agent, you must deploy the agent offline.

    image

    1. View the content in the Deploy And Run The Agent Using A Command dialog box. Log on to the machine where you want to install the agent. You can use connection tools provided by Alibaba Cloud, such as Workbench or VNC, or use third-party client tools.

    2. Download the agent installation package aliyun_import_agent_offline_bundle.tar.gz and upload it to the deployment machine.

    3. On the deployment machine, go to the directory where the agent installation package is stored and run the tar -zxvf aliyun_import_agent_offline_bundle.tar.gz command to decompress the package.

    4. After the package is decompressed, go to the aliyun_import_agent_offline_bundle directory. Copy the command to run and deploy the agent from the dialog box. Run the command in a local disk directory on the deployment machine. Do not run the command in a remotely mounted directory such as a NAS directory. If the command runs successfully, the agent is deployed. The command format and parameter descriptions are as follows. The actual command and parameters in the console may be different due to updates.

      chmod 755 aliyun_import_agent_deploy.sh;./aliyun_import_agent_deploy.sh -t <TunnelID> -u <UID> -i <AK> -k <SK> -n <AgentName> -v <AgentID> -e <Endpoint> -f <AgentDeployMethod> -c <CpuUsage> -m <MemoryUsage> -d <LogMemoryUsage> -b <MaxBandwidth> -l <VPCType>

      Parameter

      Description

      TunnelID

      The channel ID.

      UID

      The Alibaba Cloud account ID.

      AK

      The AccessKey ID.

      SK

      The AccessKey secret.

      AgentName

      The agent name.

      AgentID

      The agent ID.

      Endpoint

      The Endpoint. `vpc` indicates a leased line or VPN.

      AgentDeployMethod

      The deployment method of the agent. `default` indicates the standalone process method.

      CpuUsage

      Specifies the number of CPU cores. This parameter is displayed only when a value is set.

      MemoryUsage

      Specifies the memory to use (in GB). This parameter is displayed only when a value is set.

      LogMemoryUsage

      Specifies the log space (in GB). This parameter is displayed only when a value is set.

      MaxBandwidth

      Specifies the maximum available bandwidth (in MB). This parameter is displayed only when a value is set.

      VPCType

      A parameter specific to the VPC network type.

    5. After the agent is deployed, you can create a data address and associate it with the agent. Migration tasks that are created using this data address are executed on the agent machine.

    Scale out an agent

    1. Create a new agent. For more information, see Create an agent.

    2. Generate a deployment script for the agent. For more information, see Generate a deployment script for an agent.

    3. Deploy the agent. For more information, see Deploy an agent.

    4. Add the new agent to the data address.

      1. In the navigation pane on the left, choose Address Management.

      2. On the Address Management page, find the data address that you want to manage and click Modify in the Actions column. The Modify Address dialog box appears.

      3. In the dialog box, click the Agent drop-down list and select the agent that you want to associate.

      4. Click OK.

      image

    Scale in an agent

    1. To remove the proxies, follow these steps:

      1. Log on to the Data Online Migration console. In the navigation pane on the left, choose Address Management.

      2. On the Address Management page, find the data address that you want to manage and click Modify in the Actions column. The Modify Address dialog box appears.

      3. In the dialog box, click the Agent drop-down list and remove the agent that you want to scale in.

      4. Click OK.image

    2. Clean up the agent.

      1. Delete the agent in the Data Online Migration console.

        1. In the navigation pane on the left, choose Agent Management.

        2. On the Agent Management page, find the agent that you want to delete and click Delete in the Actions column. The Confirm Deletion dialog box appears.

        3. Click OK.

          image

    3. Release the agent machine (Optional).

      If you confirm that the machine is used only for migration and releasing it does not affect other services, you can release the agent machine.

    Upgrade an agent

    1. Pause the migration task.

      1. Log on to the Data Online Migration console. In the navigation pane on the left, choose Migration Tasks.

      2. On the Migration Tasks page, find the task that you want to manage and click Manage in the Actions column to go to the migration task details page.image

      3. At the bottom of the migration task details page, click Pause in the history section.image

    2. Stop the agent program on the agent machine.

      1. Log on to the agent machine and go to the root directory of the agent program, for example, /root/aliyun_import_agent_online_res.

      2. Run the bash bin/stop.sh command and wait for the agent program to stop.

    3. Check the old agent version number.

      1. Log on to the agent machine, run the ./bin/drs_import_agent -v command, and record the Version number.image

    4. Deploy the agent.

      1. Generate a deployment script for the agent. For more information, see Generate a deployment script for an agent.

      2. Deploy the agent. For more information, see Deploy an agent.

    5. Check whether the agent is successfully upgraded.

      1. Log on to the agent machine and go to the root directory of the agent program, for example, /root/aliyun_import_agent_online_res.

      2. Run the ./bin/drs_import_agent -v command and compare the new version number with the old one. If the version number is updated, the agent is successfully upgraded.

    View, start, and stop the agent process

    Note

    • After the agent is successfully deployed, the agent process starts automatically. You do not need to perform any other operations.

    • The agent process is not added to the startup items. Therefore, you must manually start the agent process if the machine restarts or the process stops for other reasons.

    • If an agent is no longer in use, stop the agent process and promptly delete the corresponding agent instance in the console.

    1. To view the agent process, follow these steps:

      1. Log on to the agent machine and go to the root directory of the agent program, for example, /root/aliyun_import_agent_online_res.

      2. Run the ps -ef | grep drs_import_agent command to view process information, such as the process ID and the running directory.image

      3. The agent generates log files during runtime. By default, the log files are generated in the logs/ directory under the root directory of the agent program. The log files are automatically scrolled based on the log space parameter that you specified during deployment.

    2. To start the agent process, follow these steps:

      1. Log on to the agent machine and go to the root directory of the agent program, for example, /root/aliyun_import_agent_online_res.

      2. Check the agent process. If the process does not exist, run the bash bin/start.sh command to start it.

    3. To stop the agent process, follow these steps:

      1. Log on to the agent machine and go to the root directory of the agent program, for example, /root/aliyun_import_agent_online_res.

      2. Run the bash bin/stop.sh command and wait for the agent program to stop.

      3. After the agent stops, log on to the Data Online Migration console and check the status of the agent instance. If the status changes to Connection Abnormal, the agent has completely stopped.

    Key configuration parameters for the agent

    When you deploy an agent, its runtime parameters are configured by the deployment command that you generate in the console. These parameters are saved to the agent-config.properties file in the config/ directory of the agent program's root directory (for example, /root/aliyun_import_agent_online_res/config/agent-config.properties).

    Important

    • The default configuration parameters are suitable for most migration scenarios. You do not need to modify them.

    • The following table lists only some of the key parameters for the agent. Do not modify configuration parameters that are not listed in the table.

    • Before you modify the configuration parameters in the table, make sure that you understand their functions, scopes, and potential risks.

    Configuration item parameter

    Valid Values

    Description

    ssrfBlacklistOn

    Default value: true

    Valid values: true, false

    Important

    Disabling this feature reduces the controllability of the agent process and poses certain security risks.

    Specifies whether to enable the Server-Side Request Forgery (SSRF) blacklist detection feature. If enabled, the IP address of the remote host is checked before any network connection is established. If the IP address is within the Private endpoint range, the connection is rejected.

    Example:

    ssrfBlacklistOn=false

    The Private endpoint range includes:

    • 0.0.0.0/8

    • 127.0.0.0/8

    • 10.0.0.0/8

    • 11.0.0.0/8

    • 25.0.0.0/8

    • 26.0.0.0/8

    • 30.0.0.0/8

    • 33.0.0.0/8

    • 192.168.0.0/16

    • 100.64.0.0/10

    • 172.16.0.0/12

    • 169.254.0.0/16

    • ::1/128

    • fe80::/10

    • fc00::/7

    allowRedirectProviders

    Default value: Empty

    Valid values: Any data address type. If there are multiple types, separate them with commas (,).

    Note

    By default, Data Online Migration does not support redirection for any data address type. If a source or destination address request returns a redirection status code, the migration will report the UnsupportedRedirect error code.

    Specifies whether to support the HTTP protocol redirection feature when accessing source and destination addresses. This only takes effect for the specified data address types.

    Example:

    allowRedirectProviders=qiniu,s3

    After you modify and save the configuration items, you must restart the agent process for the changes to take effect.