All Products
Search
Document Center

Object Storage Service:Advanced configurations

Last Updated:Jan 12, 2024

This topic describes how to configure ossfs.

Prerequisites

ossfs is installed. For more information, see Installation.

Specify account information

When you use ossfs to access Object Storage Service (OSS) buckets, you must specify your account information, including the AccessKey ID and AccessKey secret. The account information must be written to the account configuration file in the $bucket_name:$access_key_id:$access_key_secret format. ossfs obtains the account information from the account configuration file.

Note

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

The default path of the account configuration file is /etc/passwd-ossfs. You can also use the -opasswd_file=passwd-path option to specify a configuration file path. The permissions for the account configuration file in the default path can be 640. The permissions for the account configuration file in a different path must be 600.

  • An account configuration file can contain records for multiple accounts. Each line provides information about one account. When ossfs is used to mount a bucket, ossfs matches the bucket name with the correct account.

    Configuration example:

    echo bucket-test-1:AAAIbZcdVCmQ****:AAA8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs
    echo bucket-test-2:BBBIbZcdVCmQ****:BBB8x0y9hxQ31coh7A5e2MZEUz**** >> /etc/passwd-ossfs
    chmod 640 /etc/passwd-ossfs
    mkdir /tmp/ossfs-1
    mkdir /tmp/ossfs-2
    ossfs bucket-test-1 /tmp/ossfs-1 -ourl=http://oss-cn-hangzhou.aliyuncs.com
    ossfs bucket-test-2 /tmp/ossfs-2 -ourl=http://oss-cn-hangzhou.aliyuncs.com
  • If you want to mount multiple buckets, you can write the information about all the accounts to one account configuration file, or write the information about each account to a separate account configuration file. You can use the -opasswd_file=xxx option to select an account configuration file.

    Configuration example:

    echo bucket-test-3:CCCIbZcdVCmQ****:CCC8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs-3
    chmod 600 /etc/passwd-ossfs-3
    mkdir /tmp/ossfs-3
    ossfs bucket-test-3 /tmp/ossfs-3 -ourl=http://oss-cn-hangzhou.aliyuncs.com -opasswd_file=/etc/passwd-ossfs-3
    echo bucket-test-4:DDDIbZcdVCmQ****:DDD8x0y9hxQ31coh7A5e2MZEUz**** > /etc/passwd-ossfs-4
    chmod 600 /etc/passwd-ossfs-4
    mkdir /tmp/ossfs-4
    ossfs bucket-test-4 /tmp/ossfs-4 -ourl=http://oss-cn-hangzhou.aliyuncs.com -opasswd_file=/etc/passwd-ossfs-4

Use instance RAM roles

In Elastic Compute Service (ECS), you can use ossfs based on instance Resource Access Management (RAM) roles. You can attach a RAM role to an ECS instance to access OSS from the instance by using temporary access credentials that are obtained from Security Token Service (STS). STS temporary access credentials are automatically generated and updated. Applications can obtain STS temporary access credentials by using the instance metadata URL. The RAM role helps protect the security of your AccessKey pair and facilitates fine-grained permission control and management. For more information about instance RAM roles, see Overview.

This section describes how to use ossfs by using the EcsRamRoleOssTest instance RAM role:

  1. Create a RAM role named EcsRamRoleOssTest.

  2. 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 your actual business application, you can grant custom permissions. For more information, see Create custom policies.

  3. Attach the RAM role to the ECS instance.

  4. Use ossfs based on the instance metadata URL.

    1. Log on to the ECS instance.

    2. Use an ossfs command to mount the bucket and include the -oram_role option in the command.

      The bucket named Bucket1 located in the China (Hangzhou) region is used in the following example:

      ossfs bucket1 /tmp/ossfs -ourl=http://oss-cn-hangzhou.aliyuncs.com -oram_role=http://100.100.100.200/latest/meta-data/ram/security-credentials/EcsRamRoleOssTest

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

  • allow_other: authorizes other users to access the directory to which the bucket is mounted, but not the objects in the directory. To modify the access permissions on the objects in the directory, you must run the chmod command. No value is available for this option. To grant the permissions to other users, use the -oallow_other option.
  • uid: specifies the user ID (UID) of the owner of a directory.

  • gid: specifies the group ID (GID) of the owner of a directory.

  • mp_umask: specifies the permission mask set for the mount point. This option takes effect only when the allow_other option is set. The default value is 000. For example, you can use -oallow_other -omp_umask=007 to set the permission of the mount point to 770, or use -oallow_other -omp_umask=077 to set the permission of the mount point to 700.

  • umask: set permissions for files and directories on the mount point. The default value is 000. For example, you can use -oumask=007 to set the permissions of files on the mount point to 770 or use -oumask=077 to set the permissions of files on the mount point to 700.

