All Products
Search
Document Center

Elastic Compute Service:Enable eRDMA on an enterprise-level instance

Last Updated:May 26, 2026

Some enterprise-level ECS instances support eRDMA. This feature delivers an ultra-low-latency, high-throughput, and highly elastic RDMA network service without requiring changes to your existing network architecture. This topic explains how to enable eRDMA on enterprise-level ECS instances.

Limitations

Limitation

Description

Instance type

The following instance types support eRDMA:

Image

  • Alibaba Cloud Linux 3 (recommended)

  • Alibaba Cloud Linux 2 (x86-based systems only)

  • CentOS 7.9 (x86-based systems only)

  • Ubuntu 18.04, 20.04, 22.04, or 24.04

  • Anolis OS 8.4 ANCK or 8.6 ANCK (Arm-based versions only)

Note

The available images vary by instance type. The instance buy page displays only the images that are compatible with the selected instance type.

Number of eRDMA devices

To query the maximum number of ERIs for an instance type, call the DescribeInstanceTypes operation and check the EriQuantity parameter. A value of 0 means the instance type does not support ERIs.

Network limitations

  • After you enable the ERI feature for an elastic network interface (ENI), you cannot assign IPv6 addresses to the ENI.

  • The eRDMA communication path between two instances cannot pass through network elements such as Server Load Balancer (SLB) instances.

  • A GPU-accelerated instance and an enterprise-level instance that both have eRDMA enabled cannot communicate directly because they operate in different eRDMA modes. To enable communication, you must deploy eRDMA on the enterprise-level instance using the same method as for GPU-accelerated instances. This involves installing the eRDMA driver and the OpenFabrics Enterprise Distribution (OFED) driver, and then binding an Elastic RDMA network interface card (ERI) to the instance. For more information, see Enable eRDMA on GPU-accelerated instances.

Configure eRDMA on enterprise instances

During instance creation

Important
  • If the operating system does not support automatic installation of the eRDMA driver, or if the automatic installation fails, you can install the driver manually or using a script after the instance is created. For more information, see For existing instances.

  • The eRDMA driver installation begins after the instance starts and may take some time to complete.

  1. Go to the ECS instance buy page.

  2. Create an enterprise-level instance that supports the ERI feature. Note the following parameters when creating the instance. For information about other parameters, see Create an instance by using the wizard.

    • Instances & Images: Select an instance type that supports eRDMA and install the eRDMA driver.

      • Instance: For more information, see Limitations.

      • Images: Select Public Image and then select Install eRDMA Driver. The eRDMA driver is automatically installed when the instance starts.

        image

    • ENIs: To the right of Primary ENI, enable the ERI feature to bind an ERI to the ECS instance.

      image

      Note

      When you create an enterprise-level instance, you can enable the ERI feature only for the primary ENI. If you need to configure eRDMA for a secondary ENI, you can enable the ERI feature for the secondary ENI in the console or by calling an API operation. For more information, see Elastic RDMA network interface card (ERI).

