Configuration
Updated at：2025-11-03
Parameter setting
bosfs supports parameter settings to configure user permissions, storage class, caching, etc. Execute bosfs –h to obtain details of bosfs parameter settings:
| bosfs parameters | Configurations | Note |
|---|---|---|
| -o use_cache, -o bos.fs.cache.base=< your_cache_dir_path > | Specify the cache file location in file cache mode. | This location must not be within the mount target and must be an absolute path. Cached files will be stored in this directory for a long term. |
| -o allow_other -o mount_umask=0000 | Allow other users to access the mount target, and restrict certain permissions via mount_umask. mount_umask has the same meaning as Linux umask. | By default, bosfs only supports the read, write, and execution permissions of the mounting user, i.e., S_IRWXU. |
| -o meta_expires=< integer seconds> | Specify the expiration time of metadata caches. | It does not expire by default. When multiple clients simultaneously access/mount the same bucket, it is recommended that -o meta_expires=0 should be configured to ensure the metadata in bosfs is consistent with that in the BOS server. For details, refer to the Configuration practices section below. |
| -o meta_capacity=< integer number> | Specify the capacity of metadata caches in the memory. Expired caches exceeding capacity will be cleared using LRU. | It is 100,000 by default. Note that after meta cache is used, when the same bucket is read or written at multiple mount targets, file metadata in bosfs may become inconsistent with that in the BOS server. |
| -o meta_strategy=<remote,merge,local> | Specify the meta read policy. Remote: Read from the remote; merge: read from the remote and merge with the local; local: only read local caches. | This parameter shall be used for the meta_expires configuration. |
| -o storage_class=< standard or standard_ia> | Specify the object storage class, including standard storage and infrequent access storage. | The default class is standard storage. |
| -o tmpdir=<your_tmp_dir> | Specify the temporary file location in file mode. | This location must not be within the mount target and must be an absolute path. Temporary files are not stored on disk for long term and are cleared automatically after the file is closed, but sufficient disk space of this directory shall be guaranteed. bosfs uses this mode by default. |
| -o multipart_size=<integer KB,MB> | Specify the part size for concurrent transmission, in KB or MB. | Defaulting to 10 MB |
| -o multipart_threshold=<integer KB,MB> | Specify the file size threshold for enabling three-step upload. If the threshold is exceeded, it will be enabled. | Defaulting to 100 MB |
| -o multipart_parallel=<integer number'> | Limit the upload concurrency of large files. | Configure it based on network bandwidth and other factors, and generally configure it as 10. |
| -o preload_blocks=<integer number,MB> | Specify the number of read-ahead blocks, and the size of single read-ahead data: preload_blocks*1MB | It is 0 by default. For large file downloads (sequential read), configuration is recommended. For random reads, configuration is not recommended. |
| -o connect_timeout=< milliseconds> | Specify the timeout duration for connecting to the BOS server. | It is 1000ms by default. |
| -o client_timeout=< milliseconds> | Specify the timeout duration for data transmission. | It is 1,200,000 s by default. Reconfiguration is recommended for weak networks/public networks. Timeouts trigger retries and this shall be configured based on network conditions. |
| -o rw_strategy=<mem_sequence,mem_random> | Specify read and write policies. mem_sequence: Use memory mode for sequential read/write only (suitable for upload and download scenarios); mem_random: use memory mode for random read/write. | mem_sequence: Support only sequential read/write, and upload/download large files (size >10GB), improving performance and reducing space usage of temporary files in the /tmp directory. |
| -o mem_cache_per_size=< integer MB> | Specify the memory cache size for a single file provided that rw_strategy=mem_sequence/mem_random is configured. | When configuring rw_strategy=mem_random, note that mem_cache_per_size must exceed the maximum size of any file that may be opened. |
| -o mem_cache_limit_size=< integer MB> | Specify the total memory threshold that can be used for file caches in the bosfs process provided that rw_strategy=mem_sequence/mem_random is configured. Exceeding this threshold will cause the tool to automatically switch to the regular file mode. | The total memory threshold that can be used for file caches in the bosfs process = the number of files opened simultaneously * mem_cache_per_size. The default value is the free memory size in the system during the bosfs startup multiplied by 80%. |
| -o logfile=</tmp/bosfs.log> -o loglevel=debug | Enable bosfs logging, and configure the log location as /tmp/bosfs.log. | The default part size is 1GB, and it is recommended that debug logs should be enabled in test environments. |
| -o credentials=/path/credentials | Configure the tool to read AK/SK and other information through the /path/credentials file. This method must be used when the STS permission is exercised. | Specific format: [defaults] bce_access_key_id = xxx bce_secret_access_key = xxx bce_security_token = xxx reload_interval_s=60 |
| FUSE parameters | Configurations | Note |
|---|---|---|
| -o ro | Set to read-only mode to protect the bucket from being written. | This is a standard FUSE option. |
| -o direct_io | It is set to direct_io, and the OS page cache is not used. | It can be set to direct_io provided that rw_strategy=mem_sequence/mem_random is configured, and this is a standard FUSE option. |
Log
Logs are output to stderr by default, and they can be named via -o logfile=xxxx/xxxx.log. When the -d command is executed to enable the debug mode, the output can be redirected to a local file.
Note:
- Avoid specifying the logfile path or redirected file path within the mount target, as this will lead to continuous log flushing into BOS, causing excessive overhead.
- If the foreground operating mode is not specified using
-dor-f, the bosfs process will become a daemon after startup and the working directory will be switched to /. Thus, an absolute path shall be specified for the logfile. Bosfs log files are not split automatically, and users shall manage them with scripts.- After mounting BOS FS, when rsync is used, it is recommended that
-o loglevel=ERRORand--partitial-dir=local pathshould be set. Because rsync generates temporary files that will be saved to the destination location (within bosfs) by default, incurring unnecessary overhead of upload.
Read-only
The -o ro option can be used to set the read-only mode, protecting the bucket from being written. This is a standard FUSE option.
Configuration practices
- Recommended mount parameters for general scenarios (upload or download only, with little or no random read/write):
Plain Text
1bosfs <bos-bucket> <local-mount-dir> -o endpoint=bj.bcebos.com -o ak=xxx -o sk=xxx -o logfile=/tmp/bosfs.log -o loglevel=debug -o meta_expires=0 -o preload_blocks=100 -o bos.sdk.multipart_threshold=100MB -o bos.sdk.multipart_size=10MB -o bos.fs.multipart_parallel=10- meta_expires configuration item of metadata caches
The cache duration for bosfs metadata (file size, last_modify_time, ACL, etc.) is set via this configuration item. Metadata caching improves performance but cannot ensure the data is consistent with that in the BOS server. Common scenarios are as follows:
If -o meta_expires is not configured, metadata caches are used by default with no expiration time. When the cache count reaches meta_capacity, LRU cache release shall be performed.
-o meta_expires=0 indicates that metadata caches are not used. In other words, metadata is fetched from the BOS server each time, which correspondingly reduces performance.
-o meta_expires=3600 means metadata caching is set to 3600 seconds. Locally cached metadata is used within the expiration. Metadata is re-fetched from the BOS server after expiration.
(1) When multiple mount targets/SDKs/other methods are used to update data in the same bucket, configuring -o meta_expires=0 ensures the current mount target always fetches the latest data from the BOS server during reading.
(2) When only this mount target reads or writes the data in the bucket, and no other mount targets read or write the same bucket, this item is not configured for better performance.
(3) When only the bosfs mount target is used for uploading/writing data without downloading/reading data, this item is not configured for better performance. - For file download/upload scenarios (sequential read/write), refer to the following configurations to improve performance.
(1) Enable 100MB read-ahead. When file size exceeds 100MB, enable multipart upload with 10MB part size and a parallelism of 10.
(2) In download scenarios, when file size exceeds 10MB, bosfs will enable parallel downloads by default.
(3) Note: Enabling read-ahead during random read/write will degrade performance.
-o meta_expires=0 -o preload_blocks=100 -o bos.sdk.multipart_threshold=100MB -o bos.sdk.multipart_size=10MB -o bos.fs.multipart_parallel=10 - In scenarios involving one download and multiple reads, the file cache mode can be enabled. Refer to the following configuration to improve performance.
After enabling file cache mode (disabled by default), bosfs will cache files read via bosfs in the bos.fs.cache.base directory on the local machine. When the same file is read subsequently, the local file will be read directly instead of refetching from the BOS server, thus improving performance.
(1) Enable the file cache mode and configure the bosfs cache directory as /tmp/bosfs-cache.
(2) Enable 100MB read-ahead. When file size exceeds 100MB, enable multipart upload with 10MB part size and a parallelism of 10.
(3) In download scenarios, when file size exceeds 10MB, bosfs will enable parallel downloads by default.
-o meta_expires=0 -o use_cache -o bos.fs.cache.base=/tmp/bosfs-cache -o preload_blocks=100 -o bos.sdk.multipart_threshold=100MB -o bos.sdk.multipart_size=10MB -o bos.fs.multipart_parallel=10 - For uploading/downloading large files (file size >10GB), memory mode can be enabled. Refer to the following configuration to improve the overall performance.
(1) Enable memory mode, configure single-file memory cache to 20MB, with a total cache size of 1000MB available for the bosfs process.
① In sequential read/write scenarios, i.e., rw_strategy=mem_sequence is configured, when the cache size in the bosfs process exceeds the configured threshold, it automatically degrades to local file mode.
(2) Enable 20MB read-ahead. Specify the uploaded file size exceed 100MB, enable concurrent multipart upload with 10MB part size and a parallelism of 10.
(3) In download scenarios, when file size exceeds 10MB, bosfs will enable parallel downloads by default.
-o meta_expires=0 -o preload_blocks=20 -o bos.sdk.multipart_threshold=100MB -o bos.sdk.multipart_size=10MB -o bos.fs.multipart_parallel=10 -o mem_cache_per_size=20 -o rw_strategy=mem_sequence -o mem_cache_limit_size=1000 -o direct_io