All Products
Search
Document Center

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

Last Updated:Mar 08, 2024

ossfs allows you to mount an Object Storage Service (OSS) bucket to a local directory on a Linux system so that your application can access resources in the bucket as if they were local resources. The mount feature facilitates resource sharing.

Important

The performance and functionality of ossfs are not as good as those of local file systems because data must be synchronized to the cloud over networks. Exercise caution if you use ossfs for applications that have high I/O requirements, such as databases.

How it works

s3fs is a Filesystem in Userspace (FUSE) based file system that allows you to mount an Amazon S3 bucket to a local file system. ossfs is built based on s3fs and incorporates all s3fs features, including:

  • Support for most features described in the Portable Operating System Interface (POSIX) standards, such as file and directory uploads and downloads, and user permissions.

  • Multipart upload and resumable upload for data uploading by default.

  • MD5 verification for data integrity checks.

Runtime environment

ossfs is a FUSE-based file system and works only on FUSE-compatible machines. ossfs provides installer packages for the following systems. To run ossfs in other environments, you need to use the source code to build the required program.

  • Linux

    • CentOS 7.0 or later

    • Ubuntu 14.04 or later

    • Anolis7 or later.

  • FUSE

    • FUSE 2.8.4 or later

      Note

      You can check your FUSE version by run the following command:

      fusermount -V

Limits

ossfs maps a bucket to a local file system. The following limits apply to ossfs:

  • ossfs is not suitable for scenarios that require highly concurrent read and write operations.

  • ossfs does not support hard links.

  • You cannot access unrestored Cold Archive objects, unrestored Deep Cold Archive objects, or unrestored Archive objects in a bucket for which real-time access of Archive objects is disabled.

  • If a bucket is mounted to multiple clients and data is simultaneously written to the mount points, ossfs does not guarantee consistency.

Use ossfs

The following commands are run as the ecs-user user. To run the commands as the root user, remove sudo from the commands.

Download ossfs

The following table provides download links to ossfs installer packages for commonly used Linux distributions. If you want to use ossfs on a different distribution, source code compiling is required. For more information about the URL of the source code and how to compile the source code, visit GitHub.

Linux distribution

Download link

Ubuntu 22.04 (x64)

ossfs_1.91.1_ubuntu22.04_amd64.deb

Ubuntu 20.04 (x64)

ossfs_1.91.1_ubuntu20.04_amd64.deb

Ubuntu 18.04 (x64)

ossfs_1.91.1_ubuntu18.04_amd64.deb

Ubuntu 16.04 (x64)

ossfs_1.91.1_ubuntu16.04_amd64.deb

Ubuntu 14.04 (x64)

ossfs_1.91.1_ubuntu14.04_amd64.deb

CentOS 8.0 (x64)

ossfs_1.91.1_centos8.0_x86_64.rpm

CentOS 7.0 (x64)

ossfs_1.91.1_centos7.0_x86_64.rpm

Anolis8/Alibaba Cloud Linux 3

ossfs_1.91.1_anolisos8.0_x86_64.rpm

Anolis7/Alibaba Cloud Linux 2

ossfs_1.91.1_anolisos7.0_x86_64.rpm

Install and configure ossfs

  1. Install ossfs.

    • Ubuntu

      For example, run the following commands in sequence to install ossfs in Ubuntu 16.04 (x64):

      sudo wget https://gosspublic.alicdn.com/ossfs/ossfs_1.91.1_ubuntu16.04_amd64.deb
      sudo apt-get update
      sudo apt-get install gdebi-core
      sudo gdebi ossfs_1.91.1_ubuntu16.04_amd64.deb
    • CentOS/Anolis

      For example, run the following commands to install ossfs in CentOS 7.0 (x64):

      sudo wget https://gosspublic.alicdn.com/ossfs/ossfs_1.91.1_centos7.0_x86_64.rpm
      sudo yum install ossfs_1.91.1_centos7.0_x86_64.rpm

      If your client uses Yellowdog Updater, Modified (YUM) to install the RPM package, dependencies may fail to be downloaded by using YUM when the client node network environment is not suitable. To resolve this issue, you can use YUM to download the dependencies over the normal network to a node that runs the same operating system version, and then copy the dependencies to the required node. For example, ossfs runs on FUSE 2.8.4 or later. You can run the following command to download the latest version of FUSE from the YUM source to your local device:

      sudo yum install --downloadonly --downloaddir=./ fuse
      Important

      To download other dependencies, replace fuse with the name of the required package.

  2. Add the mime.types file if you want Content-Type and file name extension of the uploaded object match.

    If you do not add the mime.types file, OSS sets Content-Type of the uploaded object to application/octet-stream by default.

    The following examples show how to add the mime.types file.

    • Ubuntu

      Run the following command to add the mime.types file:

      sudo apt-get install mime-support
    • CentOS/Anolis

      Run the following command to add the mime.types file:

      sudo yum install mailcap
  3. Check the FUSE version.

    fusermount -V

