ossfs 2.0 mount options configuration reference - Object Storage Service

Configure ossfs 2.0 mount parameters to control how an OSS bucket is mounted as a local file system.

Basic configuration items

Category	Configuration item	Required	Description	Default value	Supported versions
Bucket basic configuration	oss_endpoint	Yes	The endpoint to access the bucket.	None	v2.0.0 and later
Bucket basic configuration	oss_bucket	Yes	The name of the bucket.	None	v2.0.0 and later
Access credential configuration	oss_access_key_id	Conditionally required	The AccessKey ID. Required for AccessKey authentication.	None	v2.0.0 and later
	oss_access_key_secret	Conditionally required	The AccessKey secret. Required for AccessKey authentication.	None	v2.0.0 and later
	ram_role	Conditionally required	The ECS RAM role. Required for ECS RAM role authentication.	None	v2.0.2 and later
	credential_process	Conditionally required	The command to run an external process to obtain access credentials. Required for external process authentication.	None	v2.0.5 and later

Common configuration items

Category	Configuration item	Required	Description	Default value	Supported versions
Bucket configuration	oss_bucket_prefix	No	Mounts a specific folder in the bucket.	Empty	v2.0.0 and later
Bucket configuration	oss_region	No	The region ID of the bucket, used for the OSS V4 signature algorithm. Falls back to V1 if not specified.	Empty	v2.0.0 and later
Cache configuration	attr_timeout	No	The time-to-live (TTL) for file metadata cache, in seconds.	60	v2.0.0 and later
	negative_timeout	No	The TTL for invalid directory entry cache, in seconds.	0	v2.0.0 and later
	readdirplus	No	Enables readdirplus. Builds file metadata cache synchronously during readdir, at the cost of higher memory usage.	true	v2.0.0 and later
	disk_data_cache_dir	No	The path of the local cache directory. Setting a non-empty value enables data caching. For more information, see Local data cache.	Empty	v2.0.8 and later
	disk_data_cache_size	Conditionally required	The maximum cache capacity, aligned to GiB. It cannot exceed the available space of the disk or partition where the cache directory resides. disk_data_cache_dir can be left empty. If disk_data_cache_dir is specified, this parameter must be set to a valid value.	Empty	v2.0.8 and later
	disk_data_cache_io_engine	No	The I/O engine for the disk cache. Valid values: psync and libaio.	psync	v2.0.8 and later
Write mode configuration	temp_dir	No	The path of the local temporary directory. Must be an absolute path. Setting a non-empty value enables random write mode based on a local temporary directory, which supports full POSIX write semantics such as writes at arbitrary offsets and truncation to any size. Leave it empty to disable this feature. For more information, see Configure a local temporary directory to support random writes.	Empty	v2.0.9 and later
	temp_dir_free_bytes	No	The minimum free disk space reserved on the disk where the temporary directory resides, in bytes (supports units such as K, M, and G). When the free disk space drops below this threshold, new writes return ENOSPC. If the free disk space is already below this value when mounting, the mount fails. Minimum value: 64 MiB.	1 GiB	v2.0.9 and later
	random_write_max_file_size	No	The maximum logical size of a single object in random write mode, in bytes (supports units such as K, M, and G). Writes or truncations that exceed this limit return EFBIG. The physical upper bound is the OSS multipart upload capacity (10,000 parts × 5 GiB, about 48.8 TiB).	100 GiB	v2.0.9 and later
Log configuration	log_level	No	The log level. Valid values are info and debug.	info	v2.0.0 and later
	log_dir	No	The folder where log files are stored.	/tmp/ossfs2	v2.0.0 and later
	log_file_max_size	No	The maximum size of a single log file, in bytes.	67108864	v2.0.3 and later
	log_file_max_count	No	The maximum number of log files to retain.	8	v2.0.3 and later
Running mode	f	No	Runs ossfs in the foreground.	false	v2.0.0 and later
Running mode	d	No	Runs ossfs in the foreground with FUSE debug logs enabled.	false	v2.0.0 and later
Mount mode	ro	No	Mounts the file system in read-only mode.	false	v2.0.0 and later
Permission configuration	gid	No	Sets the GID for all files and directories under the mount point.	The GID of the user who mounts the file system	v2.0.1 and later
	uid	No	Sets the UID for all files and directories under the mount point.	The UID of the user who mounts the file system	v2.0.1 and later
	file_mode	No	Sets the permission mode for all files under the mount point.	0777	v2.0.1 and later
	dir_mode	No	Sets the permission mode for all directories under the mount point.	0777	v2.0.1 and later
	allow_other	No	Allows non-root users to access files under the mount point. Access is verified by file permissions.	true	v2.0.1 and later

