Skip to content

Commit de184b9

Browse files
wulianqingwulianqing
committed
add support for FUSE on Polar File System
1 parent 9a16bfe commit de184b9

12 files changed

+1154
-10
lines changed

‎Readme-FUSE-CN.md

+155
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# FUSE on pfs
2+
3+
用户态文件系统（FUSE）是Unix和类似Unix的计算机操作系统的一个软件接口，允许非特权用户在不编辑内核代码的情况下创建自己的文件系统。这是通过在用户空间运行文件系统代码来实现的，而FUSE模块只提供了一个通往实际内核接口的桥梁。
4+
5+
为了让用户像其他内核内置文件系统一样使用PFS的内核接口，我们实现了一个FUSE on PFS的处理程序，它被链接到LibFUSE库。这个程序定义了内核接口与 PFS 操作的请求-响应映射，即它指定了PFS如何响应读/写/统计请求。同时，这个程序也被用来挂载 PFS，在挂载PFS的时候，处理程序被注册到内核中。如果用户现在对PFS发出读/写/统计请求，内核会将这些IO请求转发给处理程序，然后将处理程序的响应发回给用户。
6+
7+
# FUSE主要模块
8+
9+
##### FUSE内核模块（内核状态）
10+
11+
FUSE内核模块实现了VFS接口（它实现了fuse文件驱动、fuse设备驱动的注册，并提供了超级块、inode等的维护）。它接收来自VFS的请求并将其传递给LibFUSE，然后LibFUSE将请求传递给PFS处理程序；
12+
13+
##### LibFUSE模块（用户态）
14+
15+
LibFUSE实现了文件系统的主要框架、PFS操作的封装、挂载管理以及通过/dev/fuse设备与内核模块的通信；
16+
17+
##### 用户程序模块（用户态）
18+
19+
用户程序在用户空间实现由LibFUSE库封装的PFS操作。
20+
21+
# 接口
22+
23+
FUSE接口在`fusepfs_operations`中定义，主要分为以下几类。
24+
25+
1. FUSE环境构建：init, destroy
26+
27+
2. 文件操作：create, mknod, open, rename, truncate, ftruncate
28+
29+
3. 目录操作：mkdir, opendir, readdir, rmdir
30+
31+
4. 链接：symlink, readlink, unlink
32+
33+
5. 文件属性：statfs, access, getattr, fgetattr
34+
35+
6. 扩展属性：getxattr, setxattr, listxattr, removexattr
36+
37+
7. 读写：read, write, read_buf, write_buf, fallocate
38+
39+
8. 同步I/O：fsync, fsyncdir
40+
41+
9. 多路复用：poll
42+
43+
10. 释放：release, releasedir
44+
45+
11. 其他：ioctl, lock, bmap
46+
47+
# 使用FUSE on PFS
48+
49+
#### 1. 安装PFS依赖
50+
51+
安装步骤详见文档[Readme-CN.md](./Readme-CN.md)中的【安装依赖】
52+
53+
#### 2. 加载FUSE模块
54+
55+
##### I. 下载FUSE资源包并解压
56+
57+
```bash
58+
tar -zxvf fuse.tar.gz
59+
```
60+
61+
推荐FUSE版本：2.9.2
62+
63+
##### II. 安装FUSE（3.2版本或以上需要安装Meson或Ninj）
64+
65+
```bash
66+
./configure && sudo make install
67+
```
68+
69+
##### III. 检查是否加载成功
70+
71+
```bash
72+
# 检查FUSE模块是否加载成功
73+
lsmod | grep fuse
74+
# 如果尚未加载成功，你可以通过以下命令来挂载FUSE
75+
modprobe fuse
76+
# 查看版本信息
77+
fusermount --version
78+
```
79+
80+
#### 3. 编译与安装
81+
82+
依赖项准备好后，进入代码根目录，执行脚本进行编译：
83+
84+
```bash
85+
./autobuild.sh && sudo ./install.sh
86+
```
87+
88+
#### 4. 使用FUSE
89+
90+
##### I. 挂载FUSE on PFS
91+
92+
挂载前需要对/etc/fuse.conf进行配置，在文件中添加一行`user_allow_other`即可
93+
94+
```bash
95+
/usr/local/polarstore/pfsd/bin/mount_pfs_fuse.sh [-p diskname] [-c rw/ro] mount_dir
96+
# 示例
97+
/usr/local/polarstore/pfsd/bin/mount_pfs_fuse.sh -p nvme1n1 -c rw ./fuse_mntdir
98+
```
99+
100+
`diskname`代表块设备名称。可以通过命令`lsblk`列出所有可用块设备信息；
101+
102+
`rw/ro`代表所启动实例为启动读写实例或者只读实例；
103+
104+
`mount_dir`指fuse挂载目录。
105+
106+
说明：挂载FUSE on PFS首先会启动pfsdaemon后台进程，然后启动pfs-fuse进程并挂载PFS到制定目录。
107+
108+
##### II. 通过FUSE访问PFS
109+
110+
在后台启动FUSE实例后，现在你可以 `cd` 进入挂载目录，像平常使用内核内置的文件系统一样操作PFS。所有操作的结果将被送入PFS挂载的磁盘。示例如下：
111+
112+
```bash
113+
# 进入挂载目录
114+
$cd path/to/fuse_mount_dir
115+
# 创建文件 写文件
116+
$echo "hello pfs fuse">test_file.txt
117+
# 打印文件内容
118+
$cat test_file.txt
119+
hello pfs fuse
120+
```
121+
122+
##### III. 结束使用
123+
124+
1. 解挂FUSE on PFS
125+
126+
你可以通过单独指定一个挂载路径来解挂特定FUSE实例，路径需要以绝对路径的形式指定；
127+
也可以选择`all`参数来解挂所有已挂载的PFS FUSE实例。
128+
129+
```bash
130+
/usr/local/polarstore/pfsd/bin/umount_pfs_fuse.sh [mount_dir/all]
131+
# 示例
132+
/usr/local/polarstore/pfsd/bin/umount_pfs_fuse.sh /fuse_mntdir
133+
/usr/local/polarstore/pfsd/bin/umount_pfs_fuse.sh all
134+
```
135+
136+
2. 停止pfsdaemon后台进程
137+
138+
支持两种方式：
139+
1. 通过盘名以停止指定pfsdaemon
140+
2. 以停止所有正在运行的pfsdaemon
141+
142+
```bash
143+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh [diskname]
144+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh
145+
146+
example:
147+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh nvme1n1
148+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh
149+
```
150+
151+
##### IV. 使用卸载脚本uninstall.sh进行卸载：
152+
153+
```bash
154+
sudo ./uninstall.sh
155+
```

