DocsICP FilingConsole
官方文档
首页

Common configuration examples for ossfs 2.0

更新时间：
复制 MD 格式
产品详情
我的收藏

To mount an Object Storage Service (OSS) bucket, you need a configuration file for your specific scenario. Reference this file when you mount the bucket.

Create a configuration file

Important

Each configuration file can mount only one bucket. To mount multiple buckets, you must create a separate configuration file for each. You can customize the file names and paths.

You can use any name and path for the ossfs 2.0 configuration file. For example, create a file named /etc/ossfs2.conf.

sudo touch /etc/ossfs2.conf

Configure access credentials

AccessKey pair

For ossfs 2.0.1 and later, use environment variables to configure the AccessKey pair of a Resource Access Management (RAM) user to mount an OSS bucket. This method is more secure and convenient. Credentials configured by using environment variables do not need to be specified again in the configuration file.

Environment variables

export OSS_ACCESS_KEY_ID=LTAI******************
export OSS_ACCESS_KEY_SECRET=8CE4**********************

Configuration file

--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
--oss_bucket=bucketName
--oss_access_key_id=AAAI************
--oss_access_key_secret=AAA8x*************************

Instance RAM role

With ossfs 2.0.2 and later, you can configure access credentials by using an instance RAM role in the configuration file.

--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
--oss_bucket=bucketName
--ram_role=EcsRamRoleOssTest

External process

ossfs 2.0.5 and later supports using a command to start an independent external process. This process returns its result to ossfs through standard output.

Important

  • To prevent security risks, ensure that the command used to generate credentials is not accessible to unauthorized processes or users.

  • Make sure that the command that generates credentials does not write any sensitive information to stderr, as this could expose the information to unauthorized users through capture or logging.

Long-term credentials

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk"
}

Temporary credentials

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2025-12-29T07:45:02Z",
  "SecurityToken" : "token"
}

The Expiration field specifies the UTC time in ISO 8601 format.

Use the following format to configure an external process:

--credential_process=user-cmd

Set use-cmd based on your use case. The configuration requirements are as follows:

  • If a parameter or file name contains spaces, enclose the corresponding string in double quotation marks ("").

  • Specify the full path to the executable, such as /bin/bash, /bin/echo, or /bin/curl.

  • Do not include any environment variables in the command, such as $HOME.

Common examples are as follows:

  • To get credentials from a temporary file such as /etc/creds.txt, use the following configuration: --credential_process=/bin/cat /etc/creds.txt.

  • To retrieve access credentials from a custom service, use the following configuration: --credential_process=/bin/curl <custom_service_endpoint>.

Important

ossfs only validates that the parameters are in valid JSON format and include the required fields. Ensure that the command you configure outputs complete and valid access credentials. For example, if you use a temporary file, ensure that file updates are atomic, or use mechanisms such as flock to enforce mutual exclusion for read and write operations.

Configuration file format

Format

The -- prefix denotes a mount option. <option> is the option name, and value in [=<value>] is its corresponding value. The square brackets [] indicate that the value is optional.

--<option>[=<value>]

Example

# Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# AccessKey ID and AccessKey secret. (Optional) For ossfs 2.0.1 and later, you can configure access credentials by using environment variables instead of setting them in the configuration file.
--oss_access_key_id=AAAI************
--oss_access_key_secret=AAA8x*************************

Configuration examples

Note

To view the endpoint of a bucket, go to the Buckets page, select the target bucket, and then click Overview in the left-side navigation pane. The endpoint is displayed in the Port section. The following examples use a bucket in the China (Hangzhou) region.

The endpoints for a bucket in the China (Hangzhou) region are as follows: The public endpoint is oss-cn-hangzhou.aliyuncs.com. The internal endpoint for access from an Elastic Compute Service (ECS) instance in the classic network or a Virtual Private Cloud (VPC) is oss-cn-hangzhou-internal.aliyuncs.com. The transfer acceleration endpoint for global uploads and downloads is oss-accelerate.aliyuncs.com. The OSS accelerator endpoint is cn-hangzhou-internal.oss-data-acc.aliyuncs.com. All endpoints support HTTPS.

Open the ossfs 2.0 configuration file that you created and configure the file based on the following examples. All examples use an internal endpoint in the China (Hangzhou) region. You can use internal endpoints and OSS accelerator endpoints to mount a bucket only from an instance in a Virtual Private Cloud (VPC) within the same region. These endpoints provide faster and more stable data transfers. We do not recommend using ossfs with a public endpoint because high latency and unstable internet connections may cause performance issues.

Mount an entire bucket

Mount all directories and files in a bucket to a local directory.

# Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# AccessKey ID and AccessKey secret (optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

Mount a specific directory

When you mount a bucket, mount only a specific directory in the bucket to a local directory.

# Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# Path of the directory in the OSS bucket (optional)
--oss_bucket_prefix=folder-test/folder-prefix/
# AccessKey ID and AccessKey secret (optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

Mount with a memory limit

When you mount a bucket, you can allocate a specific amount of memory to the ossfs 2.0 process.

Important

By default, ossfs 2.0 is optimized for performance, using up to approximately 8 GB of memory for data reads and writes. If your memory resources are limited, configure the total_mem_limit option to prevent out-of-memory (OOM) issues.

# Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# Memory limit in bytes (optional)
--total_mem_limit=4294967296
# AccessKey ID and AccessKey secret (optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

Mount with debug logging

Set the log level to debug and specify a custom path to store the logs.

# Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# Directory to store logs (optional). Ensure the /tmp/log directory exists.
--log_dir=/tmp/log/ossfs2
# Log level (optional)
--log_level=debug
# AccessKey ID and AccessKey secret (optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

Mount with access permissions

Important

By default, ossfs 2.0 allows all users to read and write all files. If you need stricter permissions, use the following settings. These examples apply only to ossfs 2.0.1 and later.

  • Mount all directories in the bucket to a local directory and deny read and write access for non-root users.

    # Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# Deny access to users other than the mounting user
--allow_other=false
# Global directory permissions
--dir_mode=0755
# Global file permissions
--file_mode=0644
# AccessKey ID and AccessKey secret (optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

  • Mount all directories in the bucket, granting read and write permissions to a specific user (defined by uid and gid) and read-only permissions to others.

    # Endpoint of the region where the bucket is located
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com
# bucket name
--oss_bucket=bucketName
# Global directory permissions
--dir_mode=0755
# Global file permissions
--file_mode=0644
# Specific user UID and GID (use the id command to get the user's UID and GID)
--uid=1000
--gid=1000
# AccessKey ID and AccessKey secret (optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

Next steps

After you install and configure ossfs 2.0, you can mount a bucket to your Linux system. For more information, see Mount a bucket.

Related topics

For more information about ossfs 2.0 mount options, see Mount options.

Previous：Install ossfs 2.0 on LinuxNext：Mount a bucket