This topic describes how to configure ossfs.

Prerequisites

ossfs is installed. For more information about how to install ossfs, see Installation.

Configure the account information

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

The default path for the account configuration file is /etc/passwd-ossfs. You can also use the -opasswd_file=passwd-path option to specify a configuration file. In the default path, the permission of a configuration file can be set to 640. In other paths, the permission of a configuration file must be set to 600.
  • An account configuration file can contain records for multiple accounts. Each line indicates the information about one account. When ossfs is used to attach a bucket, ossfs matches the bucket name with the correct account.
    Examples:
    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 attach multiple buckets, you can write the information about all accounts to one account configuration file, or write the information about different accounts to different account configuration files. You can use the -opasswd_file=xxx option to select the account configuration file.
    Examples:
    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 credentials that are obtained from Security Token Service (STS). STS temporary credentials are automatically generated and updated. Applications can obtain the STS temporary 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.

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

  1. Create a RAM role named EcsRamRoleOssTest.
    For more information, see Step 1: Create an instance RAM role.
  2. Grant the RAM role permissions to access OSS resources.
    For more information, see Grant permissions to a RAM role. In this example, the RAM role is granted the AliyunOSSReadOnlyAccess permission. You can specify a custom permission. For more information, see Create a custom policy.
  3. Attach the RAM role to an ECS instance
  4. Use ossfs based on the instance metadata URL.
    1. Log on to the ECS instance.
    2. Use ossfs. Add the -oram_role option.
      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 to which ossfs attaches files 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 attached, but not objects in the directory. To modify the access permission on the objects in the directory, you must run the chmod command. No value is available for this option. To grant 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. Default value: 000. This option is used in the same way as the umask command. For example, you can use the -oallow_other -omp_umask=007 option to set the permission of the mount point to 770, and use the -oallow_other -omp_umask=077 option to set the permission of the mount point to 700.
Examples:
  • Set the permission to 777 to allow access from all users.
    ossfs bucket_name mount_point -ourl=endpoint -oallow_other
  • Set the permission 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
  • When you attach the bucket, specify the user and the user group, and then set the permission to 770 to allow access from users only in the same group.

    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 attach 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

Attach a specific directory

You can use ossfs to specify a prefix. This way, you can attach a specific directory in a bucket to the local file system. Command syntax:
ossfs bucket:/prefix mount_point -ourl=endpoint

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

The following command provides an example on how to attach the folder directory in the bucket-ossfs-test bucket in the China (Hangzhou) region to /tmp/ossfs-folder.
ossfs bucket-ossfs-test:/folder /tmp/ossfs-folder -ourl=http://oss-cn-hangzhou.aliyuncs.com

Attach a directory on startup

  1. Write the bucket name, AccessKey ID, and AccessKey secret to the /etc/passwd-ossfs file, and change the permission on 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 command to the /etc/fstab file:
        ossfs#bucket_name mount_point fuse _netdev,url=url,allow_other 0 0
      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 operations, 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 allow the ossfs script to be executed:
        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 attached to 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 operations, automatic mount on startup is enabled for ossfs.

Start ossfs by using Supervisor

Supervisor is a universal process management program of 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:

Notice The file installation path in the following procedure uses the root user as an example. You must use the actual installation path of your operating environment.
  1. Install Supervisor.
    • CentOS
      yum install supervisor
    • Ubuntu
      sudo apt-get install supervisor
  2. Create an ossfs startup script.
    1. Create the start_ossfs.sh file.
      mkdir /root/ossfs_scripts
      vi /root/ossfs_scripts/start_ossfs.sh
    2. Write the startup script.
      # Remove the mount point.
      fusermount -u /mnt/ossfs
      # Attach the OSS 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 /etc/supervisor/supervisord.conf file. Add the following content to the end of the file:
    [program:ossfs]
    command=bash /root/ossfs_scripts/start_ossfs.sh
    logfile=/var/log/ossfs.log
    log_stdout=true
    log_stderr=true
    logfile_maxbytes=1MB
    logfile_backups=10
  4. Run Supervisor.
    supervisord
  5. Verify whether Supervisor runs properly.
    ps aux | grep supervisor # The Supervisor process is displayed. 
    ps aux | grep ossfs # The ossfs process is displayed. 
    kill -9 ossfs # Terminate the ossfs process. Supervisor restarts ossfs. Do not run the killall command because this command sends the SIGTERM signal to terminate the ossfs process. In this case, Supervisor does not restart ossfs. 
    ps aux | grep ossfs # The ossfs process is displayed. 

Enable debug logging

You may encounter issues when you use ossfs. If issues arise, you must enable the debug logging feature and analyze and locate the issues based on the logs. You can enable debug logging by using one of the following methods:
  • Add the -d -odbglevel=debug -ocurldbg option when you attach 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.

  • Add the -d -odbglevel=debug -ocurldbg -f option when you attach a directory. ossfs displays the logs.