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 in Linux.

Prerequisite

Install ossfs 1.0 and configure ossfs 1.0.

Mount command format

Command format: ossfs bucket_name /tmp/ossfs -o url=http://oss-cn-hangzhou.aliyuncs.com -o sigv4 -o region=cn-hangzhou
Parameter description
- ossfs: The ossfs startup program.
- bucket__name: The name of the bucket to be mounted.
- /tmp/ossfs: The local directory to which the target bucket is mounted.
- -o: The prefix parameter for mount options. This parameter is required in the mount command.
- url=http://oss-cn-hangzhou.aliyuncs.com: The url mount option specifies the endpoint of the target bucket. The option value format is http://Endpoint.
  To view the endpoint of the target bucket, go to the Bucket List page, select the target bucket, and then click Overview in the left-side navigation pane. You can view the region of the target bucket in the Access Points section on the Overview page. In this example, a bucket in the China (Hangzhou) region is used.
- sigv4: Controls whether to use V4 signatures. Add -osigv4 when mounting. By default, ossfs uses OSS V1 signatures. After this mount option is added, ossfs uses the OSS V4 signature process to send requests to OSS.
- region=cn-hangzhou: The region identifier for OSS bucket requests. Add -oregion=<region_id> when mounting. The default value is empty. When using V4 signatures, you must add this option as the identifier of the region where the request is initiated.

Basic mounting

Mount using configuration files

Create a mount directory.
Run the following command to create custom empty directories /tmp/ossfs-1 and /tmp/ossfs-2 as mount directories for the target bucket.
```
mkdir /tmp/ossfs-1 /tmp/ossfs-2
```

Run the mount command.

Run the following two commands to mount bucket-test-1 and bucket-test-2 configured in the default configuration file to the local /tmp/ossfs-1 and /tmp/ossfs-2 directories respectively.

ossfs bucket-test-1 /tmp/ossfs-1/ -o url=http://oss-cn-hangzhou.aliyuncs.com -o sigv4 -o region=cn-hangzhou
ossfs bucket-test-2 /tmp/ossfs-2/ -o url=http://oss-cn-hangzhou.aliyuncs.com -o sigv4 -o region=cn-hangzhou

The mount result is shown in the following figure.

Mount using ECS RAM Role

Create a mount directory.
Run the following command to create an empty directory /tmp/ossfs as the mount directory for the target bucket.
```
mkdir /tmp/ossfs
```
Run the mount command.
Note
When using the instance metadata URL to mount ossfs, only normal mode access is supported. For information about metadata access modes, see Metadata access modes.
Run the following command to mount a bucket named bucket1 to the local /tmp/ossfs directory.
Note: When mounting a bucket using the ECS RAM Role method, you need to use the ram_role parameter to specify the instance metadata URL. 100.100.100.200 is the default IP address of the Alibaba Cloud ECS instance metadata service and does not need to be changed. EcsRamRoleOssTest is the name of the role bound to the ECS instance. Please replace it with your target role name. The rest of the information does not need to be changed.
```
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 -o sigv4 -o region=cn-hangzhou
```
The mount result is shown in the following figure.

Scenario-based mounting

You can mount only specific directories when mounting, or add mount options to choose appropriate mount options based on different usage scenarios to complete the bucket mounting. Note: Make sure that the local directory is empty before you run the mount command.

Mount a specific directory

Run the following command to mount the folder directory in bucket-ossfs-test to the local /tmp/ossfs-folder directory.

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

Mount using a specified configuration file

Mount option: The passwd_file mount option is used to specify the path of a non-default ossfs 1.0 configuration file during mounting. The permissions of the specified configuration file must be set to 600.

Mount example

Run the following command to mount bucket-test-3 configured in the specified configuration file to the local /tmp/ossfs-3 directory.

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

Enable debug logs when mounting

Mount option: The dbglevel mount option is used to set the log information level. The supported log information levels are critical, error, warn, info, and debug. The default value is critical. Default log retention path: CentOS systems save logs in /var/log/messages, while Ubuntu systems save logs in /var/log/syslog. You can also specify the target log file path using the logfile mount option.
Mount example 1
Run the following command to mount bucket-ossfs-test-1 to the local /tmp/ossfs-1 directory, enable libfuse debug logs using -d, and set the log information level to debug using the dbglevel mount option.
```
ossfs bucket-ossfs-test-1 /tmp/ossfs-1 -d -o dbglevel=debug -o sigv4 -o region=cn-hangzhou
```
Mount example 2
Run the following command to mount bucket-ossfs-test-2 to the local /tmp/ossfs-2 directory, set the log information level to debug, enable libfuse debug logs, and output the log information to the foreground terminal using the -f mount option.
```
ossfs bucket-ossfs-test-2 /tmp/ossfs-2 -d -o dbglevel=debug -f -o sigv4 -o region=cn-hangzhou
```

