All Products
Search

This Product

    Cloud Parallel File Storage:Mount a file system on a CPFS-POSIX client (Ubuntu/CentOS)

    Document Center

    Cloud Parallel File Storage:Mount a file system on a CPFS-POSIX client (Ubuntu/CentOS)

    Last Updated:Apr 27, 2026

    Install a CPFS-POSIX client and mount a Cloud Parallel File Storage (CPFS) file system on Ubuntu or CentOS.

    Prerequisites

    • A CPFS file system has been created. For more information, see Create a file system.

    • A POSIX mount target has been added to the file system. For more information, see Add a POSIX client mount target.

    • One or more Elastic Compute Service (ECS) instances running Ubuntu or CentOS have been created, with at least 2 CPU cores and 4 GiB of memory. The kernel version must match a supported version in the following table. For more information, see Create an ECS instance.

      Operating system type

      Distribution

      Kernel version

      RHEL or CentOS

      8.4

      4.18.0-305.19.1.el8_4

      8.3

      4.18.0-240.22.1.el8_3

      8.2

      4.18.0-193.28.1.el8_2

      8.1

      4.18.0-147.8.1.el8_1

      8.0

      4.18.0-80.11.2.el8_0

      7.9

      3.10.0-1160.42.2.el7

      7.8

      3.10.0-1127.19.1.el7

      7.7

      3.10.0-1062.18.1.el7

      7.6

      3.10.0-957.54.1.el7

      7.5

      3.10.0-862.14.4.el7

      7.4

      3.10.0-693.2.2.el7

      7.3

      3.10.0-514.26.2.el7

      7.2

      3.10.0-514.26.2.el7

      Ubuntu

      20.04.3 LTS

      5.4.0-86-generic

      Important

      • If your kernel version is not in the supported list, use a CPFS-NFS client instead. For more information, see Mount a file system on a CPFS-NFS client (Recommended).

      • CentOS Linux has reached end of life (EOL). Alibaba Cloud will no longer provide support for CentOS Linux public images. To prevent business interruptions, migrate to a supported operating system. For more information, see Operating system migration.

    How CPFS-POSIX mounting works

    • In this topic, the destination ECS instances refer to the compute nodes on which you mount and access the CPFS file system.

    • CPFS supports POSIX-based APIs. To access CPFS through POSIX, install a CPFS-POSIX client on Ubuntu or CentOS and mount the file system. To access CPFS through NFS instead, see Mount a file system on a CPFS-NFS client (Recommended).

    • After you add a POSIX mount target, CPFS automatically creates three control plane node ECS instances: <FSID>-<GENID>-qr-001, <FSID>-<GENID>-qr-002, and <FSID>-<GENID>-qr-003. The first instance in the list (<FSID>-<GENID>-qr-001) is the default node for installing the CPFS-POSIX client.

    Step 1: Prepare the environment

    Install the required kernel packages on each destination ECS instance before deploying the CPFS-POSIX client.

    Ubuntu

    1. Check your kernel version:

      uname -r

      Compare the output to the supported versions in the prerequisites table. If your kernel version is not in the list, update the kernel to a supported version before continuing. If no supported version is available for your distribution, use a CPFS-NFS client instead. For more information, see Mount a file system on a CPFS-NFS client (Recommended).

    2. Install the software dependencies:

      apt-get -y install linux-headers-`uname -r` cpp gcc binutils

      If the message Unable to locate packages linux-headers appears, the apt source does not have the required linux-headers package. Download and install the package from the official Ubuntu website.

    3. Verify that the linux-headers package version matches the kernel version:

      dpkg -l | grep linux-headers-`uname -r`

    CentOS

    1. Install the software dependencies:

      yum -y install kernel-devel-`uname -r` cpp gcc gcc-c++ binutils

      If the message No package kernel-devel available appears, the Yellowdog Updater, Modified (YUM) source does not have the required kernel-devel package. Run uname -r to check the current kernel version, then download and install the matching kernel-devel package from the official CentOS website.

    2. Check your kernel version:

      uname -r

    3. Verify that the kernel-devel package version matches the kernel version:

      rpm -qa | grep kernel-devel-`uname -r`

    Step 2: Configure the security group

    The CPFS-POSIX client requires network access to the control plane nodes. Add the control plane node security group to each destination ECS instance.

    1. Get the security group ID of the CPFS-POSIX control plane node.

      1. Log on to the NAS console.

      2. In the left navigation pane, choose File System > File System List.

      3. In the upper-left corner, select the resource group and region where the file system resides.

        image

      4. Click the file system to open its details page, then click Mount Targets.

      5. In the Client Management node section, click the ID of the first ECS instance to open its details page.

      6. On the Instance Details page, click the Security Groups tab and note the Security Group ID/Name.

        The control plane node security group name follows the format <FSID>-<GENID>-qr-sg, where <FSID> is the file system ID and <GENID> is the mount target serial number.

    2. Add the control plane node security group to each destination ECS instance.

      1. In the left navigation pane, choose Instances & Images > Instances.

      2. On the Instances page, click the ID of the destination ECS instance. Click the Security Groups tab, then click Change Security Group.

      3. In the Change Security Group dialog box, select the control plane node security group (<FSID>-<GENID>-qr-sg) that you noted from the Security Group drop-down list, then click Confirm.

    Step 3: Mount the file system

    1. Connect to the control plane node ECS instance where the CPFS-POSIX client is installed. For connection instructions, see Select a tool to connect to an instance.

      The control plane node is listed in the Client Management node section. The first ECS instance in the list is the default installation node. For more information, see View a POSIX client mount target.

    2. Add the destination ECS instances to the client cluster by running the following command on the control plane node:

      cpfs add <Internal IP address of destination ECS 1> <Internal IP address of destination ECS 2> <Internal IP address of destination ECS 3>

      Example:

      cpfs add 192.168.1.249 192.168.1.250 192.168.1.251

      The cpfs add command installs the CPFS-POSIX client on each specified instance and joins them to the client cluster. Pass internal IP addresses separated by spaces. The command takes approximately 2 minutes per instance — for multiple instances, run it in the background using screen or nohup to avoid connection timeouts. Each instance must have a unique hostname.

      Note

      • Use internal IP addresses, not public IP addresses.

      • Each client must have a unique hostname.

      • Separate multiple internal IP addresses with spaces.

      • The command takes approximately 2 minutes per instance. For multiple instances, run the command in the background using screen or nohup to avoid connection timeouts.

    3. Verify that the destination ECS instances appear in the node list:

      • Run the command:

        mmlscluster

      • Expected output:

         Node  Daemon node name                     IP address  Admin node name                      Designation