Note

The gid and uid parameters take effect only at mount time. After the file system is mounted, running chown or chmod on files or directories under the mount point returns success (exit code 0) but does not actually change their UID, GID, or permissions. To change the UID or GID, run fusermount -u <mount point> to unmount the file system, and then run the ossfs2 mount command again with new --uid and --gid values. After remounting, all files under the mount point, including existing files and newly created files, display the new UID and GID.

Advanced configuration

Category	Configuration item	Required	Description	Default value	Supported versions
Network configuration	bind_ips	No	Comma-separated list of source IP addresses for OSS access, such as 192.168.0.1,192.168.0.2. Controls which NIC is used to increase throughput in multi-NIC environments.	Empty	v2.0.3 and later
Network configuration	http_proxy	No	The HTTP proxy server used to forward OSS requests.	Empty	v2.0.8 and later
Upload configuration	upload_buffer_size	No	The multipart upload buffer (part) size in bytes. The maximum writable file size is upload_buffer_size × 10,000.	8388608	v2.0.0 and later
	upload_concurrency	No	The concurrency for multipart uploads.	64	v2.0.0 and later
	sync_upload	No	Waits for the upload to complete before returning on file close.	true	v2.0.0 and later
Download/Prefetch configuration	prefetch_concurrency	No	The global concurrency for download prefetching.	256	v2.0.0 and later
	prefetch_concurrency_per_file	No	The concurrency for download prefetching per file handle.	64	v2.0.0 and later
	prefetch_chunk_size	No	The size of a prefetch chunk, in bytes.	8388608	v2.0.0 and later
	prefetch_chunks	No	The number of prefetch chunks. Defaults to 3× prefetch_concurrency. Set to -1 for unlimited prefetch memory per file handle.	0 (automatically configured based on prefetch_concurrency)	v2.0.0 and later
Memory management configuration	total_mem_limit	No	The total memory limit in bytes. Upload and prefetch concurrency auto-adjusts to this limit. Without this option, read prefetch uses a buffer of `prefetch_chunk_size * prefetch_chunks` and writes use `upload_buffer_size * upload_concurrency`, allocating up to ~8 GB total. Ensure sufficient memory to avoid OOM. Defaults to half of system memory for systems with 16 GB or less. No limit for systems with more than 16 GB.	0	v2.0.0 and later
Memory management configuration	max_inode_cache_count	No	Controls the number of cached metadata entries. 0 (default): No active control. The OS evicts metadata automatically. Positive integer: ossfs 2.0 evicts excess entries when the cache count exceeds this value.	0	v2.0.4 and later
File verification/Metadata configuration	enable_crc64	No	Enables CRC64 verification for file writes.	true	v2.0.0 and later
File verification/Metadata configuration	close_to_open	No	Enables close-to-open semantics. Sends a GetObjectMeta request on file open to ensure real-time metadata. Disabled by default, where file open checks the metadata cache TTL to decide whether to query OSS. Enabling this always queries OSS on file open, which significantly increases latency for many small files.	false	v2.0.0 and later
File operation configuration	rename_dir_limit	No	Maximum number of descendant files and directories in a source folder for a rename operation. Exceeding this limit causes the rename to fail.	2000000	v2.0.0 and later
	enable_appendable_object	No	Uses the AppendObject operation for file writes, enabling concurrent read and write on the same file.	false	v2.0.0 and later
	appendable_object_autoswitch_threshold	No	When enable_appendable_object is enabled, non-appendable objects ≤ this size (in bytes) are automatically converted to appendable objects on append.	0	v2.0.5 and later
	enable_symlink	No	Enables the symlink feature. Symlinks can only be created inside the mount point using relative paths.	false	v2.0.6 and later
Request timeout configuration	oss_request_timeout_ms	No	The timeout for OSS requests, in milliseconds.	60000	v2.0.0 and later
Cache configuration	oss_negative_cache_timeout	No	The TTL for cached OSS 404 request items, in seconds.	0	v2.0.2 and later
	oss_negative_cache_size	No	The number of cached OSS 404 request items.	10000	v2.0.2 and later
	memory_data_cache_size	No	Pre-allocates a fixed read cache to reduce prefetch amplification during concurrent reads. Improves performance for multi-GPU model loading.	0	v2.0.5 and later
	kernel_readdir_cache_timeout	No	TTL for the kernel directory cache, in seconds. Requires Linux kernel 4.20 or later.	0	v2.0.7 and later

References

Configuration file examples for common scenarios: Configure ossfs 2.0.
Mount a bucket to a local file system using ossfs 2.0.