Configuration example:

  • Set the permissions to 777 to allow access from all users.

    ossfs bucket_name mount_point -ourl=endpoint -oallow_other
  • Set the permissions to 770 to allow access from users only in the same group as the owner of the mount point.

    ossfs bucket_name mount_point -ourl=endpoint -oallow_other -omp_umask=007
  • Set the permissions of files and directories on the mount point to 770 to allow access only by users in the same group as the owner of the mount point.

    ossfs bucket_name mount_point -ourl=endpoint -oumask=007

  • Set the permissions of files and directories on the mount point to 770 to allow access by users in the same group as the owner of the mount point and other groups.

    The user www is used in the example. You can run the id command to obtain the UID or GID of the user, and then specify the uid or gid parameter when you mount the bucket.

    id www
    uid=1000(www) gid=1000(web) groups=1000(web)
    ossfs bucket_name mount_point -ourl=endpoint -oallow_other -ouid=1000 -ogid=1000 -omp_umask=007

Mount a specific directory

You can use ossfs to mount a specific directory in a bucket to the local file system by specifying a prefix. Command syntax:

ossfs bucket:/prefix mount_point -ourl=endpoint

When you run this command, make sure that an ${prefix}/ object exists in the bucket. You can run the stat command of ossutil to check whether such an object exists.

The following command provides an example on how to mount the folder directory in the bucket-ossfs-test bucket in the China (Hangzhou) region on the /tmp/ossfs-folder folder.

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

Automatically mount a directory on startup

  1. Add information such as the bucket name, AccessKey ID, and AccessKey secret to the /etc/passwd-ossfs file and change the permissions for the file to 640.

    For more information, see Installation.

  2. Enable automatic mount on startup.

    Note

    The following examples show how to enable automatic mount on startup for common versions of Ubuntu and CentOS. For other versions, refer to the relevant documents to enable automatic mount on startup.

    • Enable automatic mount on startup by using the fstab file for Ubuntu 14.04 or later and CentOS 6.5 or later

      1. Add the following line to the /etc/fstab file:

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

        bucket_name is the name of the bucket that you want to mount. mount_point is the local directory on which you want to mount the bucket. url is the endpoint for the bucket. 0 0 are options for the file system.

      2. Save the /etc/fstab file. Run the mount -a command. If no errors are reported, the settings are correctly configured.

      3. After you complete the preceding steps, automatic mount on startup is enabled in Ubuntu 14.04. For CentOS 6.5, you must also run the following command:

        chkconfig netfs on
    • Enable automatic mount on startup by using the script for CentOS 7.0 or later

      1. Create the ossfs file in the /etc/init.d/ directory, and copy the content of the template to this file. Replace your_xxx with your actual information.

      2. 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 OSS bucket is mounted on the specified directory.

      3. Run the following command to start the ossfs script as a service which is automatically enabled on startup:

        chkconfig ossfs on
      4. After you complete the preceding steps, ossfs automatically mounts the bucket on startup.

Start ossfs by using Supervisor

Supervisor is a universal process management program that is developed in Python. Supervisor can turn a general command-line process into a background daemon and monitor the process. Supervisor automatically restarts the process when the process stops unexpectedly. Perform the following steps to start ossfs by using Supervisor:

Important

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

  1. Install Supervisor:

    CentOS

    sudo yum install supervisor

    Ubuntu

    sudo apt-get install supervisor
  2. Create an ossfs startup script.

    1. Run the following command to create a start_ossfs.sh file:

      mkdir /home/user1/ossfs_scripts
    2. Write the startup script.

      vi /home/user1/ossfs_scripts/start_ossfs.sh

      The following code is an example of start_ossfs.sh file content.

      # Unmount the bucket.
      fusermount -u /mnt/ossfs
      # Mount the bucket again. You must use the -f parameter to run ossfs on the frontend. 
      exec ossfs bucket_name mount_point -ourl=endpoint -f
  3. Edit the supervisord.conf file.

    Centos

    sudo vi /etc/supervisord.conf

    Ubuntu

    sudo vi /etc/supervisor/supervisord.conf

    Add the following content at 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
  4. Run the following command to run Supervisor:

    supervisord
  5. Check whether Supervisor runs normally.

    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 result is returned. 2044 and 2452 are the process IDs of ossfs.

      Dingtalk_20231225172213.jpg

    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 process ID

      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 locate issues, you can enable the debug logging feature. You can enable debug logging by using one of the following methods:

  • Add the -d -odbglevel=debug -ocurldbg option when you mount a bucket on 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.

  • Add the -d -odbglevel=debug -ocurldbg -f option when you mount a bucket on a local directory. ossfs displays the logs on the screen.