The GooseFS-Lite tool supports mounting Cloud Object Storage (COS) buckets locally, allowing you to directly operate objects in Tencent Cloud Object Storage as if using a local file system. Compared to the COSFS tool, GooseFS-Lite offers higher large file read and write speeds and is not limited by local disk performance. GooseFS-Lite supports major POSIX file system features, such as file order, random read, sequential write, and directory manipulation.
Use Limits
GooseFS-Lite is only suitable for simple management of files after mounting and does not support some features of local file systems. Please note the following usage limits:
Files cannot be written randomly and truncate operations are not supported.
When multiple clients mount the same COS bucket, users need to self-coordinate the behavior of multiple clients, such as avoiding multiple clients writing to the same file.
Rename operations for files/folders are non-atomic.
Reading and renaming files being written in the current mount point are not supported.
Metadata operations like listing directories have poor performance due to the need for remote access to the COS server.
Soft/hard links are not supported.
Append write performance is poor, involving server-side data copy and downloading the appended file.
Not recommended for use in low memory scenarios, such as when container memory or CVM memory is less than 2G.
Container environments are currently only supported within Tencent Kubernetes Engine (TKE). Non-TKE containers are not supported.
Not recommended for use in scenarios with a large amount of random reads and high performance requirements.
Note:
External network mount and append write operations on non-infrequent storage will incur download traffic fees.
Install GooseFS-Lite in the current directory and soft link goosefs-lite to /usr/bin/goosefs-lite for convenient use of the goosefs-lite command.
curl -fssL https://downloads.tencentgoosefs.cn/goosefs-lite/install.sh | sh -x
cd goosefs-lite-*
sudo bash bin/install.sh
Step 3: Installing KonaJDK11
In the goosefs-lite-<specific version> directory (for example, in the goosefs-lite-1.0.6 directory), use the following command to install KonaJDK to /usr/local/konajdk11:
As shown below, there are two options to choose from:
First: Use the download link for konajdk. Second: Download the konajdk installation package to the specified directory. Use the following command to install it, so that goosefs-lite can automatically use this Java runtime environment.
If you want a more flexible way to install the Java environment, refer to manual JDK installation and modify environment variables in conf/goosefs-env.sh to make it effective.
Step 4: Modifying the Configuration File
In the goosefs-lite-<specific version> directory (for example, in the goosefs-lite-1.0.6 directory), there are two ways to modify the configuration file:
Use sed to modify the following three parameters, filling in SECRET_ID, SECRET_KEY, and REGION as needed:
Set fs.cosn.userinfo.secretKey to the Tencent Cloud key.
Set fs.cosn.userinfo.secretId to the Tencent Cloud ID.
Set fs.cosn.bucket.region to the bucket region.
sed -i '/<name>fs.cosn.userinfo.secretId<\\/name>/{N;s/<value>[^<]*<\\/value>/<value>$SECRET_ID<\\/value>/}' conf/core-site.xml
sed -i '/<name>fs.cosn.userinfo.secretKey<\\/name>/{N;s/<value>[^<]*<\\/value>/<value>$SECRET_KEY<\\/value>/}' conf/core-site.xml
sed -i '/<name>fs.cosn.bucket.region<\\/name>/{N;s/<value>[^<]*<\\/value>/<value>$REGION<\\/value>/}' conf/core-site.xml
You can also use vim to edit the conf/core-site.xml file to modify parameters.
Set fs.cosn.userinfo.secretKey to the Tencent Cloud key.
Set fs.cosn.userinfo.secretId to the Tencent Cloud ID.
Set fs.cosn.bucket.region to the bucket region.
Configuration file description
In the goosefs-lite-<specific version>/conf directory (for example, in the goosefs-lite-1.0.6/conf directory), you can see the following files:
acl-site.properties: specify directory permissions, username, group name, similar to Linux Posix semantics 0755, uid, gid, etc.
core-site.xml: Hadoop-COS configuration file (goosefs-lite's data flow is based on Hadoop-COS, so parameters and configuration files are almost universal)
goosefs-env.sh: various environment variables, such as JVM parameters, etc.
log4j.properties: log configuration. To enable debug logging, uncomment the last line of this file and remount.
acl-site.properties: specify directory permissions, username, group name, similar to Linux Posix semantics 0755, uid, gid, etc.
Note:
We recommend that users avoid using permanent keys in the configuration. Configuring sub-account keys or temporary keys can help improve business security. When authorizing a sub-account, grant only the permissions of the operations and resources that the sub-account needs, which helps avoid unexpected data leakage.
If you must use a permanent key, we recommend that you limit ITS permission scope. This can improve the security by limiting its executable operations, resource scope, and conditions (access IP, etc.).
Step 5: Mounting a Bucket to a Local Directory
Execute the following command in the goosefs-lite-<specific version> directory (for example, in the goosefs-lite-1.0.6 directory) to mount the bucket configured in the key file to the specified directory:
<MountPoint> is the local mounting directory (for example, /mnt/goosefs-lite-mnt-dir), which must be empty; otherwise, it cannot be mounted.
<BucketName> is the bucket name (e.g., examplebucket-1250000000).
Example:
mkdir -p /mnt/goosefs-lite-mnt
./bin/goosefs-lite mount /mnt/goosefs-lite-mnt/ cosn://examplebucket-1250000000/
View the local mount point and the corresponding COS bucket. The output information includes the process ID, local mount point, and COS path in sequence:
If you need to specify multiple mount parameters simultaneously in the command line, you can use commas to separate multiple parameters. The following command sets the mount point to read-only and allows other users to access the mount point:
./bin/goosefs-lite mount -o "ro,allow_other" mnt/ cosn://examplebucket-1250000000/
Among them:
-o allow_other: To allow other users to access the mount folder, you can specify this parameter when running GooseFS-Lite.
-o ro: Set the mount point to read-only, disallowing write and delete operations.
Note:
A single parameter can be specified with -o, such as -o ro; multiple parameters can be separated by commas, such as -o "ro,allow_other".
Step 6: Uninstalling the Mount Point
In the goosefs-lite-<specific version> directory (for example, in the goosefs-lite-1.0.6 directory), execute the following command to uninstall the mount point:
$./bin/goosefs-lite umount /mnt/goosefs-lite-mnt
Unmount fuse at /mnt/goosefs-lite-mnt/ (PID: 17206).
# If uninstallation is abnormal, you can force uninstall using the following command
$ sudoumount -l /mnt/goosefs-lite-mnt
Step 7: Parameter Tuning
GooseFS-Lite includes two configuration files: conf/core-site.xml and conf/goosefs-lite.properties.
You can optimize upload and download bandwidth by modifying conf/core-site.xml. Common parameters are as follows, more parameters can be found in the Hadoop-COS documentation.
Attribute Key
Description
Default Value
Required
fs.cosn.useHttps
Configure whether to use HTTPS as the transfer protocol for the COS backend.
true
No
fs.cosn.upload.part.size
The size of each part in the chunked upload. Since COS can only support up to 10,000 parts in a chunked upload, it is necessary to estimate the maximum possible single file size. For example, when the part size is 8MB, a single file with a maximum size of 78GB can be uploaded. The maximum part size can be supported is 2GB, which means a single file can support up to 19TB.
8388608 (8MB)
No
fs.cosn.upload_thread_pool
The number of concurrent threads when files are uploaded to COS through streams.
32
No
fs.cosn.read.ahead.block.size
The size of the pre-read block.
1048576 (1MB)
No
fs.cosn.read.ahead.queue.size
The length of the read-ahead queue.
6
No
fs.cosn.trsf.fs.ofs.tmp.cache.dir
Temporary file directory of Metadata Accelerator bucket.
No
Metadata Accelerator bucket is required
fs.cosn.trsf.fs.ofs.user.appid
Appid of Metadata Accelerator bucket.
No
Metadata Accelerator bucket is required
fs.cosn.trsf.fs.ofs.bucket.region
Region of Metadata Accelerator bucket, such as ap-shanghai, ap-beijing.
No
Metadata Accelerator bucket is required
You can adjust the behavior of GooseFS-Lite by modifying conf/goosefs-lite.properties. Common parameters are as follows:
Attribute
Description
Default Value
Required
goosefs.fuse.list.entries.cache.enabled
Enable client List cache
true
No
goosefs.fuse.list.entries.cache.max.size
Maximum number of entries in client List cache, unit: entries
Time to wait for write operation to complete when files in open and rename operations are being written, unit: ms
5000
No
goosefs.fuse.umount.timeout
Time to wait for incomplete operations when uninstalling the file system, unit: ms
120000
No
When your read and write concurrency is high, you can adjust the maximum JVM runtime memory of GooseFS-Lite as follows to avoid FullGC and OutOfMemoryError. The default JVM values are -Xmx512m -XX:MaxDirectMemorySize=512m -XX:+UseG1GC -XX:G1HeapRegionSize=32m. The adjustment method is as follows:
exportJAVA_OPTS=" -Xms2G -Xmx2G"
./bin/goosefs-lite mount /mnt/goosefs-lite-mnt/ cosn://examplebucket-1250000000/
ps -ef|grep goosefs-lite|grep -v grep
FAQs
Missing libfuse library file, how to handle it?
To install libfuse, follow these steps:
Method 1
1. Run the following command to install fuse-devel.
If you are using CentOS or TencentOS systems, run the following command:
yum install fuse-devel
If you are using Ubuntu systems, run the following command:
aptinstall libfuse-dev
2. After installation, run the following command to check if the installation was successful.
find / -name libfuse.so*
Method 2
Update the old version libfuse.so.2.9.2. The installation steps are as follows:
Note:
CentOS 7 installs libfuse.so.2.9.2 by default.
1. Download the libfuse source code and compile and generate libfuse.so.2.9.7.
tar -zxvf fuse-2.9.7.tar.gz
cd fuse-2.9.7/ && ./configure &&make&&makeinstall
echo -e '\\n/usr/local/lib'>> /etc/ld.so.conf
ldconfig
2. After compiling and generating libfuse.so.2.9.7, follow these steps to replace it:
2.1 Run the following command to find the old version libfuse.so.2.9.2 library links.
find / -name libfuse.so*
2.2 Run the following commands to copy libfuse.so.2.9.7 to the location of the old version library libfuse.so.2.9.2.
cp /usr/local/lib/libfuse.so.2.9.7 /usr/lib64/
2.3 Run the following commands to delete all links of the old version libfuse.so library.
rm -f /usr/lib64/libfuse.so
rm -f /usr/lib64/libfuse.so.2
2.4 Run the following commands to build libfuse.so.2.9.7 library links similar to those of the old version library.
1. Edit the file /usr/lib/systemd/system/goosefs-lite.service and add the following content. You can replace examplebucket-1250000000 with your bucket: Note that the memory values configured in JAVA_OPTS (-Xms and -Xmx) should not exceed 50% of the physical memory limit of the node. For example, if the node has 16GB of physical memory, it is recommended to configure up to -Xms8G -Xmx8G.
The following uses version goosefs-lite-1.0.6 as an example:
[Unit]
Description=The Tencent Cloud GooseFS Lite for COS
2. Run the following command to execute the mount command and view the status of the background Daemon process.
# Apply the systemd configuration of goosefs-lite
systemctl daemon-reload
# Start the background Fuse process
systemctl start goosefs-lite
# View the status of the background Daemon process
systemctl status goosefs-lite
# View the mount point list
/usr/local/goosefs-lite-1.0.6/bin/goosefs-lite stat
# If modifying the systemd configuration, reload and restart after modification.
Set to attempt mounting at boot startup:
systemctl enable goosefs-lite
3. Uninstall the mount point, reboot the machine, and check the status of the Fuse process.
# Execute Uninstall. Note: Do not Uninstall during data writing, as it may cause data incomplete.
systemctl stop goosefs-lite
# Restart operating system. Proceed with caution to avoid affecting business.
reboot -h now
# View the status of the background Daemon process
systemctl status goosefs-lite
# View the mount point list
/usr/local/goosefs-lite-1.0.6/bin/goosefs-lite stat
GooseFS-Lite Having High CPU Utilization and Sending a Large Number of HEAD and LIST Requests to COS, Incurring a Large Amount of Request Fees During a Certain Period Every Day, What Should I Do
This is usually caused by a scheduled disk scan task on your machine. The common disk scan program on Linux systems is updatedb. You can add the GooseFS-Lite mount point directory to the PRUNEPATHS configuration item in the updatedb configuration file /etc/updatedb.conf to avoid the disk scan behavior of this program. Additionally, you can use the Linux tool auditd to find the programs accessing the GooseFS-Lite mount point.
Directions are as follows:
1. Install auditd.
If you are using Ubuntu systems, run the following command:
apt-getinstall auditd -y
If it is a CentOS system, execute the following command:
yum install audit audit-libs
2. Start the auditd service.
systemctl start auditd
systemctl enable auditd
3. Monitor the mounted directory.
Note:
-w specifies the GooseFS-Lite mounted directory, -k indicates the key to be outputted to the audit logs.
4. Determine the access program based on the logs.
The audit log directory: /var/log/audit, the query command is as follows:
ausearch -i|grep'goosefs_lite_mnt'
5. Stop auditd service.
If you need to stop the auditd service, you can use the following command:
/sbin/service auditd stop
Note:
If the program accessing the mount point is always running, the newly started auditd will not monitor the access behavior of the program. This is because only the first call in multiple calls from the program to the mounted directory will be recorded.
Handling "Cannot Allocate Memory" Error During GooseFS-Lite Installation
This error mainly occurs because of a memory allocation error during the GooseFS-Lite operation, usually when the requested memory exceeds the actual available memory.
You can modify the JAVA_OPT parameter in the ./bin/goosefs-lite file to a reasonable memory value, ensuring that the requested memory amount is less than the instance available memory amount.
Viewing the Latest Package Version
Run the following command, the return value is the latest version number.
Problem troubleshooting relies on logs. Below are the locations of the relevant logs.
For goosefs-lite version 1.0.3 and later, the default log directory is under /data/goosefs/logs/fuse.
For example: If the user mounting goosefs-lite is root and the mount point path is /data1/data2, then the log path is: /data/goosefs/logs/fuse/root/data1/data2.
For goosefs-lite versions 1.0.0-1.0.2, the default log directory is under /data/goosefs/logs.
Another way to check the mount point log path is to first remount, then ps aux | grep ${MOUNT_POINT}. From the output, you can see Error_File or goosefs.logs.dir, and the parent directory of this path is where all logs for the mount point are located.
System logs: If it is a centos or tlinux system, it is /var/log/message*. If it is ubuntu, it is /var/log/syslog.
If you need to enable debug logs, go to conf/log4j.properties, comment out the last line, and remount to take effect.
Note:
Enabling debug logs will impact performance. Normally, there is no need to enable them.
Mount failed with error "Name or service not known", how to handle it?
This is usually because the domain name cannot be resolved. You can try pinging the domain name. If the error shown above occurs, you can execute the following command:
ping VM-36-104-centos
If it also returns a failure, you can configure the corresponding IP by modifying /etc/hosts. Generally, you can set it to 127.0.0.1.
Follow the steps below:
1. Add a line in the /etc/hosts file. Replace VM-36-104-centos with your hostname.
127.0.0.1 VM-36-104-centos
2. Then retest with ping. After confirming normal resolution, remount to take effect.
Default Environment JDK Is Not KonaJDK11, How to Use GooseFS-lite
2. Copy the absolute path of the java binary program in konajdk. For example, the extracted jdk is under /root/konajdk11.
# Determine Java Version
/root/konajdk11/bin/java -v
# Modify the Current Shell's Java Environment Variable Without Affecting Other Shells and Processes
exportJAVA=/root/konajdk11/bin/java
# Mounting
goosefs-lite mount /mnt cosn://bucket-appid
3. Using ps aux | grep goosefs-lite, you can see the process starts with /root/konajdk11/bin/java, indicating that the specified java version is being used, operation completed.
The Mount Point Was Originally Normal, Suddenly Unable to Use During Operation, How to Handle
Assume the current problematic mount point is /tmp/mount_point.
1. First, use ps aux | grep /tmp/mount_point to check if any process is using this mount point, including goosefs-lite. If there is, use the kill command to terminate the corresponding process.
2. Use ls to attempt to access the mount point. If the return is empty, it means the mount point has been successfully unmounted. Then remount to take effect.
ls /mount_point
3. If an error like transport is not connected is thrown, execute umount -l /mount_point to force unmount. (This command requires root privileges.)
Usually, such situations are caused by processes being killed by kill -9 or the system oom-killer. You can find it in the system logs or goosefs-lite logs.
4. Check the mount point log directory (/data/goosefs/logs/fuse/$USER/$MOUNT_POINT) for logs starting with hs_error (file describes the stack and reason before program exit).
Throwing Exception: Unsupported or Unrecognized SSL Message, how to handle it?
The current environment does not support disabling https mode, configuration needs to be modified. The solution is to add the following content to the core-site.xml configuration file:
<property>
<name>fs.con.useHttps</name>
<value>false</value>
</property>
How to Access COS Using Intranet Domain Name in GooseFS-Lite
In the core-site.xml configuration file, delete the fs.cosn.bucket.region property and add fs.cosn.bucket.endpoint_suffix.
To learn more about parameters, read the following documents:
Typically, ERROR logs in the log will describe what permissions are missing, supplement as needed.
Note: For head bucket permissions, it needs to be set at the bucket level rather than just the path level. For example, cosn://bucket-appid/path will not work, it must be cosn://bucket-appid. This permission will not expose the objects in the bucket.
Handling Error "fuse: failed to open /dev/fuse Operation not permitted"
1. Check if you have root privileges.
2. If in a container, check if the container is started with --privileged. If not, add it.
3. Check if the fuse kernel module is installed: execute the command lsmod | grep fuse and see if there is any output. If not, it indicates that the fuse kernel module is missing.
Handling File Write Failure with Error "part num: 10001, the parameter partNumber is not valid"
This indicates that the number of parts for multipart upload exceeds the limit. COS supports a maximum of 10,000 parts. Therefore, goosefs-lite by default supports files up to 8MB*10000 (approximately 78GB). If you need to support larger files, you need to adjust the parameter fs.cosn.upload.part.size. For example, if fs.cosn.upload.part.size is changed to 16777216 (i.e., 16MB), it can support large files up to 16MB*10000.
Yes
No
Was this page helpful?