Advanced ossfs configurations - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to use ossfs to mount an Object Storage Service (OSS) bucket to a local file system on Linux.

Prerequisites

ossfs is installed. For more information, see Install ossfs.

Manually mount a bucket to a local file system

You can use one of the following mount methods:

Use the AccessKey of an Alibaba Cloud account: This method is suitable for scenarios in which you use specific Alibaba Cloud account credentials to facilitate quick configurations.
Use a RAM role of an Elastic Compute Service (ECS) instance: This method is suitable for environments in which you need to improve security and permission management. You can use role-based authorization to manage resource access.

Comparison of the methods

Mount method	AccessKey pair of an Alibaba Cloud account used	A RAM role of an ECS instance used
Advantage	The method is simple, easy to use, and very convenient for a single user or in development stages.	The method enhances security. The AccessKey pair is not directly exposed. Permission management is flexible.
Disadvantage	The AccessKey pair may be leaked, which compromises security.	The configuration is complex. You need to configure the RAM role in the RAM console.

Select an appropriate mount method based on your scenario and security requirements. The following section describes how to use the two methods to mount a bucket to a local file system.

Use the AccessKey pair of an Alibaba Cloud account

When you access a bucket, you must use ossfs to configure the AccessKey pair of an Alibaba Cloud account or a RAM user.

Warning

An Alibaba Cloud account has full permissions on the resources within the account. Leaks of the Alibaba Cloud account AccessKey pair pose critical security threats. Therefore, we recommend that you use the AccessKey pair of a RAM user that is granted the minimum required permissions.

Obtain an AccessKey pair. For information about how to create an AccessKey ID and an AccessKey secret, see Create an AccessKey pair.
Write the bucket name and the corresponding AccessKey pair information to the default configuration file named /etc/passwd-ossfs, and set the file permission to 640.
The format of the configuration file is $bucket_name:$access_key_id:$access_key_secret. The AccessKey pair information is stored in the configuration file, with one piece of information recorded in each line.
```
echo bucket-test-1:AAAI************:AAA8x************************* > /etc/passwd-ossfs
echo bucket-test-2:BBBI************:BBB8x************************* >> /etc/passwd-ossfs
chmod 640 /etc/passwd-ossfs
```
Create a directory and mount a bucket to the directory.
Note
The endpoint is the URL. If the bucket is located in the same region in which the ECS instance that runs the Linux operating system is located, specify the internal endpoint of the region. If you want to mount the bucket to a local system, you must ensure that the network connection is smooth to support access to OSS over the Internet. For more information about how to obtain a URL, see Alibaba Cloud public cloud.
```
mkdir /tmp/ossfs-1 /tmp/ossfs-2
ossfs bucket-test-1 /tmp/ossfs-1 -o url=http://oss-cn-hangzhou.aliyuncs.com
ossfs bucket-test-2 /tmp/ossfs-2 -o url=http://oss-cn-hangzhou.aliyuncs.com
```

Use a RAM role of an ECS instance

You can mount a bucket to a local file system on an ECS instance by using a RAM role attached to the instance. You can attach a RAM role to an ECS instance to access OSS resources from the instance by using temporary access credentials that are obtained from STS. Temporary access credentials are automatically generated and updated. Applications can obtain temporary access credentials by using the instance metadata URL. By using an instance RAM role, you can ensure the security of your AccessKey pair and perform fine-grained permission management. For more information about instance RAM roles, see Instance RAM roles.

This section describes how to mount a bucket by using ossfs based on the EcsRamRoleOssTest RAM role:

Create a RAM role named EcsRamRoleOssTest.
For more information, see Create an instance RAM role and attach the RAM role to an ECS instance.
Grant the RAM role permissions to access OSS resources.
For more information, see Grant permissions to a RAM role. In this example, the AliyunOSSReadOnlyAccess policy is attached to the RAM role. In this case, the RAM role can only read the resources in OSS. In your actual business scenario, you can attach a custom policy to the RAM role. For more information, see Create custom policies.
Attach the RAM role to an ECS instance
For more information, see Attach the instance RAM role to an ECS instance.
Check the status of the RAM role attached to the ECS instance.
In the following example, EcsRamRoleOssTest is the name of the RAM role. Make sure that the name is the same as the name of the created RAM role.
```
curl -o /dev/null -s -w "%{http_code}\n" http://100.100.100.200/latest/meta-data/ram/security-credentials/EcsRamRoleOssTest
```
HTTP status code description:
- 404: The RAM role does not exist or is not attached to the ECS instance. Check the preceding steps.
- 200: The RAM role is attached to the ECS instance and works as expected. Proceed to the next step.
If you want to query the RAM roles that are attached to one or more ECS instances or query information about the ECS instances to which the RAM roles are attached based on the RAM role names, see DescribeInstanceRamRole.
Use ossfs to mount a bucket to the local file system based on the instance metadata URL.
Note
Only Normal mode is supported. For more information, see Instance metadata access modes.
1. Log on to the ECS instance.
2. Include the -oram_role option in the mount operation to mount an OSS bucket.
  The following example describes how to mount a bucket named Bucket1 in the China (Hangzhou) region to the /tmp/ossfs directory. In the command, 100.100.100.200 is the default IP address of the ECS instance metadata service.