For existing instances

  1. Verify that the instance type is on the list of eRDMA-supported instance types.

    You need to select an instance type that supports eRDMA.

  2. Verify the eRDMA configuration on the instance.

    • Verify whether eRDMA is correctly configured on the instance. For more information, see Verify the eRDMA configuration.

    • If eRDMA is not configured, install the eRDMA driver and bind an ERI.

  3. Install the eRDMA driver for the instance.

    If you did not select eRDMA Driver when you created the instance, the eRDMA driver is not automatically installed. You must install the eRDMA driver manually or by using a script.

    • Script-based method: By default, the latest stable version of the driver package is downloaded.

    • Manual method: You can download a specific version of the driver package.

    One-click script installation

    1. Run the following command to download the latest stable version of the driver package.

      curl -O http://mirrors.cloud.aliyuncs.com/erdma/env_setup.sh
    2. Run the following command to install the downloaded driver package.

      sudo /bin/bash env_setup.sh > /var/log/erdma_install.log 2>&1

      After you run the installation script, the script automatically installs the required software dependencies and the eRDMA driver. Wait for the installation to complete.

      Note

      If the driver installation script fails, check the installation log at /var/log/erdma_install.log.

    Manual installation

    1. Run the following command to update prerequisite packages.

      • Alibaba Cloud Linux 3, CentOS, or Anolis OS:

        sudo yum update -y
      • Ubuntu: No update is required. Skip this step.

    2. Run the following commands in sequence to check the latest kernel package version and the running kernel version.

      rpm -qa | grep kernel  # View the latest kernel package version.
      uname -r  # View the running kernel version of the operating system.

      If the versions are the same, as shown in the following sample output, no further action is required. If the versions are different, you must restart the instance for the changes to take effect.

      image.png

    3. Run the following command to install the dependency packages.

      • For x86 instances, perform the following operations:

        • Alibaba Cloud Linux 3, CentOS, or Anolis OS:

          sudo yum install gcc-c++ dkms cmake kernel-devel kernel-headers libnl3 libnl3-devel
        • Ubuntu:

          sudo apt-get install dkms cmake libnl-3-dev libnl-route-3-dev linux-headers-generic
      • For Arm instances, which require source-based build tasks, the dependency packages are numerous and may change. Therefore, you can skip this step and directly run the installation script. If the installation script fails, it will prompt you to install the necessary dependency packages. Install them as prompted, and then run the installation script again.

    4. Run the following command to download the driver installation package.

      • Obtain the package from an internal URL:

        wget http://mirrors.cloud.aliyuncs.com/erdma/erdma_installer-latest.tar.gz
      • Obtain the package from a public URL:

        wget https://mirrors.aliyun.com/erdma/erdma_installer-latest.tar.gz

      By default, the latest version of the driver installation package is downloaded. You can also download a specific version based on your requirements. For more information about the release information of different eRDMA installer package versions, see Step 2: Install the eRDMA driver for an ECS instance.

    5. Run the following command to decompress the installation package and enter the file directory.

      tar -xvf erdma_installer-latest.tar.gz && cd erdma_installer
    6. Run the following command to install the driver.

      • Method 1: Manually confirm the uninstallation and automatic download steps during installation.

        sudo sh install.sh
      • Method 2: The installation runs without confirmation.

        sudo sh install.sh  --batch

      Check the output to confirm the installation result.

      If the following information is returned, the driver is successfully installed.

      4.png

      If the following information is returned, the driver installation failed. Follow the instructions in the prompt, and then try to install the driver again.

      5.png

      Note

      If you are using CentOS 7 and a package is missing during driver reinstallation, but you cannot obtain it by using yum, you may need to run the yum install -y epel-release command to install the EPEL repository. You can then obtain the required package.

  4. Bind an ERI to the instance.

    You can bind an ERI to the instance in one of the following ways.

    Note

    To query the maximum number of ERIs for an instance type, call the DescribeInstanceTypes operation and check the EriQuantity parameter. A value of 0 means the instance type does not support ERIs.

    • Create a secondary ENI with the eRDMA interface enabled and bind it to an instance by using an API operation

      Create and bind a secondary ENI by using API operations:

      1. Call an API operation to create an ERI.

        Call the CreateNetworkInterface operation and set NetworkInterfaceTrafficMode to HighPerformance to enable the ERI feature.

        Record the ENI ID returned in the NetworkInterfaceId parameter.

      2. Call AttachNetworkInterface. Set NetworkInterfaceId to the ID from the previous step and InstanceId to the target instance ID to bind the ERI-enabled ENI.

        Important

        If your instance type supports multiple ERIs, specify a different NetworkCardIndex for each ERI when binding them to maximize network bandwidth. This ensures the ERIs are bound to different channels. See Network card indexes.

Test the write latency of eRDMA

You can install perftest on two eRDMA-enabled enterprise-level instances and use ib_write_lat to perform a write latency test. For more information about perftest, see the perftest test suite.

Prerequisites

  1. Prepare two enterprise-level instances configured with eRDMA. One will act as the server and the other as the client.

  2. Ensure that the network configuration is correct and that the two servers can communicate with each other over the internal network. For more information, see Enable internal communication between ECS instances.

