ossfs 2.0 mount options configuration reference-Object Storage Service(OSS)-阿里云帮助中心

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
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

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
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
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.