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

Prerequisites

You have installed ossfs 1.0 and configured 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 command.
- bucket_name: The name of the bucket to mount.
- /tmp/ossfs: The local directory to mount the bucket, also known as the mount point.
- -o: A required prefix for mount options.
- url=http://oss-cn-hangzhou.aliyuncs.com: The url mount option specifies the endpoint of the target bucket. The value format is http://endpoint.
  
  To find the endpoint for your bucket, go to the Bucket List page, select your bucket, and then click Overview in the left-side navigation pane. The Port section displays the endpoint. This example uses a bucket in the China (Hangzhou) region.
  
  Other endpoints are available for specific network environments: oss-cn-hangzhou-internal.aliyuncs.com for access from an ECS instance over a classic network or a VPC network (internal), oss-accelerate.aliyuncs.com for the global Transfer Acceleration domain, and cn-hangzhou-internal.oss-data-acc.aliyuncs.com for the OSS Accelerator. Select an endpoint based on your network environment.
- sigv4: Enables V4 signature. Add -osigv4 to your mount command. By default, ossfs uses the V1 signature. If you add this mount option, ossfs sends requests to OSS by using the V4 signature process.
- region=cn-hangzhou: The region ID for the OSS bucket request. Add -oregion=<region_id> when you mount the bucket. The default value is empty. This option is required when using V4 signatures to specify the region for the request.

Basic mounting

Mounting using a configuration file

Create mount directories.

Run the following command to create the empty directories /tmp/ossfs-1 and /tmp/ossfs-2 as mount points for your buckets.
```
mkdir /tmp/ossfs-1 /tmp/ossfs-2
```

Mount example.

Run the following commands to mount bucket-test-1 and bucket-test-2, which are configured in the default configuration file, to the /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 output is as follows.

root@i-xxx:~# ossfs xxx /tmp/ossfs-1 -o url=http://oss-cn-hangzhou.aliyuncs.com -o sigv4 -o region=cn-hangzhou
[NOTICE] OSS signature V1 service will not be available for new uids since March 1st, 2025. It is recommended to mount with OSS signature V4:
    ossfs [oss-bucket] [mount-path] [options] -osigv4 -oregion=[your-region-id]
root@i-xxx:~#
root@i-xxx                :~# df -h /tmp/ossfs-1
Filesystem      Size  Used Avail Use% Mounted on
ossfs            16E     0   16E   0% /tmp/ossfs-1

Mounting using an ECS RAM role

Create a mount directory.

Run the following command to create the empty directory /tmp/ossfs to use as the mount point for your bucket.
```
mkdir /tmp/ossfs
```
Mount example.

Note
When mounting ossfs using an instance metadata URL, only the normal access mode is supported. For more information about metadata access modes, see Instance metadata.

Run the following command to mount a bucket named bucket1 to the local /tmp/ossfs directory.

Note: When you mount a bucket using an ECS RAM role, you must specify the instance metadata URL with the ram_role parameter. The IP address 100.100.100.200 is the default for the Alibaba Cloud ECS instance metadata service and should not be changed. Replace EcsRamRoleOssTest with the name of the role attached to your ECS instance. Do not change any other information.
```
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 output is as follows.

root@xxx         xxx:~# ossfs  xxx  /tmp/ossfs -o url=http://oss-cn-hangzhou.aliyuncs.com -o ram role=http://100.100.100.200/latest/meta-data/ram/security-credentials/xxx  -o sigv4 -o region=cn-hangzhou
[NOTICE] OSS signature V1 service will not be available for new uids since March 1st, 2025. It is recommended to mount with OSS signature V4:
        ossfs [oss-bucket] [mount-path] [options] -osigv4 -oregion=[your-region-id]
root@xxx         xxx:~#
root@xxx         xxx:~# df -h /tmp/ossfs
Filesystem  Size  Used  Avail Use% Mounted on
ossfs       16E   0     16E   0%   /tmp/ossfs

Mounting in specific scenarios

You can mount a specific directory or add mount options. For a list of options, see mount options. Note: Before running the mount command, ensure the local mount directory is empty.

Mounting a specific directory

Run the following command to mount the folder directory in the bucket-ossfs-test bucket 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

Mounting using a specified configuration file

Mount option: Use the passwd_file mount option to specify the path to a non-default ossfs 1.0 configuration file. Set the file's permissions to 600.
Mount example

Run the following command to mount bucket-test-3, which is 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
```

Enabling debug logs when mounting

Mount option: The dbglevel mount option sets the log level. The following log levels are supported: critical, error, warn, info, and debug. The default value is critical. By default, logs are saved to /var/log/messages on CentOS systems and to /var/log/syslog on Ubuntu systems. You can also use the logfile mount option to specify a custom path for the log file.
Mount example 1