Procedure

  1. Remotely connect to each of the two instances.

    For more information, see Connect to a Linux instance by using Workbench.

  2. Ensure that eRDMA is correctly configured on both instances.

    For more information, see Verify the eRDMA configuration.

  3. On both instances, run the following commands to install the perftest tool.

    Install perftest from the official repository (requires a public IP address) or from a YUM/APT repository.

    Official repository

    1. Assign a public IP address to the ECS instance.

    2. Download and install perftest from the official perftest repository.

    YUM or APT repository

    Note

    The perftest versions in software repositories may differ across Linux distributions, causing compatibility issues. Use the same distribution on all communicating instances. If not possible, install from the official repository.

    • Alibaba Cloud Linux 3, CentOS, or Anolis OS

      sudo yum install perftest -y
    • Ubuntu

      sudo apt install perftest -y
  4. Test whether the eRDMA network latency meets expectations.

    1. On the server instance, run the following command to start ib_write_lat as a server and listen for client connections.

      ib_write_lat -R -a -F
      • -R: Specifies that the RDMA Connection Manager (RDMA_CM) is used to establish a connection.

        Important
        • For CPU-based instance types that support eRDMA, the default installation mode for the eRDMA kernel driver is Standard, which supports only the RDMA_CM connection establishment method. For more information, see Connection establishment methods.

        • By default, perftest uses an out-of-band (OOB) connection. When performing a perftest on a CPU-based instance, you can use the -R parameter on both the server and the client to specify the RDMA_CM connection establishment method. Otherwise, an exception may occur when the connection is established.

        • You can also use the command line to make the RDMA_CM and OOB connection methods compatible. For more information, see Change the connection establishment mode of eRDMA to be compatible with bRPC. After you enable compatibility, the -R parameter is no longer required.

      • -a: This option runs tests for all message sizes from 2 to 2^23 bytes. This allows you to test the impact of different message sizes on latency.

      • -F: Forcefully overrides any existing connections. This means that if connections were previously established, using the -F option ignores these connections and forces new connections to be established.

    2. On the client instance, run the following command to start ib_write_lat and connect to the server.

      ib_write_lat -R -a -F <server_ip>

      <server_ip> is the private IP address of the network interface on the server ECS instance that is used for the test and has the ERI feature enabled. To obtain the IP address, see View IP addresses.

    3. View the test results.

      After the client test is complete, ib_write_lat outputs test configuration information, connection information, and performance test results (statistics related to latency, including performance metrics such as minimum, maximum, and average latency).

      image

      Description of the ib_write_lat test result fields

      • #bytes: The size of the message payload used in the test. The size ranges from 2 bytes to 8,388,608 bytes. Different message sizes can help you understand performance under different loads.

      • #iterations: The number of iterations. This value specifies how many times the test for each message size is repeated. A higher number of iterations can provide more stable averages and statistics.

      • t_min[usec]: The minimum latency, in microseconds, recorded across all measurements. This value provides a reference for the best-case network latency.

      • t_max[usec]: The maximum latency in microseconds, representing the highest latency recorded across all measurements. A high maximum latency may indicate certain issues in the network or transient congestion.

      • t_typical[usec]: The typical latency, in microseconds. This value represents the latency commonly observed in a test and is usually the median of all measured values.

      • t_avg[usec]: The average latency of all measurements, in microseconds. This value gives you an overall impression of the network latency.

      • t_stdev[usec]: The standard deviation of latency, in microseconds. This value indicates the degree of variation in latency. A smaller standard deviation means that the latency is more stable, while a larger standard deviation indicates greater fluctuations.

      • 99% percentile[usec]: The 99th percentile latency, in microseconds. This means that 99% of the measured values are lower than this value. These data points can help you understand latency performance in extreme cases.

      • 99.9% percentile[usec]: The 99.9th percentile latency, in microseconds. This indicates that 99.9% of the measured values are lower than this value. These data points help you understand latency performance in extreme cases.

      Analyzing these metrics helps you understand your RDMA network's performance for optimization and troubleshooting. For example, if you notice a sudden increase in latency at a specific message size, you may need to check whether your network configuration or hardware performance meets the requirements. If you see significant latency fluctuations, you may need to investigate network congestion or other instability factors.