When you create an ossfs 2.0 configuration file, you can set various parameters to meet different mount requirements. This lets you mount an OSS bucket as a file system that is customized for specific scenarios and business needs.
Basic configuration items
Category | Configuration item | Required | Description | Default value | Supported versions |
Basic bucket configuration | oss_endpoint | Yes | The endpoint of the bucket. | None | v2.0.0 and later |
oss_bucket | Yes | The name of the bucket. | None | v2.0.0 and later | |
Access credential configuration | oss_access_key_id | Required under certain conditions | The AccessKey ID. This parameter is required for AccessKey authentication. | None | v2.0.0 and later |
oss_access_key_secret | Required under certain conditions | The AccessKey secret. This parameter is required for AccessKey authentication. | None | v2.0.0 and later | |
ram_role | Required under certain conditions | The ECS RAM role. This parameter is required for ECS RAM role authentication. | None | v2.0.2 and later |
Common configuration items
Category | Configuration item | Required | Description | Default value | Supported versions |
Bucket configuration | oss_bucket_prefix | No | Mounts a specified folder in the bucket. | Empty | v2.0.0 and later |
oss_region | No | The region ID of the bucket. This is used for the OSS V4 signature algorithm. If you do not specify this parameter, the OSS V1 signature algorithm is used. | 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 the readdirplus feature. When enabled, the file metadata cache is built synchronously during the readdir operation. This consumes more memory. | true | v2.0.0 and later | |
Log configuration | log_level | No | The log output level. Valid values are info and debug. | info | v2.0.0 and later |
log_dir | No | The directory 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 | Specifies whether to run in the foreground. | false | v2.0.0 and later |
d | No | Specifies whether to run in the foreground and enable fuse debug logs. | 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 | After configuration, the `gid` property of all files and folders under the mount target is changed to the configured value. | The `gid` of the user who performs the mount operation | v2.0.1 and later |
uid | No | After configuration, the `uid` property of all files and folders under the mount target is changed to the configured value. | The `uid` of the user who performs the mount operation | v2.0.1 and later | |
file_mode | No | After configuration, the permission property of all files under the mount target is changed to the configured value. | 0777 | v2.0.1 and later | |
dir_mode | No | After configuration, the permission property of all folders under the mount target is changed to the configured value. | 0777 | v2.0.1 and later | |
allow_other | No | If you set `allow_other` to `true`, non-root users can access files under the mount target. Access is subject to permission verification based on the file's permission properties. | true | v2.0.1 and later |
Advanced configuration
Category | Configuration item | Required | Description | Default value | Supported versions |
Network configuration | bind_ips | No | Binds a specified list of IP addresses as the source IPs for accessing OSS. Use commas to separate the IP addresses. For example, 192.168.0.1,192.168.0.2. Specifying a list of IP addresses lets you control the network interface card (NIC) used to access OSS. This can increase the total throughput capacity in a multi-NIC environment. | Empty | v2.0.3 and later |
Upload configuration | upload_buffer_size | No | The size of the multipart upload buffer, in bytes. This is also the part size. This parameter determines the maximum size of a file that can be written. The maximum size is calculated as `upload_buffer_size` × 10000. | 8388608 | v2.0.0 and later |
upload_concurrency | No | The concurrency for multipart uploads. | 64 | v2.0.0 and later | |
sync_upload | No | When enabled, the system waits for the file to finish uploading before returning from the close operation. | 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 the prefetch chunk, in bytes. | 8388608 | v2.0.0 and later | |
prefetch_chunks | No | The number of chunks to prefetch. If not set, the default value is 3 × `prefetch_concurrency`. If set to -1, the prefetch memory is not limited, and each file handle can acquire enough memory for prefetching. | 0 (automatically configured based on `prefetch_concurrency`) | v2.0.0 and later | |
Memory management configuration | total_mem_limit | No | The total memory usage limit, in bytes. If set, the concurrency for uploads and prefetches is automatically adjusted based on this limit. If you do not configure this option, a memory of For environments with 16 GB of memory or less, the default value of `total_mem_limit` is half of the system memory. For environments with more than 16 GB of memory, there is no limit. | 0 | v2.0.0 and later |
max_inode_cache_count | No | Enables active control over the number of cached metadata entries.
| 0 | v2.0.4 and later | |
File validation/Metadata configuration | enable_crc64 | No | Specifies whether to enable cyclic redundancy check (CRC) for file writes. | true | v2.0.0 and later |
close_to_open | No | Supports close-to-open semantics. When this option is enabled, a GetObjectMeta request is sent to get file information from OSS when a file is opened. This ensures real-time metadata. By default, this option is disabled. When a file is opened, the system decides whether to send a request to OSS for the latest file properties based on the TTL of the file's metadata cache. Enabling this option significantly increases access latency when reading many small files because a request is forcibly sent to OSS every time a file is opened. | false | v2.0.0 and later | |
File operation configuration | rename_dir_limit | No | The maximum total number of descendant files and folders in a source folder for a single rename operation. If the actual number exceeds this limit, the rename operation fails. | 2000000 | v2.0.0 and later |
enable_appendable_object | No | When enabled, the AppendObject operation is used for file writes. This mode lets you read a file while it is being written. | false | v2.0.0 and later | |
Request timeout configuration | oss_request_timeout_ms | No | The timeout period for requests sent to OSS, 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 |
References
For examples of configuration files for common ossfs 2.0 scenarios, see Configure ossfs 2.0.