All Products
Search

This Product

    Cloud Parallel File Storage:Mount a CPFS for AI file system on ECS or EGS

    Document Center

    Cloud Parallel File Storage:Mount a CPFS for AI file system on ECS or EGS

    Last Updated:Aug 21, 2026

    ECS and EGS instances access a CPFS for AI file system through a VPC mount target. This approach suits data preprocessing, data migration, and small-scale training, and supports both same-zone and cross-zone access.

    Prerequisites

    • You have created a file system.

    • You have added a VPC mount target for the CPFS file system, and the ECS or EGS instance is in the same VPC as the mount target.

    • Your ECS or EGS instance's operating system must meet the following requirements:

      Operating system

      Support status

      Alibaba Cloud Linux 3 (kernel 5.10.134-13 or later)

      Supported (x86_64, ARM)

      Alibaba Cloud Linux 4 (kernel 6.6.102-5.3 or later)

      Supported (x86_64, ARM)

      Ubuntu 24.04 (kernel 6.8.0-60 or later)

      Supported (x86_64)
      Note

      The latest Alibaba Cloud Linux 3 image available in the ECS console includes the required kernel version by default.

    Mount the file system

    Step 1: Install kmod-fuse

    The Elastic File Client (EFC) requires the enhanced FUSE kernel module. Install it before proceeding.

    Alibaba Cloud Linux 4

    # Download and install the latest fuse kmod RPM package on the instance.
sudo bash -c "yum install -y http://mirrors.cloud.aliyuncs.com/alinux/aiext/2.0/alinux-4/$(uname -m)/Packages/alinux-aiext-repo-2.0-2.0-1.alnx4.noarch.rpm"
sudo bash -c "yum install kmod-fuse-$(uname -r)"

# Unmount fuse ctl if it exists.
sudo umount /sys/fs/fuse/connections

# Unload the old fuse module.
# Note: If the rmmod fuse command reports that the module does not exist, you can proceed to the next step. If it returns a "busy" error, reboot the instance. After the reboot, skip the rmmod and modprobe commands and proceed directly to the version consistency check.
sudo rmmod fuse
lsmod | grep fuse

# Load the new fuse module.
sudo modprobe fuse

# Verify version consistency. A successful command outputs "same" (Consistent).
diff -q <(cat /lib/modules/$(uname -r)/extra/fs/fuse/fuse.srcversion) <(cat /sys/module/fuse/srcversion) >/dev/null && echo "same" || echo "not same"

    Alibaba Cloud Linux 3

    # Install kmod-fuse.
sudo bash -c "yum install -y http://mirrors.cloud.aliyuncs.com/alinux/aiext/0.5/alinux-3/$(uname -m)/Packages/alinux-aiext-repo-0.5-0.5-1.al8.noarch.rpm"
sudo bash -c "yum install -y kmod-fuse-$(uname -r)"

# Unmount fuse ctl if it exists.
sudo umount /sys/fs/fuse/connections

# Unload the old fuse module.
# Note: If the rmmod fuse command reports that the module does not exist, you can proceed to the next step. If it returns a "busy" error, reboot the instance. After the reboot, skip the rmmod and modprobe commands and proceed directly to the version consistency check.
sudo rmmod fuse
lsmod | grep fuse

# Load the new fuse module.
sudo modprobe fuse

# Verify version consistency. A successful command outputs "same" (Consistent).
diff -q <(cat /lib/modules/$(uname -r)/extra/fs/fuse/fuse.srcversion) <(cat /sys/module/fuse/srcversion) >/dev/null && echo "same" || echo "not same"

    Ubuntu 24.04 (x86_64)

    # Add the AIExt deb source.
echo "deb [trusted=yes] http://mirrors.cloud.aliyuncs.com/alinux/aiext/1.0/ubuntu-24.04/x86_64/ /" > /etc/apt/sources.list.d/aliyun-aiext.list
apt update

apt -y install ubuntu-aiext-repo
apt update

# Install kmod-fuse.
apt -y install kmod-fuse=$(uname -r)*

# Disable the built-in fuse module in the Ubuntu kernel to ensure that the kmod-fuse module is loaded.
cp /etc/default/grub /etc/default/grub.bak.$(date +%Y%m%d-%H%M%S)
sed -i 's#^\(GRUB_CMDLINE_LINUX=\".*\)\"#\1 initcall_blacklist=fuse_init\"#g' /etc/default/grub
update-grub

# Reboot the instance for the changes to take effect.
reboot

    Step 2: Install the EFC client

    Note: You must complete Step 1 before you install the EFC client.
    Important

    When the EFC client receives major feature updates or bug fixes, you must upgrade the EFC process on your ECS instance. The upgrade does not cause I/O errors or interruptions, but may produce brief I/O jitter lasting a few seconds. Log on to the instance and run the upgrade script.

    Alibaba Cloud Linux 3/4 (x86_64)

    # Get the region of the current instance.