Run the following command to mount bucket-ossfs-test-1 to the local /tmp/ossfs-1 directory. In this command, the -d option is added to enable the libfuse debug log, and the dbglevel mount option is used to set the log level to debug.
```
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. The log level is set to debug and the libfuse debug log is enabled. The log messages are printed to the foreground terminal using the -f option.
```
ossfs bucket-ossfs-test-2 /tmp/ossfs-2 -d -o dbglevel=debug -f -o sigv4 -o region=cn-hangzhou
```

Configuring access permissions when mounting

By default, only the user who runs the mount command (the owner) can access the mounted directory. To allow other users to access the mount point, configure the parameters described below when mounting the bucket.

Parameter	Description
allow_other	Allows all users to access the mount point directory itself, but not the files in the directory. You must set permissions for files separately. Use the `chmod` command to change permissions for individual files. To apply uniform permissions to all files, configure the `umask` option.
uid	The UID of the user that owns the directory.
gid	The GID of the group that owns the directory.
umask	Sets the permission mask for files and directories in the mount point. For example, to set the permissions in the mount point to 770, add -o umask=007. To set the permissions 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 grant access to all users. This sets the permissions of the mount directory to 777.
```
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 permissions of the mount directory and the files within it to 770. This allows access only for users in the same group.
```
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 specific user. The www user is used in this example.
```
id www
```
  The command output is as follows.
```
root@iZbp1325rf1sja6ye4kbm2Z:~# id www
uid=xxx(www) gid=xxx(www) groups=xxx(www)
```
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. This configuration grants access only to users in the same group and sets the permissions to 770. The uid and gid are 1000 in this example. Before you run the mount command, replace these values with the uid and gid of the target user.
```
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

Automatic mount on startup

A manually mounted bucket is not automatically remounted on system restart. To enable automatic mounting on startup, follow these steps. Before enabling automatic mounting, ensure the manual mount succeeds. This prevents ECS startup failures. The following method enables automatic mounting after you configure ossfs with an AccessKey pair.

Write the bucket name, AccessKey ID, AccessKey secret, and other information to the /etc/passwd-ossfs file, and set the file permissions to 640.

For more information about the configuration steps, see Configure ossfs 1.0.

Set automatic mounting on startup.

Note

The following examples show how to enable automatic mounting on startup for common distributions and versions. For other distributions and versions, refer to your distribution's documentation.

Mount with fstab

Add the following line 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. Replace `bucket_name` with the name of your bucket.
mount_point	The local mount directory. Replace `mount_point` with the path of your local mount directory.
url=url	The endpoint of the target bucket.
0 0	The file system options.

Save the /etc/fstab file. Run the mount -a -t fuse command. If no error is reported, the configuration is correct.
After the previous step is complete, automatic mounting is enabled on Ubuntu 14.04. For CentOS 6.5, you must also run the following command:
```
chkconfig netfs on
```

Mount with a startup script

Create a file named ossfs in the /etc/init.d/ directory, and copy the following content to the file. Replace the values in the mount command with your target bucket information.

#! /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 new ossfs script:
```
chmod a+x /etc/init.d/ossfs
```
After the command is run, you can try to run the script. If the script content is correct, the OSS bucket is mounted to the specified directory.
Configure the ossfs script to start on boot as a service:
```
chkconfig ossfs on
```
After you perform the preceding steps, ossfs is automatically mounted on startup.

Important

chkconfig does not automatically restart ossfs if it exits unexpectedly. It only ensures that ossfs automatically starts at boot.

Unmount a bucket

To unmount a bucket, run the following command. For example, to unmount the file system mounted at /tmp/ossfs:

umount /tmp/ossfs

FAQ

To mount an OSS bucket on a Windows system, use Cloud Storage Gateway (CSG). For more information, see Use a file gateway in the Alibaba Cloud console and Access an SMB shared directory.
Mounting an OSS bucket from an ECS instance over an internal endpoint incurs no traffic fees. For more information about traffic fees, see Traffic fees.
If your ECS instance and OSS bucket are in different regions and you need to mount the bucket across regions, ensure network connectivity. You can directly use a public endpoint to mount the bucket. You can also enable an ECS instance to access an OSS service in another region over a private network.
If you need to build an IIS website using Cloud Storage Gateway and use OSS for data storage, see Build an IIS website by using Alibaba Cloud Storage Gateway.
If you need to mount an OSS bucket on a Windows operating system, see Rclone.
For more information about issues related to mounting and permissions, see FAQ.