Common configuration examples for ossfs 2.0 - Object Storage Service

To use ossfs for different scenarios, you must create a specific configuration file for each scenario. You can then specify this file when you mount an Object Storage Service (OSS) bucket. This topic describes how to use mount options to generate configuration files for different scenarios.

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 bucket. You can customize the file names and paths. When you mount the buckets, specify their corresponding configuration files.

You can set the file name and path for the ossfs 2.0 configuration file. For example, you can create the /etc/ossfs2.conf file.

sudo touch /etc/ossfs2.conf

Configure access credentials

AccessKey

For ossfs 2.0.1 and later, you can use environment variables to configure the AccessKey pair of a Resource Access Management (RAM) user to mount OSS buckets. This method is more secure and convenient. If you have already configured the AccessKey pair using environment variables, do not set it 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*************************

ECS instance RAM role

ossfs 2.0.2 and later supports specifying an instance RAM role in the configuration file to manage access credentials.

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

External process

ossfs 2.0.5 and later lets you use an external command to start an independent process, which is known as an external process. After the external process is executed, it returns the result to ossfs through standard output.

Important

The command that generates credentials must not be accessible by unauthorized processes or users. Otherwise, a security risk may occur.
The command that generates credentials must not write sensitive information to stderr. This is because the information can be captured or logged, which may expose it to unauthorized users.

The external command can return long-term or temporary credentials in the following formats:

Long-term credentials

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

Temporary credentials

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

The Expiration field is in the ISO 8601 format and is specified in UTC.

The configuration format for an external process is as follows:

--credential_process=user-cmd

You can configure use-cmd based on your scenario. The configuration requirements are as follows:

If a parameter or file name contains spaces, enclose the string in double quotation marks ("").
The program must be specified by its full path, such as /bin/bash, /bin/echo, or /bin/curl.
Do not include environment variables, such as $HOME, in the command.

Common scenarios are as follows:

To use a temporary file named /etc/creds.txt to store credentials, set the command to --credential_process=/bin/cat /etc/creds.txt.
To return access credentials from a custom service, set the command to --credential_process=/bin/curl <Custom Service Endpoint>.

Important

ossfs checks only whether the parameters are valid JSON and contain the required fields. Make sure that the command you configure can output complete and valid access credentials. For example, if you use a temporary file, make sure that updates to the file are atomic. You can also use a mechanism such as flock to ensure mutually exclusive read and write operations.

Configuration file format

Format description

The format is --<option>[=<value>]. -- is the prefix for a mount option. <option> is the option name. [=<value>] is the value of the option. The square brackets ([]) indicate that the value is optional.

--<option>[=<value>]

Configuration example

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName

# The AccessKey ID and AccessKey secret. (Optional) For ossfs 2.0.1 and later, you can configure access credentials using environment variables. You do not need to set them in the configuration file.
--oss_access_key_id=AAAI************
--oss_access_key_secret=AAA8x*************************

Common configuration examples

Note

To view the endpoint for a bucket, go to the Buckets page. Select the target bucket. In the navigation pane on the left, click Overview. On the Overview page, find the region in the Port section. The following figure shows an example for a bucket in the China (Hangzhou) region.

Open your ossfs 2.0 configuration file and configure it based on the following examples. All examples use an internal endpoint in the China (Hangzhou) region. Internal network and OSS accelerator endpoints support mounting only from instances within the same region's Virtual Private Cloud (VPC). This method provides faster and more stable data transmission. Do not use ossfs with a public endpoint. High latency and unstable internet connectivity can cause performance issues.

Mount an entire bucket

You can mount all folders and files in an entire bucket to a local path.

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName

# The 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 folder in a bucket

When you mount a bucket, you can specify a particular folder in the bucket to mount to a local path.

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName

# The path of the OSS folder. (Optional)
--oss_bucket_prefix=folder-test/folder-prefix/

# The 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 bucket and configure a memory limit

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

Important

If you do not configure a memory limit, ossfs 2.0 is optimized for performance by default. It can use up to approximately 8 GB of memory for data read and write operations to achieve the best performance. If you have limited memory resources, configure the total_mem_limit option to prevent out-of-memory (OOM) errors.

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName

# The memory limit parameter, in bytes. (Optional)
--total_mem_limit=4294967296

# The 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 bucket and enable debug logs

When you mount a bucket, you can set the log level to debug and specify a custom path for the logs.

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName

# The path to store logs. (Optional) Make sure the /tmp/log folder exists.
--log_dir=/tmp/log/ossfs2

# The log level. (Optional)
--log_level=debug

# The 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 bucket and configure access permissions

Important

By default, when you use ossfs 2.0 to mount a bucket, all users are granted read and write permissions for all files. If you require stricter permissions, you can use the following configurations. These examples apply only to ossfs 2.0.1 and later.

You can mount all folders in the entire bucket to a local path and restrict read and write access for non-root users.

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName

# Deny access to non-root users (the user who mounts the bucket).
--allow_other=false

# Global folder permission property.
--dir_mode=0755

# Global file permission property.
--file_mode=0644

# The AccessKey ID and AccessKey secret. (Optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

You can mount all folders in the entire bucket to a local path. You can allow only the root user and a specific user to have read and write access. Other users have read-only access.

# The endpoint of the region where the bucket is located.
--oss_endpoint=https://oss-cn-hangzhou-internal.aliyuncs.com

# The bucket name.
--oss_bucket=bucketName
 
# Global folder permission property.
--dir_mode=0755

# Global file permission property.
--file_mode=0644

# The UID and GID of the specified user. You can use the id command to obtain the UID and GID of a user.
--uid=1000
--gid=1000

# The AccessKey ID and AccessKey secret. (Optional for ossfs 2.0.1 and later)
--oss_access_key_id=LTAI******************
--oss_access_key_secret=8CE4**********************

What to do next

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

References

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