All Products
Search

This Product

    Object Storage Service:Use ossfs to mount an OSS bucket to a Linux system

    Document Center

    Object Storage Service:Use ossfs to mount an OSS bucket to a Linux system

    Last Updated:Mar 20, 2026

    ossfs lets you mount an Object Storage Service (OSS) bucket to a Linux directory. Your applications can then read and write OSS objects using standard file system operations — open, read, write, and list — without any code changes. ossfs translates these operations into OSS API calls automatically.

    When to use ossfs 2.0

    ossfs 2.0 is a good fit if your application:

    • Runs AI training, inference, or autonomous driving simulation workloads

    • Needs high read throughput to large objects stored in OSS

    • Cannot use an OSS SDK or the OSS Connector for AI/ML directly

    ossfs 2.0 is not the right fit if your application:

    • Requires broad POSIX semantics (for example, file locking, hard links, or directory rename) — use ossfs 1.0 instead

    • Does not have high throughput requirements and needs general-purpose file access — ossfs 1.0 is better suited

    If your application can use an OSS SDK or the OSS Connector for AI/ML, prefer those over ossfs for better performance.

    Prerequisites

    Before you begin, ensure that you have:

    Supported operating environments

    ossfs 2.0 uses Filesystem in Userspace (FUSE).

    ArchitectureOperating systemSupported versions
    x86_64CentOSCentOS 7, CentOS 8
    x86_64Alibaba Cloud LinuxAlibaba Cloud Linux 2, Alibaba Cloud Linux 3
    x86_64UbuntuUbuntu 20.04 LTS and later LTS versions
    x86_64DebianDebian 11 and later
    aarch64Alibaba Cloud LinuxAlibaba Cloud Linux 3

    Step 1: Install ossfs 2.0

    Select the instructions for your operating system.

    Alibaba Cloud Linux and CentOS

    x86_64

    1. Download the installation package.

         sudo wget https://gosspublic.alicdn.com/ossfs/ossfs2_2.0.5_linux_x86_64.rpm

    2. Install ossfs 2.0.

         sudo yum install ossfs2_2.0.5_linux_x86_64.rpm -y

    aarch64 (Alibaba Cloud Linux only)

    1. Download the installation package.

         sudo wget https://gosspublic.alicdn.com/ossfs/ossfs2_2.0.5_linux_aarch64.rpm

    2. Install ossfs 2.0.

         sudo yum install ossfs2_2.0.5_linux_aarch64.rpm -y

    Ubuntu

    1. Download the installation package.

         sudo wget https://gosspublic.alicdn.com/ossfs/ossfs2_2.0.5_linux_x86_64.deb

    2. Install ossfs 2.0.

         sudo dpkg -i ossfs2_2.0.5_linux_x86_64.deb

    Verify the installation

    Run the following command on any supported distribution to confirm ossfs 2.0 is installed:

    ossfs2 --version

    Expected output:

    Version ID: 2.0.5
Commit  ID: 08539976558311f7a8f5282c30d94198d48c125c
Build Time: 2025-12-19.01:50:42.UTC
    The ossfs2 executable is installed at /usr/local/bin/ossfs2. If your PATH does not include that directory, run the command using its absolute path: /usr/local/bin/ossfs2.

    Step 2: Configure credentials and bucket settings

    ossfs 2.0 reads its settings from a configuration file. The file stores the bucket name, endpoint, and access mode.

    Get an AccessKey pair

    Create an AccessKey pair for a Resource Access Management (RAM) user that has OSS management permissions.

    To create a RAM user and AccessKey pair quickly with a Resource Orchestration Service (ROS) script:

    1. Open the Create Stack page. In the Security Confirmation section, select the check box, then click Create.

      ROS Create Stack page showing the Security Confirmation section

    2. After the stack is created, copy the AccessKey pair from the Outputs tab.

      ROS stack Outputs tab showing the generated AccessKey pair

    Set credentials as environment variables

    export OSS_ACCESS_KEY_ID=LTAI******************
export OSS_ACCESS_KEY_SECRET=8CE4**********************

    Create the configuration file

    1. Create the configuration file.

         sudo touch /etc/ossfs2.conf

    2. Choose an access mode for your bucket:

      ModeDescriptionWhen to use
      Read-onlyWrite operations are rejectedModel inference or any workload that only reads data
      Read/writeBoth reads and writes are allowedApplications that write output back to OSS

    3. Open /etc/ossfs2.conf and add the bucket settings. Replace the placeholder values with your bucket name and endpoint. Read-only mode:

      To find the endpoint for your bucket, go to the Buckets page, select the bucket, click Overview in the left navigation pane, and look in the Port section. Use an internal or OSS accelerator endpoint rather than a public endpoint — public endpoints introduce higher latency and can cause stuttering. image
         # Endpoint of the region where the bucket is located
   --oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

   # Bucket name
   --oss_bucket=<your-bucket-name>

   # Mount in read-only mode
   --ro=true

      Read/write mode: use the same configuration but omit the --ro=true line.

    Step 3: Mount and access the bucket

    1. Create a mount directory.

         mkdir /tmp/ossfs2-bucket

    2. Mount the bucket.

         ossfs2 mount /tmp/ossfs2-bucket/ -c /etc/ossfs2.conf

    3. Verify the mount. List the objects in the bucket:

         sudo ls -lh /tmp/ossfs2-bucket/

      Terminal output showing files listed in the mounted bucket

    4. When you no longer need the mounted bucket, unmount it.

         sudo umount /tmp/ossfs2-bucket/

    Next steps