ossfs: mounting an Alibaba Cloud OSS bucket with OSSFS2

A file client for object storage, not a filesystem in the usual sense

Alibaba Cloud OSS is an object storage service. Buckets hold objects addressed by key, and the API for them is HTTP, not a filesystem interface. ossfs bridges that gap by mounting a bucket so that ordinary file operations on a local directory turn into object requests.

The project describes OSSFS2 as a high-performance file client for mounting an OSS bucket as a local filesystem, with sequential read and write throughput that is meant to exploit the bandwidth of OSS itself. The implementation language is C++ and the licence is Apache License 2.0.

The audience is stated in the README as applications with high storage performance requirements, specifically AI training, inference, big data processing, autonomous driving and other compute-intensive workloads. What those workloads have in common is described precisely: they involve sequential and random reads, sequential append-only writes, and do not require full POSIX semantics.

That last clause is the whole design brief, and it is where the trade-off lives. The client is built for streaming large objects through a POSIX-shaped interface, not for workloads that assume a real filesystem underneath. Anything that depends on hard links, file locking, atomic rename semantics or careful permission enforcement is asking for guarantees the project does not claim to provide.

The bucket is accessed through the usual OSS endpoint and bucket name, and the mount options are documented separately on the Alibaba Cloud help site, with a local reference available through the mount command's own help output.

Low-Level FUSE, coroutines and CRC64 on writes

Five design choices account for the performance story, and the README lists them.

The first is the filesystem engine. OSSFS2 is redesigned on the libfuse3 Low-Level API rather than the High-Level API, in order to avoid the additional performance and memory overhead the high-level layer adds. That choice puts the burden of handling filesystem semantics on the client, and it is the direct cause of the POSIX limitations that follow from it.

The second is the HTTP client, which is described as high-performance and coroutine-based, built on PhotonLibOS from Alibaba. Coroutines matter here because a FUSE request handler can then wait on network I/O without blocking a thread per request, which is what lets the client keep memory use low under high concurrency.

The third is fine-grained resource control through coroutines, memory pools and the elimination of unnecessary memory copies, which the project links to lower client-side CPU and memory consumption. The fourth is cross-platform CRC64 checksumming on writes for data integrity at low overhead, which matters because a silent corruption in a training dataset is expensive to discover later.

The fifth is pipelined prefetching with sliding windows, aimed at sequential reads where latency can be hidden by requesting ahead. The combination is described in the README as delivering significant performance gains with very low CPU and memory overhead.

The general applicability point is worth stating plainly. Because the tool was designed around embarrassingly parallel access patterns, its behaviour under many small concurrent operations is part of the design intent rather than an accident.

Installing the package and making the first mount

Pre-compiled packages are provided for the common distributions: Alibaba Cloud Linux 2 on x86_64, Alibaba Cloud Linux 3 on x86_64 and aarch64, CentOS 7 and 8 on x86_64, Ubuntu 14.04 or later on x86_64, and Debian 11 or later on x86_64. Packages are downloaded from the releases page.

On Ubuntu the install is a single dpkg command:

sudo dpkg -i <your_ossfs2_package>.deb

On Alibaba Cloud Linux and CentOS it is the rpm equivalent:

sudo yum install <your_ossfs2_package>.rpm -y

After installation you can confirm the binary with ossfs2 --version. Note that the command is ossfs2, not ossfs, which reflects the second generation naming.

Mounting needs valid OSS access credentials, and there are three supported ways to supply them. The first is environment variables, which the documentation strongly recommends:

export OSS_ACCESS_KEY_ID=<your_access_key_id>
export OSS_ACCESS_KEY_SECRET=<your_access_key_secret>
ossfs2 mount /path/to/mount --oss_endpoint=<your_endpoint> --oss_bucket=<your_bucket>

The second is an ECS RAM role, where the credential comes from the instance role rather than from configuration:

ossfs2 mount /path/to/mount --oss_endpoint=<your_endpoint> --oss_bucket=<your_bucket> --ram_role=<your_ecs_ram_role>

The third passes the keys as mount options:

ossfs2 mount /path/to/mount --oss_endpoint=<your_endpoint> --oss_bucket=<your_bucket> \
  --oss_access_key_id=<your_access_key_id> --oss_access_key_secret=<your_access_key_secret>

Once mounted, the bucket behaves like a directory:

ls /path/to/mount
echo "123" > /path/to/mount/test.txt
cat /path/to/mount/test.txt

And when you are done, the mount point is released with umount /path/to/mount. A configuration file is also supported for parameters you would rather not pass on the command line each time.

The OSSFS1 and OSSFS2 split, and where the numbers come from

The main branch now defaults to OSSFS2, and the previous generation has been moved to a separate branch, main-v1, which the README says will continue to receive updates and maintenance. That branch split is the practical upgrade path: existing OSSFS1 deployments stay on main-v1, and new work starts on main with the second generation client.

