From 6f3a0eae85f8dee4d368f597e4148a2861ee8865 Mon Sep 17 00:00:00 2001 From: Deng Guangxing Date: Sun, 12 Nov 2023 10:14:42 +0800 Subject: [PATCH 1/2] add vsock-sim README Signed-off-by: Deng Guangxing --- qtfs/test/vsock-sim/README.md | 36 +++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 qtfs/test/vsock-sim/README.md diff --git a/qtfs/test/vsock-sim/README.md b/qtfs/test/vsock-sim/README.md new file mode 100644 index 0000000..212e6a8 --- /dev/null +++ b/qtfs/test/vsock-sim/README.md @@ -0,0 +1,36 @@ +# vsock-sim介绍 + +## 背景 + +qtfs为部署在HOST和DPU上的客户端-服务器模型，二者之间需要进行通信。出于安全性考虑，没有使用开放的网络协议作为qtfs客户端与服务端的通信方式，而是选择vsock这一封闭但是仍具备通用性的协议（用户也可以通过QTFS_TEST_MODE flag编译开启网络模式，建议只作为测试模式）。 + +由于vsock默认只能用于虚拟化场景，用于宿主机与虚拟机或同宿主机上的虚拟机之间的通信（通过cid区分不同机器），通用环境下无法直接使用vsock，所以vsock-sim就是为了提供一个vsock的仿真环境，用户可以在常规环境中使用vsock协议通信。 + +未来DPU硬件可根据自定义的通信通道封装为vsock协议对上层应用提供通信。 + +## 原理 + +vsock-sim的实现原理为替换了系统的vsock_family_ops，当用户通过socket系统调用创建AF_VSOCK类型socket时，使用vsock-sim提供的socket create接口函数。该函数会创建一个AF_INET类型的socket，并将该socket的部分socket_ops替换为vsock-sim的。主要是其中跟地址相关的ops，如bind、connect等，将这些处理函数的vsock类型地址转换为预先设定好的inet类型地址。 + +通过上述方式完成vsock类型socket替换为inet类型。 + +## 使用方式 + +vsock-sim为内核模块，可以在当前目录下直接编译： + +``` +# make clean +# make +``` + +编译完成后生成vsock-sim.ko + +通过以下命令插入vsock-sim模块，通过参数指定vsock cid和ip地址之间的对应关系，后续用户对特定vsock cid的使用都会转换为指定ip： + +``` +# insmod ./vsock-sim.ko cid_ip_map=2-192.168.122.104,3-192.168.122.103 +``` + +上述命令为将cid 2映射到ip 192.168.122.104， 将cid 3映射到ip 192.168.122.103 + +cid-ip-map参数通`,`分隔cid-ip对；通过`-`分隔cid及ip，左侧为cid，右侧为ip。 -- Gitee From a6ef144a17b6635496bbe8d71e43cad699c0c015 Mon Sep 17 00:00:00 2001 From: Deng Guangxing Date: Sun, 12 Nov 2023 11:22:27 +0800 Subject: [PATCH 2/2] update qtfs README and doc Signed-off-by: Deng Guangxing --- qtfs/README.md | 62 +++++--- ...77\347\224\250\346\211\213\345\206\214.md" | 136 ++++++++++++++---- 2 files changed, 149 insertions(+), 49 deletions(-) diff --git a/qtfs/README.md b/qtfs/README.md index 56456e0..53f6d4e 100644 --- a/qtfs/README.md +++ b/qtfs/README.md @@ -37,7 +37,8 @@ qtfs的特性： 如有DPU硬件支持通过vsock与host通信，可选择此方法。 如果没有硬件，也可以选择host-vm作为qtfs的client与server进行模拟测试，通信通道为vsock： - 1. 启动vm时为vm配置vsock通道，vm可参考如下配置，将vsock段加在devices配置内： + 1. 启动vm时为vm配置vsock通道，vm可参考如下配置，将vsock段加在devices配置内： + ``` ... @@ -49,32 +50,34 @@ qtfs的特性： ... ``` - 2. 要求内核版本在5.10或更高版本。 + 2. 要求内核版本在5.10或更高版本。 3. 安装内核开发包：yum install kernel-devel json-c-devel。 -服务端安装： +服务端编译安装： - 1. cd qtfs_server + 1. cd qtfs_server 2. make clean && make -j 3. insmod qtfs_server.ko qtfs_server_vsock_cid=2 qtfs_server_vsock_port=12345 qtfs_log_level=WARN - 4. 配置白名单，将qtfs/config/qtfs/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，至少需要配置一个Mount白名单才能启动后续服务。 - 5. nohup ./engine 16 1 2 12121 10 12121 2>&1 & - Tips: 这里的cid需要根据配置决定，如果host作为server端，则cid固定配置为2，如果vm作为server端，则需要配置为前面xml中的cid字段，本例中为10。 + 4. 配置白名单，将qtfs/config/qtfs/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，至少需要配置一个Mount白名单才能启动后续服务，任何文件或目录的增删改查操作都需要在白名单中增加对应权限才能正常工作。 + 5. nohup ./engine 16 1 2 12121 10 12121 2>&1 & + 6. engine参数解释：engine ${number_of_threads} ${uds_proxy_thread_number} ${server_cid_or_ip} ${server_uds_proxy_port} ${client_cid_or_ip} ${client_uds_proxy_port} + Tips: 这里的cid需要根据配置决定，如果host作为server端，则cid固定配置为2，如果vm作为server端，则需要配置为前面xml中的cid字段，本例中为10。 客户端安装： 1. cd qtfs 2. make clean && make -j 3. insmod qtfs.ko qtfs_server_vsock_cid=2 qtfs_server_vsock_port=12345 qtfs_log_level=WARN - 4. cd ../ipc/ - 5. make clean && make && make install - 6. nohup udsproxyd 1 10 12121 2 12121 2>&1 & - Tips：这里插入ko的cid和port配置为与server端一致即可，udsproxyd的cid+port与server端交换位置。 + 4. cd ../ipc/ + 5. make clean && make && make install + 6. nohup udsproxyd 1 10 12121 2 12121 2>&1 & + 7. udsproxyd参数解释：udsproxyd ${uds_proxy_thread_number} ${client_cid_or_ip} ${client_uds_proxy_port} ${server_cid_or_ip} ${server_uds_proxy_port} + Tips：这里插入ko的cid和port配置为与server端一致即可，udsproxyd的cid+port与server端交换位置。 其他注意事项： - 1. udsproxyd目前也支持vsock和测试模式两种，使用vsock模式时，不能带UDS_TEST_MODE=1进行编译。 - 2. 如果vsock不通，需要检查host是否插入了vhost_vsock内核模块：modprobe vhost_vsock。 + 1. udsproxyd目前也支持vsock和测试模式两种，使用vsock模式时，不能带UDS_TEST_MODE=1进行编译。 + 2. 如果vsock不通，需要检查host是否插入了vhost_vsock内核模块：modprobe vhost_vsock。 ### 测试模式，仅用于测试环境： @@ -82,27 +85,30 @@ qtfs的特性： 1. 要求内核版本在5.10或更高版本。 2. 安装内核开发包：yum install kernel-devel。 - 3. 假设host服务器ip为192.168.10.10，dpu为192.168.10.11 + 3. 假设host服务器ip为192.168.10.10，dpu为192.168.10.11 服务端安装： 1. cd qtfs_server 2. make clean && make -j QTFS_TEST_MODE=1 - 3.指定测试服务端的ip，ip a a ip_server(例：192.168.10.10)/port dev network（例:ens32），防止机器重启造成的ip变更问题，方便测试 + 3. 指定测试服务端的ip，ip a a ip_server(例：192.168.10.10)/port dev network（例:ens32），防止机器重启造成的ip变更问题，方便测试 4. insmod qtfs_server.ko qtfs_server_ip=x.x.x.x qtfs_server_port=12345 qtfs_log_level=WARN - 5. 配置白名单，将qtfs/config/qtfs/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，至少需要配置一个Mount白名单才能启动后续服务。 + 5. 配置白名单，将qtfs/config/qtfs/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，至少需要配置一个Mount白名单才能启动后续服务。任何文件或目录的增删改查操作都需要在白名单中增加对应权限才能正常工作。 6. nohup ./engine 16 1 192.168.10.10 12121 192.168.10.11 12121 2>&1 & + 7. engine参数解释：engine ${number_of_threads} ${uds_proxy_thread_number} ${server_cid_or_ip} ${server_uds_proxy_port} ${client_cid_or_ip} ${client_uds_proxy_port} Tips: 该模式暴露网络端口，有可能造成安全隐患，仅能用于功能验证测试，勿用于实际生产环境。 客户端安装： 1. cd qtfs 2. make clean && make -j QTFS_TEST_MODE=1 - 3.指定测试用户端的ip，ip a a ip_client(例：192.168.10.11)/port dev network（例:ens32），防止机器重启造成的ip变更问题，方便测试 + 3. 指定测试用户端的ip，ip a a ip_client(例：192.168.10.11)/port dev network（例:ens32），防止机器重启造成的ip变更问题，方便测试 3. insmod qtfs.ko qtfs_server_ip=x.x.x.x qtfs_server_port=12345 qtfs_log_level=WARN 4. cd ../ipc/ - 5. make clean && make && make install + 5. make clean && make UDS_TEST_MODE=1 && make install 6. nohup udsproxyd 1 192.168.10.11 12121 192.168.10.10 12121 2>&1 & + 7. udsproxyd参数解释：udsproxyd ${uds_proxy_thread_number} ${client_cid_or_ip} ${client_uds_proxy_port} ${server_cid_or_ip} ${server_uds_proxy_port} + Tips：这里插入ko的cid和port配置为与server端一致即可，udsproxyd的cid+port与server端交换位置。 Tips: 该模式暴露网络端口，有可能造成安全隐患，仅能用于功能验证测试，勿用于实际生产环境。 ## 使用说明 @@ -112,7 +118,25 @@ qtfs的特性： mount -t qtfs /home /root/mnt/ 客户端进入"/root/mnt"后便可查看到server端/home目录下的所有文件，以及对其进行相关操作。此操作受到白名单的控制，需要挂载路径在server端白名单的Mount列表，或者在其子目录下，且后续的查看或读写操作都需要开放对应的白名单项才能进行。 -Tips：若完成测试环境的配置后，无法通过服务端访问所挂载的客户端文件，可检查是否由防火墙的阻断导致。 +Tips：若完成测试环境的配置后，无法通过客户端访问所挂载的客户端文件，可检查是否由防火墙的阻断导致。 + +## rexec使用 + +1. rexec工具依赖上述udsproxyd服务，使用udsproxyd提供的uds协同进行通信，请确认udsproxyd正常启动。 + +2. 配置白名单，将qtfs/config/rexec/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，在其中增加允许执行的二进制命令。 + +3. 在udsconnect中增加rexec通信socket所在目录白名单，增加方式有两种： + + 1. 在/etc/qtfs/whitelist的`[udsconnect]`表项中增加`/var/run/rexec`，修改后需要重新部署qtfs使其生效。 + + 2. 进入源码目录`qtinfo/`，执行`make`编译得到二进制。使用qtcfg进行配置：`qtcfg -w udsconnect -x /var/run/rexec`，配置完成后可通过`qtcfg -w udsconnect -z`查询是否生效 + +4. 拉起rexec_server作为服务端，无需参数 + +5. 通过rexec ${your_cmd} 验证rexec功能是否正常 + +Tips：rexec的远程执行功能支持双向，需要在client和server都拉起rexec_server服务。 ## 参与贡献 diff --git "a/qtfs/doc/qtfs\345\205\261\344\272\253\346\226\207\344\273\266\347\263\273\347\273\237\346\236\266\346\236\204\345\217\212\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/qtfs/doc/qtfs\345\205\261\344\272\253\346\226\207\344\273\266\347\263\273\347\273\237\346\236\266\346\236\204\345\217\212\344\275\277\347\224\250\346\211\213\345\206\214.md" index 8088f48..879a5e4 100644 --- "a/qtfs/doc/qtfs\345\205\261\344\272\253\346\226\207\344\273\266\347\263\273\347\273\237\346\236\266\346\236\204\345\217\212\344\275\277\347\224\250\346\211\213\345\206\214.md" +++ "b/qtfs/doc/qtfs\345\205\261\344\272\253\346\226\207\344\273\266\347\263\273\347\273\237\346\236\266\346\236\204\345\217\212\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -2,25 +2,17 @@ ## 介绍 -qtfs是一个共享文件系统项目，可部署在host-dpu的硬件架构上，也可以部署在2台服务器之间。以客户端服务器的模式工作，使客户端能通过qtfs访问服务端的指定文件系统，得到本地文件访问一致的体验。 +qtfs是一个共享文件系统项目，可部署在host-dpu的硬件架构上，也可以部署在host-vm或同一台host的vm-vm之间，通过vsock建立安全通信通道。以客户端服务器的模式工作，使客户端能通过qtfs访问服务端的指定文件系统，就像访问本地文件系统一样。 qtfs的特性： - + 支持挂载点传播； - + 支持proc、sys、cgroup等特殊文件系统的共享； - -+ 支持远程文件读写的共享； - ++ 客户端对qtfs目录下文件的操作都被转移到服务端，文件读写可共享； + 支持在客户端对服务端的文件系统进行远程挂载； - -+ 支持特殊文件的定制化处理； - ++ 可以定制化处理特殊文件； + 支持远端fifo、unix-socket等，并且支持epoll，使客户端和服务端像本地通信一样使用这些文件； - -+ 支持基于host-dpu架构通过PCIe协议底层通信，性能大大优于网络； - -+ 支持内核模块形式开发，无需对内核进行侵入式修改。 ++ 基于host-dpu架构时，底层通信方式可以支持PCIe，性能大大优于网络； ++ 内核模块形式开发，无需对内核进行侵入式修改。 ## 软件架构 @@ -31,39 +23,123 @@ qtfs的特性： ## 安装教程 目录说明： ++ **rexec**：跨主机二进制生命周期管理组件，在该目录下编译rexec和rexec_server。 ++ **ipc**: 跨主机unix domain socket协同组件，在该目录下编译udsproxyd二进制和libudsproxy.so库。 ++ **qtfs**: 客户端内核模块相关代码，直接在该目录下编译客户端ko。 ++ **qtfs_server**: 服务端内核模块相关代码，直接在该目录下编译服务端ko和相关程序。 ++ **qtinfo**: 诊断工具，支持查询文件系统的工作状态以及修改log级别等。 ++ **demo**、**test**、**doc**: 测试程序、演示程序以及项目资料等。 ++ 根目录: 是客户端与服务端都能用到的公共模块代码。 + +### VSOCK通信模式 + +如有DPU硬件支持通过vsock与host通信，可选择此方法。 +如果没有硬件，也可以选择host-vm作为qtfs的client与server进行模拟测试，通信通道为vsock： + + 1. 启动vm时为vm配置vsock通道，vm可参考如下配置，将vsock段加在devices配置内： + +``` + + ... + + + +
+ + ... + +``` + 2. 要求内核版本在5.10或更高版本。 + 3. 安装内核开发包：yum install kernel-devel json-c-devel。 + +服务端编译安装： -+ **qtfs**: 客户端内核模块相关代码，直接在该目录下编译客户端ko。 - -+ **qtfs_server**: 服务端内核模块相关代码，直接在该目录下编译服务端ko和相关程序。 + 1. cd qtfs_server + 2. make clean && make -j + 3. insmod qtfs_server.ko qtfs_server_vsock_cid=2 qtfs_server_vsock_port=12345 qtfs_log_level=WARN + 4. 配置白名单，将qtfs/config/qtfs/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，至少需要配置一个Mount白名单才能启动后续服务，任何文件或目录的增删改查操作都需要在白名单中增加对应权限才能正常工作。 + 5. nohup ./engine 16 1 2 12121 10 12121 2>&1 & + 6. engine参数解释：engine ${number_of_threads} ${uds_proxy_thread_number} ${server_cid_or_ip} ${server_uds_proxy_port} ${client_cid_or_ip} ${client_uds_proxy_port} + Tips: 这里的cid需要根据配置决定，如果host作为server端，则cid固定配置为2，如果vm作为server端，则需要配置为前面xml中的cid字段，本例中为10。 -+ **qtinfo**: 诊断工具，支持查询文件系统的工作状态以及修改log级别等。 +客户端安装： + + 1. cd qtfs + 2. make clean && make -j + 3. insmod qtfs.ko qtfs_server_vsock_cid=2 qtfs_server_vsock_port=12345 qtfs_log_level=WARN + 4. cd ../ipc/ + 5. make clean && make && make install + 6. nohup udsproxyd 1 10 12121 2 12121 2>&1 & + 7. udsproxyd参数解释：udsproxyd ${uds_proxy_thread_number} ${client_cid_or_ip} ${client_uds_proxy_port} ${server_cid_or_ip} ${server_uds_proxy_port} + Tips：这里插入ko的cid和port配置为与server端一致即可，udsproxyd的cid+port与server端交换位置。 -+ **demo**、**test**、**doc**: 测试程序、演示程序以及项目资料等。 +其他注意事项： + + 1. udsproxyd目前也支持vsock和测试模式两种，使用vsock模式时，不能带UDS_TEST_MODE=1进行编译。 + 2. 如果vsock不通，需要检查host是否插入了vhost_vsock内核模块：modprobe vhost_vsock。 -+ 根目录: 客户端与服务端通用的公共模块代码。 +### 测试模式，仅用于测试环境： -首先找两台服务器（或虚拟机）配置内核编译环境： +找两台服务器（或虚拟机）配置内核编译环境： - 1. 要求内核版本在5.10或更高版本。 -  2. 安装内核开发包：yum install kernel-devel。 + 1. 要求内核版本在5.10或更高版本。 + 2. 安装内核开发包：yum install kernel-devel。 + 3. 假设host服务器ip为192.168.10.10，dpu为192.168.10.11 服务端安装： - + 1. cd qtfs_server - 2. make clean && make - 3. insmod qtfs_server.ko qtfs_server_ip=x.x.x.x qtfs_server_port=12345 qtfs_log_level=WARN - 4. ./engine 4096 16 + 2. make clean && make -j QTFS_TEST_MODE=1 + 3. 指定测试服务端的ip，ip a a ip_server(例：192.168.10.10)/port dev network（例:ens32），防止机器重启造成的ip变更问题，方便测试 + 4. insmod qtfs_server.ko qtfs_server_ip=x.x.x.x qtfs_server_port=12345 qtfs_log_level=WARN + 5. 配置白名单，将qtfs/config/qtfs/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，至少需要配置一个Mount白名单才能启动后续服务。任何文件或目录的增删改查操作都需要在白名单中增加对应权限才能正常工作。 + 6. nohup ./engine 16 1 192.168.10.10 12121 192.168.10.11 12121 2>&1 & + 7. engine参数解释：engine ${number_of_threads} ${uds_proxy_thread_number} ${server_cid_or_ip} ${server_uds_proxy_port} ${client_cid_or_ip} ${client_uds_proxy_port} + Tips: 该模式暴露网络端口，有可能造成安全隐患，仅能用于功能验证测试，勿用于实际生产环境。 客户端安装： - + 1. cd qtfs - 2. make clean && make + 2. make clean && make -j QTFS_TEST_MODE=1 + 3. 指定测试用户端的ip，ip a a ip_client(例：192.168.10.11)/port dev network（例:ens32），防止机器重启造成的ip变更问题，方便测试 3. insmod qtfs.ko qtfs_server_ip=x.x.x.x qtfs_server_port=12345 qtfs_log_level=WARN + 4. cd ../ipc/ + 5. make clean && make UDS_TEST_MODE=1 && make install + 6. nohup udsproxyd 1 192.168.10.11 12121 192.168.10.10 12121 2>&1 & + 7. udsproxyd参数解释：udsproxyd ${uds_proxy_thread_number} ${client_cid_or_ip} ${client_uds_proxy_port} ${server_cid_or_ip} ${server_uds_proxy_port} + Tips：这里插入ko的cid和port配置为与server端一致即可，udsproxyd的cid+port与server端交换位置。 + Tips: 该模式暴露网络端口，有可能造成安全隐患，仅能用于功能验证测试，勿用于实际生产环境。 ## 使用说明 安装完成后，客户端通过挂载把服务端的文件系统让客户端可见，例如： + + mount -t qtfs /home /root/mnt/ + +客户端进入"/root/mnt"后便可查看到server端/home目录下的所有文件，以及对其进行相关操作。此操作受到白名单的控制，需要挂载路径在server端白名单的Mount列表，或者在其子目录下，且后续的查看或读写操作都需要开放对应的白名单项才能进行。 +Tips：若完成测试环境的配置后，无法通过客户端访问所挂载的客户端文件，可检查是否由防火墙的阻断导致。 + +## rexec使用 + +1. rexec工具依赖上述udsproxyd服务，使用udsproxyd提供的uds协同进行通信，请确认udsproxyd正常启动。 + +2. 配置白名单，将qtfs/config/rexec/whitelist文件拷贝至/etc/qtfs/下，请手动配置需要的白名单选项，在其中增加允许执行的二进制命令。 + +3. 在udsconnect中增加rexec通信socket所在目录白名单，增加方式有两种： + + 1. 在/etc/qtfs/whitelist的`[udsconnect]`表项中增加`/var/run/rexec`，修改后需要重新部署qtfs使其生效。 + + 2. 进入源码目录`qtinfo/`，执行`make`编译得到二进制。使用qtcfg进行配置：`qtcfg -w udsconnect -x /var/run/rexec`，配置完成后可通过`qtcfg -w udsconnect -z`查询是否生效 + +4. 拉起rexec_server作为服务端，无需参数 + +5. 通过rexec ${your_cmd} 验证rexec功能是否正常 + +Tips：rexec的远程执行功能支持双向，需要在client和server都拉起rexec_server服务。 - mount -t qtfs / /root/mnt/ +## 参与贡献 -客户端进入"/root/mnt"后便可查看到server端的所有文件，以及对其进行相关操作。 +1. Fork 本仓库 +2. 新建 Feat_xxx 分支 +3. 提交代码 +4. 新建 Pull Request -- Gitee