When you create an ossfs 2.0 configuration file, you can set various parameters to meet your specific mount requirements. This file lets you mount an OSS bucket as a file system in different ways to meet various business needs.
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 |
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. This parameter is required for AccessKey authentication. | None | v2.0.0 and later |
oss_access_key_secret | Conditionally required | The AccessKey secret. This parameter is required for AccessKey authentication. | None | v2.0.0 and later | |
ram_role | Conditionally required | The ECS RAM role. This parameter is 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. This parameter is 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 |
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 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 | 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 | If configured, the GID property of all files and folders under the mount target is set to this value. | The GID of the user who mounts the file system | v2.0.1 and later |
uid | No | If configured, the UID property of all files and folders under the mount target is set to this value. | The UID of the user who mounts the file system | v2.0.1 and later | |
file_mode | No | If configured, the permission property of all files under the mount target is set to this value. | 0777 | v2.0.1 and later | |
dir_mode | No | If configured, the permission property of all folders under the mount target is set to this 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 verified based on file permissions. | true | v2.0.1 and later |
Advanced configuration
Category | Configuration item | Required | Description | Default value | Supported versions |
Network configuration | bind_ips | No | Binds a list of specified IP addresses as the source IPs for accessing OSS. Separate the IP addresses with commas. For example, 192.168.0.1,192.168.0.2. By specifying a list of IP addresses, you can control which network interface card (NIC) is used to access OSS. This can increase the total throughput 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 file size is calculated as `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 | If enabled, the system waits for the file to be completely uploaded before returning when the file is closed. | 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. If not set, the default value is three times the value of `prefetch_concurrency`. If set to -1, prefetch memory is not limited. 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 limit, in bytes. If set, the concurrency for uploads and prefetching is automatically adjusted based on this limit. If you do not configure this option, a buffer 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 verification/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. If you enable this option, 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 metadata cache TTL. If you enable this option, a request is always sent to OSS when a file is opened. This significantly increases access latency when reading many small files. | 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 | If enabled, the AppendObject operation is used for file writes. This mode supports reading a file while it is being written. | false | v2.0.0 and later | |
appendable_object_autoswitch_threshold | No | When `enable_appendable_object` is enabled, non-appendable objects in OSS that are smaller than or equal to this size (in bytes) are automatically converted to appendable objects when data is appended. | 0 | v2.0.5 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 | |
memory_data_cache_size | No | In this mode, a fixed amount of memory is pre-allocated for the read cache. This is mainly used to solve the prefetch amplification issue when reading files concurrently. It can effectively improve performance when loading large models on multiple GPUs. | 0 | v2.0.5 and later |
References
For examples of configuration files for common ossfs 2.0 scenarios, see Configure ossfs 2.0.
For more information, see Mount a bucket to a local file system using ossfs 2.0.