Configure access permissions when mounting

By default, the directory to 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 and allow other users or user groups to access the mount point, you can use the following options when you run ossfs:

Mount option	Description
allow_other	Modifies the permissions on the mount point to allow all users to access the directory instead of the objects in the directory. The permissions for files in the directory need to be set separately. Use the `chmod` command to modify permissions for individual files. To set uniform permissions for all files, configure the `umask` option.
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, to set the permissions of files on the mount point to 770, add -o umask=007. To set the permissions of files on the mount point to 700, add -o umask=077.

Mount example 1
Run the following command to mount bucket_name to the local mount_point directory, and use the allow_other mount option to set the mount directory permissions to 777, allowing all users to access it.
```
ossfs bucket_name mount_point -o url=endpoint -o allow_other -o sigv4 -o region=cn-hangzhou
```
Mount example 2
Run the following command to mount bucket_name to the local mount_point directory, and use the umask mount option to set the mount directory and file permissions to 770, allowing only users in the same group to access.
```
ossfs bucket_name mount_point -o url=endpoint -o umask=007 -o sigv4 -o region=cn-hangzhou
```
Mount example 3
1. Run the following command to obtain the UID, GID, and groups of a specified user. In this example, the www user is used.
```
id www
```
  The command output is shown in the following figure.
2. Run the following command to mount bucket_name to the local mount_point directory, and use the uid and gid mount options to specify the user and group, allowing only users in the same group to access with permissions set to 770. The uid and gid information uses 1000 as an example. Replace them with the target user's uid and gid information before executing the mount command.
```
ossfs bucket_name mount_point -o url=endpoint -o allow_other -o uid=1000 -o gid=1000 -o umask=007 -o sigv4 -o region=cn-hangzhou
```

Useful tips

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 mount 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.

Write the bucket name, AccessKey ID, AccessKey secret, and other information to the /etc/passwd-ossfs file, and change the file permissions to 640.
For configuration steps, see Configure ossfs 1.0.

Enable automatic mounting upon startup.

Note

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

Automatic mounting through fstab for Ubuntu 14.04 or later and CentOS 6.5 or later

Add the following command to /etc/fstab:

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

Parameters:

Parameter	Description
bucket_name	The name of the bucket to be mounted. Replace `bucket_name` with your actual OSS bucket name.
mount_point	The local mount directory. Replace `mount_point` with your actual local mount directory path.
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 error is reported, the settings are correct.
After you complete the preceding steps, automatic mounting upon startup is enabled in Ubuntu 14.04. For CentOS 6.5, you must also run the following command:
```
chkconfig netfs on
```

Automatic mounting through startup scripts for CentOS 7.0 or later

Create a file named ossfs in the /etc/init.d/ directory and copy the following content to the new file. In addition, change the information in the mount command to the information about your destination bucket.

#! /bin/bash
#
# ossfs      Automount Aliyun OSS Bucket in the specified direcotry.
#
# chkconfig: 2345 90 10
# description: Activates/Deactivates ossfs configured to start at boot time.

ossfs your_bucket your_mountpoint -ourl=your_url -oallow_other

Grant executable permissions to the newly created 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 OSS bucket is mounted to the specified directory.
Set the ossfs startup script to start automatically with other services:
```
chkconfig ossfs on
```
After you complete the preceding operations, automatic mount on startup is enabled for ossfs.

Important

chkconfig does not automatically restart ossfs if it exits abnormally. It only ensures that ossfs starts automatically when the system boots.

Unmount a bucket

Run the following command to unmount a bucket that is mounted to the local file system. For example, unmount the file system mounted to the /tmp/ossfs path.

umount /tmp/ossfs

FAQ

To mount an OSS bucket in Windows, use Cloud Storage Gateway (CSG). For more information, see Use file gateways in the Alibaba Cloud Management Console and Access SMB shared directories.
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 about traffic fees, 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 access OSS services across regions from an ECS instance over the internal network.
If you want to build an IIS website through Cloud Storage Gateway and use OSS as data storage, see How to build an IIS website by using Alibaba Cloud Storage Gateway.
If you need to mount OSS on a Windows operating system, see Rclone.
For more information about mounting, permissions, and other related issues, see FAQ.