---------------------------------------------------------------------------------------------------------
   1   cpfs-001cb78****154e3-000001-qr-001  10.0.2.41   cpfs-001cb78****154e3-000001-qr-001  quorum-manager-perfmon
   2   cpfs-001cb78****154e3-000001-qr-002  10.0.2.43   cpfs-001cb78****154e3-000001-qr-002  quorum-manager-perfmon
   3   cpfs-001cb78****154e3-000001-qr-003  10.0.2.42   cpfs-001cb78****154e3-000001-qr-003  quorum-manager-perfmon
   4   iZbp11iqkys8rl5cwa4****              10.0.2.44   iZbp11iqkys8rl5cwa4****              perfmon

        The destination ECS instances appear as perfmon nodes (node 4 in the example). The three quorum-manager-perfmon nodes are the control plane nodes.

    4. Optional: Query the default mount path.

      After joining the client cluster, the file system is automatically mounted at /cpfs/<FSID serial number>. Run mmlsfs <FSID serial number>-<GENID> -T to confirm the default path.

      • Sample command:

        mmlsfs 001cb78****154e3-000001 -T

      • Expected output:

        flag                value                    description
------------------- ------------------------ -----------------------------------
 -T                 /cpfs/001cb78****154e3-000001 Default mount point

      To access the file system from a custom path, use mount --bind:

      mount --bind /cpfs/001cb78****154e3-000001 /mnt/test

      /cpfs/001cb78****154e3-000001 is the default mount path automatically assigned to the file system. /mnt/test is the custom path you want to use for access. The --bind option remounts an existing directory to a second location, letting you access the same file system from a different path without duplicating data.

      Note

      • Custom mount paths are not supported on the CPFS-POSIX client installation node.

      • Subdirectory mounting is not supported.

      After the file system is mounted, access it the same way you access a local directory.

    FAQ

    For a complete list of FAQs and troubleshooting guidance for CPFS mounting, see Mounting and access FAQ.

    References