All Products
Search

This Product

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

    Document Center

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

    Last Updated:Aug 27, 2026

    Install the CPFS-POSIX client on Ubuntu or CentOS and mount a CPFS file system.

    Prerequisites

    • A file system is created. For more information, see Create a file system.

    • A POSIX mount target is added for the file system. For more information, see Add a POSIX client mount target.

    • One or more ECS instances that run Ubuntu or CentOS are created, with kernel versions that meet the requirements in the following table, and at least 2 CPU cores and 4 GiB of memory. 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 current kernel version is not in the supported list, use the CPFS-NFS client to mount a file system instead. For more information, see Mount a file system via CPFS-NFS client (Recommended).

      • CentOS Linux has announced End of Life (EOL). Alibaba Cloud will stop supporting CentOS Linux public images accordingly. To avoid service interruptions, migrate to a supported operating system as soon as possible. For more information, see OS migration.

    CPFS-POSIX mount principles

    • In this topic, target ECS instance refers to the compute node that mounts and accesses the CPFS file system.

    • CPFS is compatible with the POSIX interface. You can mount and use CPFS after installing the CPFS-POSIX client on Ubuntu or CentOS. To access CPFS over the NFS protocol, see Mount a file system by using the CPFS-NFS client (recommended).

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

    Step 1: Prepare the environment

    Before you deploy the CPFS-POSIX client, install the required kernel packages on each target ECS instance.

    Ubuntu

    1. Install the dependency packages.

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

      If Unable to locate packages linux-headers is returned, the apt source does not contain the linux-headers package for the corresponding version. You can download the package from the Ubuntu official website and install it manually.

    2. Verify that the linux-headers package version matches the kernel version.

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

    CentOS

    1. Install the dependency packages.

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

      If No package kernel-devel available is returned, the corresponding kernel-devel package for your kernel version is missing from the yum source. Run uname -r to confirm the kernel version, then download the corresponding package from CentOS official website and install it manually.

    2. View the current 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 for the target ECS instance

    The CPFS-POSIX client needs network access to the control nodes. Add the security group of the control nodes to each target ECS instance.

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

      1. Log on to the NAS console.

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

      3. In the upper-left corner of the page, select the resource group and region of the target file system.

        image

      4. Click the target file system. On the details page, click Mount Targets.

      5. In the Client Management node section, click the first ECS instance in the list to go to the instance details page.

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

        The security group name of the control node follows this format: <FSID>-<GENID>-qr-sg.

        In this format, <FSID> is the CPFS file system ID and <GENID> is the mount target sequence number, which increments each time a CPFS mount target is created.

    2. Add the security group of the control node to the target ECS instance.

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

      2. On the Instance List page, click the ECS instance ID to be mounted, select the Security Groups tab, and click Change Security Group.

      3. In the Change Security Group dialog box, select the control node security group (<FSID>-<GENID>-qr-sg) recorded in Step 1 from the Security Groups drop-down list, and click OK.

    Step 3: Mount a file system

    1. Connect to the CPFS-POSIX client installation node (the control node). For more information, see Remote connection methods for ECS instances.

      You can view the client management node list in the Client Management node section. The first ECS instance in the list is the default client installation node. For more information, see View a POSIX client mount target.

    2. Run the following command on the control node to add the target ECS instance to the client cluster and install the CPFS-POSIX client.

      cpfs add <Target ECS 1 private IP address> <Target ECS 2 private IP address> <Target ECS 3 private IP address>

      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 the specified instances and adds them to the client cluster. Separate multiple private IP addresses with spaces. Adding each instance takes approximately 2 minutes. When adding multiple instances, we recommend that you run the command in the background by using screen or nohup to avoid interruptions caused by connection timeouts.

      Note

      • Enter the private IP address of the target ECS instance. Do not use the public IP address.

      • The hostname of each client node must be unique.

      • You can add one or more ECS instances at a time. Separate multiple private IP addresses with spaces.

      • Adding each ECS instance takes approximately 2 minutes. When adding multiple instances, we recommend that you run the command in the background by using screen or nohup.

    3. Run the following command to verify that the target ECS instance appears in the node list.

      • Command

        mmlscluster

      • Sample response

         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 target ECS instance appears as a perfmon node (Node 4 in the example). Nodes marked as quorum-manager-perfmon (Nodes 1-3) are control nodes.

    4. Optional:Query the default mount path.

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

      • Command example

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

      • Sample response

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

      To access the file system through a custom path, run the mount --bind command:

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

      In this command, /cpfs/001cb78****154e3-000001 is the default mount path of the file system, and /mnt/test is the custom path. The --bind option maps the mounted directory to a new location without copying data.

      Note

      • The CPFS-POSIX client installation node does not support custom mount paths.

      • Subdirectory mounting is not supported.

      After the file system is mounted, you can access the CPFS file system as you would a local directory.

    FAQ

    For more FAQ and solutions about mounting CPFS, see Mounting and access FAQ.

    Related documentation