Mount a bucket and access data in the bucket

  1. Select the bucket that you want to mount to the local file system.

    Note
    • We recommend that you do not mount an Infrequent Access (IA) bucket or a bucket for which real-time access of Archive objects is enabled. This is because an upload to such a bucket from the local directory may initiate two upload requests, with the first creating a 0-byte object and the second uploading actual data to create the object in the bucket.

      The 0-byte object incurs a fee for 30-day storage of 64 KB in IA or Archive. This causes additional storage costs.

  2. Configure account information that is used to access your bucket.

    Write the following information to the /etc/passwd-ossfs file: the bucket name and the AccessKey pair (AccessKey ID and AccessKey secret) of the RAM user that has access permissions on the bucket. Then, set the permissions of the file to 640.

    sudo sh -c 'echo <BucketName>:<yourAccessKeyId>:<yourAccessKeySecret> > /etc/passwd-ossfs'
    ### Run the following command if you use a root user role:###
    # echo <BucketName>:<yourAccessKeyId>:<yourAccessKeySecret> > /etc/passwd-ossfs
    sudo chmod 640 /etc/passwd-ossfs

    Replace BucketName, yourAccessKeyId, and yourAccessKeySecret with your actual bucket name, AccessKey ID, and AccessKey secret. Example:

    sudo sh -c 'echo bucket-test:LTAIbZcdVCmQ****:MOk8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs'
    sudo chmod 640 /etc/passwd-ossfs
  3. Mount the bucket to the specified directory.

    sudo ossfs <BucketName> <mountfolder> -o url=<Endpoint>

    The following commands mount a bucket named bucket-test in the China (Hangzhou) region to the /tmp/ossfs directory:

    sudo mkdir /tmp/ossfs
    sudo ossfs bucket-test /tmp/ossfs -o url=http://oss-cn-hangzhou-internal.aliyuncs.com
    Important

    If you use ossfs on an Elastic Compute Service (ECS) instance and the bucket to mount resides in the same region as the ECS instance, you can use the internal OSS endpoint for the region. For example, you can change the OSS endpoint to oss-cn-hangzhou-internal.aliyuncs.com in this example to reduce traffic costs. For more information about internal OSS endpoints, see Regions and endpoints.

  4. Read objects in the bucket from the local file system.

    1. Query the list of objects in the bucket.

      sudo ls -lh /tmp/ossfs

      image

      Note

      Metadata-related operations such as list directory involve remote access to OSS and have a certain level of latency.

    2. Copy objects.

      sudo cp /tmp/ossfs/bird.jpeg /root

      The preceding command copies the bird.jpeg object to the /root directory.

    3. Upload an object to the bucket.

      sudo cp /root/forest.jpeg /tmp/ossfs

      The preceding command adds the forest.jpeg file to the local directory where the bucket is mounted.

      image

      Note

      If the upload is interrupted and never resumed, the uploaded portion of the object is stored in the bucket as parts. To avoid additional storage fees, we recommend that you use the following methods to delete parts that you no longer need:

  5. Unmount the bucket if you no longer want to keep the bucket mounted.

    sudo fusermount -u /tmp/ossfs

References

  • For more information about ossfs mount configurations, see Advanced configurations.

  • For more information about options and parameters in ossfs commands, see Common options.

  • For a list of commonly asked questions about ossfs, see FAQ.