region=$(curl -s http://100.100.100.200/latest/meta-data/region-id)

# Download the EFC client RPM packages.
wget "https://aliyun-alinas-eac-${region}.oss-${region}-internal.aliyuncs.com/aliyun-alinas-utils-latest.al7.noarch.rpm"
wget "https://aliyun-alinas-eac-${region}.oss-${region}-internal.aliyuncs.com/alinas-efc-latest.x86_64.rpm"

# Install the RPM packages. The two packages have dependencies and must be installed together.
sudo yum install -y ./aliyun-alinas-utils-latest.al7.noarch.rpm ./alinas-efc-latest.x86_64.rpm

# Verify the installation. The output should list two packages.
rpm -qa | grep alinas
    Note: You can ignore any ERROR or WARNING messages that appear during the installation, provided the process completes successfully.

    Alibaba Cloud Linux 3/4 (ARM/aarch64)

    # Set the region. Replace <YOUR-REGION> with your actual region, such as cn-wulanchabu.
region=<YOUR-REGION>

# Download the EFC client RPM packages.
wget "https://aliyun-alinas-eac-${region}.oss-${region}-internal.aliyuncs.com/alinas-efc-latest.aarch64.rpm"
wget "https://aliyun-alinas-eac-${region}.oss-${region}-internal.aliyuncs.com/aliyun-alinas-utils-latest.aarch64.rpm"

# Install the RPM packages.
sudo yum install -y ./aliyun-alinas-utils-latest.aarch64.rpm ./alinas-efc-latest.aarch64.rpm

# Verify the installation.
rpm -qa | grep alinas

    Ubuntu 24.04 (x86_64)

    # Set the region. Replace <YOUR-REGION> with your actual region, such as cn-wulanchabu.
region=<YOUR-REGION>

# Download the EFC client .deb packages.
wget "https://aliyun-alinas-eac-${region}.oss-${region}-internal.aliyuncs.com/alinas-efc-latest.amd64.deb"
wget "https://aliyun-alinas-eac-${region}.oss-${region}-internal.aliyuncs.com/aliyun-alinas-utils-latest.noarch.deb"

# Install the .deb packages.
sudo dpkg -i ./aliyun-alinas-utils-latest.noarch.deb ./alinas-efc-latest.amd64.deb

# Verify the installation.
apt list --installed | grep alinas

    Step 3: Mount the file system

    Manual mount

    # Create a mount directory.
sudo mkdir -p /mnt/cpfs

# Mount the file system.
sudo mount -t alinas -o efc,protocol=efc,net=tcp,fstype=cpfs <mount-target-domain-name>:/ /mnt/cpfs

# Verify the mount.
df -h | grep cpfs

    Parameter descriptions

    Parameter

    Description

    -t alinas

    The file system type.

    -o efc,protocol=efc,net=tcp,fstype=cpfs

    Uses the EFC client, TCP protocol, and CPFS file system type.

    <mount-target-domain-name>

    The domain name of the VPC mount target. You can find this on the Mounting and Using tab in the CPFS console.

    :/

    Mounts the root directory of the file system.

    /mnt/cpfs

    The local mount directory. You can customize this path.

    Auto-mount on startup

    To automatically mount the file system when the instance starts, add the mount configuration to /etc/fstab:

    # Append the following line to /etc/fstab.
# Replace <mount-target-domain-name> with your actual VPC mount target domain name.
# Replace /mnt/cpfs with your actual local mount directory. The directory must exist.
echo "<mount-target-domain-name>:/ /mnt/cpfs alinas _netdev,efc,protocol=efc,net=tcp,fstype=cpfs 0 0" | sudo tee -a /etc/fstab

# Verify the configuration and mount the file system.
sudo mount -a
df -h | grep cpfs
    The _netdev parameter ensures that the system mounts the file system only after the network is ready.

    Step 4: Verify access

    After mounting, verify that you can read from and write to the mount directory:

    # List the files in the directory.
ls /mnt/cpfs

# Write data to a test file.
echo "test" > /mnt/cpfs/test.txt

# Read data from the test file.
cat /mnt/cpfs/test.txt

    Unmount the file system

    1. Confirm that no processes are accessing the mount directory.

      fuser -m /mnt/cpfs

    2. Unmount the file system.

      sudo umount /mnt/cpfs

    3. If you configured auto-mount on startup, remove the corresponding entry from /etc/fstab to prevent the file system from automatically mounting after a reboot.

      sudo vi /etc/fstab
# Find and delete the line that contains the CPFS mount target, for example:
# <mount-target-domain-name>:/ /mnt/cpfs alinas _netdev,efc,protocol=efc,net=tcp,fstype=cpfs 0 0

    Access across availability zones

    ECS and EGS instances can access a CPFS for AI file system across availability zones through a VPC mount target. The mount command is the same for both same-zone and cross-zone access. For VPC access performance details, including same-zone versus cross-zone differences, see product specifications.

    FAQ

    Mount failure: "mount command not found"

    The EFC client is not installed correctly. Follow the instructions in Step 2 to reinstall the EFC client.

    Mount failure: "connection timed out"

    Check the following configurations:

    1. Confirm that the ECS or EGS instance is in the same VPC as the mount target.

    2. Confirm that the security group rules allow the ECS or EGS instance to access the mount target.

    3. Confirm that the status of the VPC mount target is Available.