```
ossfs bucket1 /tmp/ossfs -o url=http://oss-cn-hangzhou.aliyuncs.com -o ram_role=http://100.100.100.200/latest/meta-data/ram/security-credentials/EcsRamRoleOssTest
```

What to do next

Enable automatic mounting upon startup

After you manually mount a bucket, the bucket is not automatically remounted when the system restarts. If you want the bucket to be automatically mounted after the system restarts, perform the following steps: Before you enable automatic mounting upon startup, make sure that the preceding manual mounting operation is successful. This prevents startup failures of the ECS instance. In the following example, automatic mounting upon startup is enabled after you use the AccessKey pair of the Alibaba Cloud account to mount a bucket to a local file system.

Add information, such as the bucket name, AccessKey ID, and AccessKey secret to the /etc/passwd-ossfs file and set the permissions of the file to 640.
For more information, see Use the AccessKey pair of an Alibaba Cloud account.

Enable automatic mounting upon startup.

Note

The following examples describe how to enable automatic mounting upon startup for common distributions and versions. For other distributions and versions, refer to the relevant documents to enable automatic mount upon startup.

Enable automatic mounting upon startup by using the fstab file for Ubuntu 14.04 or later and CentOS 6.5 or later

Add the following command to the /etc/fstab file:

ossfs#bucket_name mount_point fuse _netdev,url=url,allow_other 0 0

The following table describes the parameters.

Parameter	Description
bucket_name	The name of the bucket to mount.
mount_point	The local directory to which you want to mount the bucket.
url=url	The endpoint of the region in which the bucket is located.
0 0	The options for the file system.

Save the /etc/fstab file. Run the mount -a -t fuse command. If no errors are reported, the settings are correctly configured.
After you complete the preceding steps, automatic mounting upon startup is enabled in Ubuntu 14.04 or later. For CentOS 6.5 or later, you must also run the following command:
```
chkconfig netfs on
```

Enable automatic mounting upon startup by using the script for CentOS 7.0 or later

Create the ossfs file in the /etc/init.d/ directory, and copy the following command to this file. Replace your_xxx with your actual information.
```
ossfs your_bucket your_mountpoint -o url=your_url -o allow_other
```
Run the following command to grant the execute permission to the ossfs script:
```
chmod a+x /etc/init.d/ossfs
```
After the preceding command is run, you can execute the script. If the content of the script is correct, the bucket is mounted to the specified directory.
Run the following command to start the ossfs script as a service which is automatically enabled upon startup:
```
chkconfig ossfs on
```
After you complete the preceding steps, ossfs automatically mounts the bucket upon startup.

Specify multiple configuration files

When you use the AccessKey pair of your Alibaba Cloud account to mount a bucket to a local file system, you can write multiple pieces of information to the default configuration file. You can also specify multiple configuration files. Example:

Obtain an AccessKey pair. For information about how to create an AccessKey ID and an AccessKey secret, see Create an AccessKey pair.

Create configuration files for different buckets and set the file permissions to 600.

echo bucket-test-3:CCCIbZcdVCmQ****:CCC8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs-3
echo bucket-test-4:DDDIbZcdVCmQ****:DDD8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs-4
chmod 600 /etc/passwd-ossfs-3 /etc/passwd-ossfs-4

Create a directory and mount buckets to the directory.

mkdir /tmp/ossfs-3 /tmp/ossfs-4
ossfs bucket-test-3 /tmp/ossfs-3 -o url=http://oss-cn-hangzhou.aliyuncs.com -o passwd_file=/etc/passwd-ossfs-3
ossfs bucket-test-4 /tmp/ossfs-4 -o url=http://oss-cn-hangzhou.aliyuncs.com -o passwd_file=/etc/passwd-ossfs-4

Configure access permissions

By default, the directory on which ossfs mounts the bucket can be accessed only by the owner of the mount point. The owner of the mount point is the user who performs the mount operation. To modify the default permission configurations to allow other users or user groups to access the mount point, you can use the following options when you run ossfs:

Parameter	Description
uid	Specifies the user ID (UID) of the owner of the directory.
gid	Specifies the group ID (GID) of the owner of the directory.
umask	Specifies the permission mask of files and directories on the mount point. For example, you can use -oumask=007 to set the file permissions on the mount point to 770 or use -oumask=077 to set the file permissions on the mount point to 700.

Configuration examples:

Set the file permissions to 777 to allow access from all users.
```
ossfs bucket_name mount_point -o url=endpoint -o allow_other
```
Set the file and directory permissions on the mount point to 770 to allow access only from users in the same group as the owner of the mount point.
```
ossfs bucket_name mount_point -o url=endpoint -o umask=007
```
Specify the user ID and group ID in the mount operation and set the file and directory permissions to 770 to allow access from users in the same group as the specified user.
The user www is used in the example. You can run the id command to obtain the UID and GID of the user, and then specify the uid and gid option when you mount the bucket.
```
id www
uid=1000(www) gid=1000(web) groups=1000(web)
ossfs bucket_name mount_point -o url=endpoint -o allow_other -o uid=1000 -o gid=1000 -o umask=007
```

Mount a directory in a bucket to a local file system

In addition to mounting an entire bucket to a local file system, you can mount a directory in the bucket to a local file system by specifying a prefix: Command syntax:

ossfs bucket:/prefix mount_point -o url=endpoint

In this case, you must have the permissions to access the objects in the specified ${prefix}/ path in the bucket.

The following sample command provides an example on how to mount the folder directory of the bucket-ossfs-test bucket in the China (Hangzhou) region to a local directory named /tmp/ossfs-folder:

ossfs bucket-ossfs-test:/folder /tmp/ossfs-folder -o url=http://oss-cn-hangzhou.aliyuncs.com

Start ossfs by using Supervisor

You can use Supervisor to manage and start ossfs for stable bucket mounting. This way, you can ensure that ossfs runs automatically when the system starts and can automatically restart in abnormal scenarios to ensure high availability and stability.

Important

The following procedure uses the installation path of the user1 user who has sudo permissions. Replace the installation path with your actual installation path.

Run the following command to install Supervisor:
CentOS
```
sudo yum install supervisor
```
Ubuntu
```
sudo apt-get install supervisor
```

Create an ossfs startup script.

Run the following command to create a start_ossfs.sh file:
```
mkdir -p /home/user1/ossfs_scripts
```

Write the startup script.

vi /home/user1/ossfs_scripts/start_ossfs.sh

The following code provides an example of the content of the start_ossfs.sh file:

# Unmount the bucket.
fusermount -u /mnt/ossfs
# Remount the bucket. You must use the -f parameter to run ossfs on the frontend. 
exec ossfs bucket_name mount_point -o url=endpoint -f

Edit the supervisord.conf file.

Centos

sudo vi /etc/supervisord.conf

Ubuntu

sudo vi /etc/supervisor/supervisord.conf

Add the following code to the end of the file:

[program:ossfs]
command=bash /home/user1/ossfs_scripts/start_ossfs.sh
logfile=/var/log/ossfs.log
log_stdout=true
log_stderr=true
logfile_maxbytes=1MB
logfile_backups=10

Run the following command to run Supervisor:
```
supervisord
```
Check whether Supervisor runs as expected.
1. Run the following command to check the Supervisor process:
```
ps aux | grep supervisor
```
2. Run the following command to check the ossfs process:
```
ps aux | grep ossfs
```
  The following figure shows sample output, 2044 and 2452 are the process IDs of ossfs.
3. Run the following command to shut down the ossfs process:
  Important
  Do not use the killall command. If you run the killall command, the command sends the SIGTERM signal to stop the ossfs process. In this case, Supervisor does not restart the ossfs process.
```
kill -9 processID
```
  After the ossfs process is shut down, Supervisor restarts the ossfs process.
4. Run the following command to check the ossfs process:
```
ps aux | grep ossfs
```

Enable debug logging

You may encounter issues when you use ossfs. To help analyze and identify issues, you can enable the log debugging feature. You can enable log debugging by using one of the following methods:

Specify the -d -odbglevel=debug -ocurldbg option when you mount a bucket to a local directory. ossfs writes the logs to the system logs.
- CentOS
  Logs are stored in /var/log/messages.
- Ubuntu
  Logs are stored in /var/log/syslog.
Specify the -d -o dbglevel=debug -f option when you mount a bucket to the local directory. ossfs displays the logs on the screen.

Unmount a bucket

Run the umount [mount point path] command to unmount a bucket that is mounted to a local file system. For example, run the following command to unmount a bucket that is mounted to /tmp/ossfs.

umount /tmp/ossfs

References

You are not charged traffic fees when you use a RAM role of an ECS instance to mount a bucket to a local file system by using an internal endpoint. For more information, see Traffic fees.
If your ECS instance and bucket are not located in the same region and you want to mount a bucket to a local file system across regions, make sure that the network is stable. You can use a public endpoint to mount the bucket to the local file system. In addition, you can Use Enterprise Edition transit routers to enable ECS instances to access OSS across regions over VPC connections.
For more information about how to build an Internet Information Services (IIS)-hosted website by using Cloud Storage Gateway (CSG) and store data in OSS, see Build an IIS-hosted website based on CSG.
For more information about how to mount a bucket to a local file system that runs Windows, see Rclone.
For more information about mounting and permissions, see FAQ.