‎Readme-FUSE.md

+155
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# FUSE on PFS
2+
3+
Filesystem in USErspace (FUSE) is a software interface for Unix and Unix-like computer operating systems that lets non-privileged users create their own file systems without editing kernel code. This is achieved by running file system code in user space while the FUSE module provides only a bridge to the actual kernel interfaces.
4+
5+
To allow users to use PFS with kernel interfaces like any other kernel built-in filesystems, we implement a FUSE on PFS handler program, which is linked to the supplied LibFUSE library. This program defines the request-respond mapping of kernal interfaces to pfs operations, which means it specify how PFS is to respond to read/write/stat requests. The program is also used to mount PFS. At the time PFS is mounted, the handler is registered with the kernel. If a user now issues read/write/stat requests for PFS, the kernel forwards these IO-requests to the handler and then sends the handler's response back to the user.
6+
7+
# Main FUSE Modules
8+
9+
#### FUSE kernel module (kernel state)
10+
11+
The FUSE kernel module implements the VFS interface (which implements the registration of the fuse file driver, the fuse device driver, and provides maintenance of super blocks, inode, etc.) It receives requests from VFS and passes them to LibFUSE, and then LibFUSE passes requests to PFS handler program;
12+
13+
#### LibFUSE module (user state)
14+
15+
LibFUSE implements the main framework of the file system, the encapsulation of PFS operations, mount management and communication with the kernel module via /dev/fuse device;
16+
17+
#### User program module (user state)
18+
19+
User programs implement PFS operations encapsulated by the LibFUSE library in user space.
20+
21+
# Interfaces
22+
23+
FUSE interfaces are defined in`fusepfs_operations`, mainly divided into the following categories :
24+
25+
1. FUSE environment building: init, destroy
26+
27+
2. file operations: create, mknod, open, rename, truncate, ftruncate
28+
29+
3. directory operations: mkdir, opendir, readdir, rmdir
30+
31+
4. link: symlink, readlink, unlink
32+
33+
5. file attribute: statfs, access, getattr, fgetattr
34+
35+
6. extended attribute: getxattr, setxattr, listxattr, removexattr
36+
37+
7. R/W: read, write, read_buf, write_buf, fallocate
38+
39+
8. Sync I/O: fsync, fsyncdir
40+
41+
9. multiplexing: poll
42+
43+
10. release: release, releasedir
44+
45+
11. other: ioctl, lock, bmap
46+
47+
48+
# Use FUSE on PFS
49+
50+
#### 1. Install PFS Dependencies
51+
52+
Refer to 【Install Dependencies】part in document [Readme.md](./Readme.md) for installation steps
53+
54+
#### 2. Load FUSE Module
55+
56+
##### I. Download FUSE resource package and decompress
57+
58+
``` bash
59+
tar -zxvf fuse.tar.gz
60+
```
61+
Recommended FUSE version: 2.9.2
62+
63+
##### II. Install FUSE (fuse 3.2 or above needs Meson or Ninj)
64+
65+
```bash
66+
./configure && sudo make install
67+
```
68+
69+
##### III. Check
70+
71+
````bash
72+
# check if FUSE is mounted successfully
73+
lsmod | grep fuse
74+
# If not, you can use `modprobe fuse` to mount FUSE.
75+
modprobe fuse
76+
# Look up version information
77+
fusermount --version
78+
````
79+
80+
#### 3. Complie and Install
81+
82+
After the dependencies are installed, go to the root directory of PFS source code and run the script to compile and install PFS.
83+
84+
```bash
85+
./autobuild.sh && sudo ./install.sh
86+
```
87+
88+
#### 4. Usage
89+
90+
##### I. mount FUSE on PFS
91+
92+
Before mounting, you need to configure /etc/fuse.conf:
93+
add `user_allow_other` to the file
94+
95+
```bash
96+
/usr/local/polarstore/pfsd/bin/mount_pfs_fuse.sh [-p diskname] [-c rw/ro] mount_dir
97+
# example
98+
/usr/local/polarstore/pfsd/bin/mount_pfs_fuse.sh -p nvme1n1 -c rw ./fuse_mntdir
99+
```
100+
101+
`diskname` block device. you can get the information of all your available block devices with shell command `lsblk`;
102+
103+
`rw/ro` startup a read&write or read-only instance;
104+
105+
`mount_dir` fuse mount directory.
106+
107+
p.s. Mounting FUSE on PFS will first start pfsdaemon in the background, then start pfs-fuse process, pfs-fuse will mount PFS to the specified directory.
108+
109+
##### II. Visit PFS by FUSE
110+
111+
After starting a pfsdfuse instance in background, now you can `cd` into the mount directory to operate PFS like a kernel built-in file system as usual. The results of all operations will be sent into the disk mounted via PFS. Here is an example :
112+
113+
```bash
114+
# enter mount directory
115+
$cd path/to/fuse_mount_dir
116+
# create file and write
117+
$echo "hello pfs fuse">test_file.txt
118+
# show new file
119+
$cat test_file.txt
120+
hello pfs fuse
121+
```
122+
123+
##### III. Stop using FUSE on PFS
124+
125+
1. Umount FUSE on pfs
126+
127+
128+
```bash
129+
/usr/local/polarstore/pfsd/bin/umount_pfs_fuse.sh [mount_dir/all]
130+
# example
131+
/usr/local/polarstore/pfsd/bin/umount_pfs_fuse.sh /fuse_mntdir
132+
/usr/local/polarstore/pfsd/bin/umount_pfs_fuse.sh all
133+
```
134+
135+
your can appoint a `mount_dir` to umount the selected instance, `mount dir` should be pointed as absolute path;
136+
your can also choose `all` to umount all mounted pfsdfuse instance.
137+
138+
2. Stop pfsdaemon
139+
140+
You can stop single pfsdaemon by pointing a diskname of the pfsdaemon, or you can kill all pfsdaemons by running stop_pfsd.sh without any parameter.
141+
142+
```bash
143+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh [diskname]
144+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh
145+
146+
example:
147+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh nvme1n1
148+
sudo /usr/local/polarstore/pfsd/bin/stop_pfsd.sh
149+
```
150+
151+
##### IV. Run the uninstall.sh script to uninstall pfsdaemon
152+
153+
```
154+
sudo ./uninstall.sh
155+
```

0 commit comments

Comments
 (0)