Common configuration examples for ossfs 2.0 - Object Storage Service

You may need to mount an Object Storage Service (OSS) bucket for different scenarios. To do this, you can create a specific configuration file for ossfs 2.0 and reference the file when you mount the bucket. This topic describes how to use mount options to generate ossfs 2.0 configuration files for different scenarios.

Create a configuration file

Important

A single 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 name and path for each file. When you mount the buckets, reference the 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 Resource Access Management (RAM) user's AccessKey pair to mount an OSS bucket. 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 lets you use an ECS instance RAM role in the configuration file to configure access credentials.

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

Configuration file format

Format description

-- is the prefix for a mount option. <option> is the name of the mount option. In [=<value>], value is the value of the mount 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 obtain the Endpoint for a bucket, go to the Bucket List page. Select the target bucket. In the navigation pane on the left, click Overview. On the Overview page, find the region in the Access Port section. The following figure shows an example for a bucket in the China (Hangzhou) region.

Open your ossfs 2.0 configuration file, and then configure and save it based on the following examples. All examples use an internal network 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 because high latency and unstable internet connectivity can cause stuttering.

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 on 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 also 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 a specific user. (You can use the id command to get the UID and GID of the 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.