The README states the gains against OSSFS1 in specific terms. It reports 1800% higher throughput in single-threaded sequential large-file writes of 100 GiB, over 300% higher throughput in sequential large-file reads of the same size with either 1 or 4 threads, and more than 2000% higher throughput in concurrent small-file reads of 128 KiB under 128-thread workloads. The README also notes that all tests use a per-thread-per-file concurrency model, where each thread reads or writes its own independent file.

Those are the project's own figures, and the framing matters when you read them. The comparison is with OSSFS1 rather than with other object storage clients, the workloads are large-file sequential, and the concurrency model is the one where each thread owns a separate file, which is the pattern AI training pipelines actually produce.

For a detailed benchmark report the README points at the Alibaba Cloud performance test page. If your workload is random reads of many small objects or a mixed read-modify-write pattern, the small-file concurrent read figure is the closest proxy, and even then you should measure your own numbers rather than adopt the ratios.

Where the POSIX line is drawn

The limitation is stated once and plainly: OSSFS2 does not support full POSIX semantics, and the README defers to the OSSFS2 Overview page on Alibaba Cloud for the specific list. That deferral is worth noting, because the details are not in the repository.

What the repository does tell you is enough to make a first judgement. The implementation is built on the FUSE Low-Level API, which means the client implements the filesystem behaviour itself rather than delegating it, and a Low-Level implementation that targets object storage will not reproduce every corner of a local filesystem. Applications that open files with unusual sharing modes, rely on advisory locking to coordinate processes, or assume that a rename over an open file behaves a certain way are the likely casualties.

There are also hard platform limits. The source is tested and supported only on Linux with GCC 9 to 13 inclusive, the build requires the static C++ standard library, libstdc++.a, and CMake 3.8 or higher. On aarch64, support is currently available only for Alibaba Cloud Linux 3, and other ARM-based systems are not supported at all.

For the other distributions, the build sequence is straightforward:

git clone https://github.com/aliyun/ossfs.git
cd ossfs
mkdir build && cd build
cmake ..
make -j4
make install

The compiler range is a real constraint for a service you intend to run for years. GCC 13 is a moving target in the sense that distributions will eventually drop it from their default toolchain, and the README does not state a plan for extending the supported range.

Debug logs, mount configuration and day two operations

Two operational details are documented, and both are the kind of thing that is easier to set up front than to add later.

The first is debug logging. Setting the --log_level=debug option enables it, and the logs are written to the /tmp/ossfs2 directory by default. The location can be changed with the --log_dir option, and the README recommends a dedicated log_dir for each process when several OSSFS2 processes are running. That recommendation exists because a shared directory would interleave the output of unrelated mounts and make a post-incident read much harder.

The second is the configuration file. As well as passing parameters on the command line, OSSFS2 supports mounting from a configuration file, with the format documented on the Alibaba Cloud help site. The full set of mount options is available through ossfs2 mount --help.

For troubleshooting beyond that, the project points at the OSSFS2 FAQ, and if the issue persists you can file a report in the GitHub repository or contact the maintainers.

One thing the README does not document is any behaviour around cache invalidation between mounts, credential rotation on a running mount, or what happens to a mount when the endpoint is unreachable. Those are the questions that surface in production, and answering them means going to the FAQ or the maintainers rather than the documentation.

Licence, release cadence and the state of the repository

The project is licensed under the Apache License 2.0, with the terms in the LICENSE file. For an engineer putting an object storage mount into a pipeline, that licence is permissive enough to ship inside a product, and the trademark and patent clauses in Apache 2.0 are the part worth reading if the mount becomes user visible.

The repository is not archived and the last push was on 2026-09-28. Recent releases are v2.0.10 on 2026-09-28, v2.0.9 on 2026-08-18, and v1.91.12 on 2026-08-17, which is the tail of the 1.x line. Two version schemes are visible here, the 1.x series for OSSFS1 and the 2.0 series for OSSFS2, and the presence of a 1.91.x release alongside 2.0.x confirms that the old line was still receiving work at the same time.

The repository layout is compact: a CMakeLists.txt, a cmake directory, a dependencies directory, the src tree, a .clang-format file and the README. The presence of .clang-format tells you formatting is enforced by a tool rather than by convention, which matters if you plan to send patches.

Contributions are handled in the usual GitHub way, with a fork, a feature branch, commits, a push and a pull request, and the README asks that code follow the existing style and include appropriate tests.

The upgrade cost, in short, is not the licence but the semantics. Moving from a local disk to an OSS mount changes what your applications can assume about the filesystem, and that is the thing to test before you move anything.

Editorial conclusion

Adopt OSSFS2 if your workload streams large sequential objects out of Alibaba Cloud OSS or writes append-only data back, and if the applications using the mount can live without full POSIX semantics. Do not adopt it for a database, a build tree that depends on hard links and file locking, or a general purpose shared filesystem, and do not plan around the throughput figures without measuring your own access pattern. Before you deploy it, read the OSSFS2 limitations page for your workload class, confirm your platform is on the supported list, since aarch64 packages exist only for Alibaba Cloud Linux 3, and pick the credential method deliberately, because the documentation recommends ECSRAMRole or environment variables over passing keys on the command line.

Frequently asked questions

Official sources

1. aliyun/ossfs on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases