DOCA 文档 v2.10.0
NVIDIA 文档中心  NVIDIA 网络  BlueField DPU / SuperNIC 和 DOCA  DOCA 文档 v2.10.0  DOCA App Shield

本页内容

DOCA App Shield

本指南提供有关使用 DOCA App Shield API 的说明。

简介

DOCA App Shield API 提供了一种解决方案，利用 DPU 服务从主机（或主机上的 VM）内存中实时收集和分析数据，从而实现强大的入侵检测功能。此解决方案以以下方式提供入侵检测和取证调查：

  • 针对主机上的攻击具有鲁棒性

  • 能够检测各种攻击（包括零日攻击）

  • 对主机应用程序的执行干扰最小（当前检测解决方案会妨碍主机应用程序的性能）

  • 对主机透明，因此主机无需安装任何内容（只需提供从工具获取的一些文件即可）

App Shield 使用 DMA 设备访问主机内存并对其进行分析。

App Shield API 提供了多个功能，可帮助收集从系统内存中提取的数据（例如，进程列表、模块列表、连接）。此数据有助于检测对系统中关键服务或进程的攻击（例如，强制执行不同应用程序执行的完整性或隐私的服务）。

前提条件

  1. 配置 NVIDIA® BlueField® 网络平台（DPU 或 SuperNIC）的固件。

    1. 在 BlueField 上，配置 PF 基址寄存器和 NVMe 仿真。运行

      复制
      已复制！
                  
      
            
      dpu> mlxconfig -d /dev/mst/mt41686_pciconf0 s PF_BAR2_SIZE=2 PF_BAR2_ENABLE=1

      如果使用 VF，请配置 NVME 仿真、SR-IOV 和 VF 数量。运行

      复制
      已复制！
                  
      
            
      dpu> mlxconfig -d /dev/mst/mt41686_pciconf0 s NVME_EMULATION_ENABLE=1 SRIOV_EN=1 NUM_OF_VFS=<vf-number>

    2. 执行正常关机并从主机冷启动。

      信息

      可以使用以下命令检查这些配置

      复制
      已复制！
                  
      
            
      dpu> mlxconfig -d /dev/mst/mt41686_pciconf0 q | grep -E "NVME|BAR|SRIOV|NUM_OF_VFS"

  2. 下载目标系统（主机/VM）符号。

    • 对于 Ubuntu

      复制
      已复制！
                  
      
            
      host> sudo tee /etc/apt/sources.list.d/ddebs.list << EOF
deb http://ddebs.ubuntu.com/ $(lsb_release -cs) main restricted universe multiverse
deb http://ddebs.ubuntu.com/ $(lsb_release -cs)-updates main restricted universe multiverse
deb http://ddebs.ubuntu.com/ $(lsb_release -cs)-proposed main restricted universe multiverse
EOF
host> sudo apt install ubuntu-dbgsym-keyring
host> sudo apt-get update
host> sudo apt-get install linux-image-$(uname -r)-dbgsym

    • 对于 CentOS

      复制
      已复制！
                  
      
            
      host> yum install --enablerepo=base-debuginfo kernel-devel-$(uname -r) kernel-debuginfo-$(uname -r) kernel-debuginfo-common-$(uname -m)-$(uname -r)

    • Windows 不需要执行任何操作

  3. 执行 IOMMU 直通。仅当默认情况下未启用 IOMMU 时，此阶段才是必需的（例如，当主机使用 AMD CPU 时）。

    注意

    如果您不确定是否需要此步骤，请跳过此步骤。仅当 DMA 失败并在 dmesg 中显示类似以下消息时，才返回此步骤

    复制
    已复制！
                
    
            
    host> dmesg
[ 3839.822897] mlx5_core 0000:81:00.0: AMD-Vi: Event logged [IO_PAGE_FAULT domain=0x0047 address=0x2a0aff8 flags=0x0000]

    1. 找到您的操作系统的 grub 文件（很可能是 /boot/grub/grub.conf、/boot/grub2/grub.cfg 或 /etc/default/grub），并打开进行编辑。运行

      复制
      已复制！
                  
      
            
      host> vim /etc/default/grub

    2. 搜索定义 GRUB_CMDLINE_LINUX_DEFAULT 的行，并添加参数 iommu=pt。例如

      复制
      已复制！
                  
      
            
      GRUB_CMDLINE_LINUX_DEFAULT="iommu=pt <intel/amd>_iommu=on"

    3. 运行

      注意

      在执行电源循环之前，请务必执行正常关机。

      • 对于 Ubuntu

        复制
        已复制！
                    
        
            
        host> sudo update-grub

      • 对于 CentOS

        复制
        已复制！
                    
        
            
        host> grub2-mkconfig -o /boot/grub2/grub.cfg

  4. BlueField 当前最多支持 4 级虚拟内存层。因此，有必要检查目标系统是否使用 5 级虚拟内存层，并据此调整配置

    1. 检查虚拟内存层

      复制
      已复制！
                  
      
            
      grep la57 /proc/cpuinfo

      验证输出中是否有 la57 标志。如果出现类似情况

      复制
      已复制！
                  
      
            
      flags : ... la57 ...

      这表明目标系统正在使用 5 级虚拟内存层，并且必须停用 5 级分页。

    2. 要停用 5 级分页，请使用 GRUB 修改内核参数。将以下行添加到您的 GRUB 配置中

      复制
      已复制！
                  
      
            
      GRUB_CMDLINE_LINUX_DEFAULT="no5lvl"

    3. 更新 GRUB 配置

      复制
      已复制！
                  
      
            
      update-grub

    4. 重新启动系统以应用更改。

  5. 准备目标

    1. 在目标系统上安装 DOCA。

    2. 创建 ZIP 和 JSON 文件。运行

      复制
      已复制！
                  
      
            
      target-system> cd /opt/mellanox/doca/tools/
target-system> python3 doca_apsh_config.py --pid <pid-of-process-to-monitor> --os <windows/linux> --path <path to dwarf2json executable  or pdbparse-to-json.py>
target-system> cp /opt/mellanox/doca/tools/*.* <shared-folder-with-baremetal>
dpu> scp <shared-folder-with-baremetal>/* <path-to-app-shield-binary>

      如果目标系统未安装 DOCA，则可以从 BlueField 复制脚本。

      DOCA 未提供所需的 dwaf2json 和 pdbparse-to-json.py。

      注意

      如果内核和进程 .exe 没有更改，则无需重新执行此步骤。

依赖项

该库需要固件版本 24.32.1010 或更高版本。

API

有关库 API 参考，请参阅DOCA 库 API中的 DOCA APSH API 文档。

注意

APSH 库的 pkg-config (*.pc 文件) 是 doca-apsh。

以下小节提供了有关库 API 的更多详细信息。

doca_apsh_dma_dev_set

要将 DOCA DMA 设备连接到 App Shield，必须调用此函数，并且必须在调用 doca_apsh_start 之前完成。

复制
已复制！
            

            
doca_apsh_dma_dev_set(doca_apsh_ctx, doca_dev)

  • doca_apsh_ctx [in] – App Shield 不透明上下文结构

  • doca_dev [in] – 具有 DMA 功能的 DOCA 设备结构

各系统功能

对于每个初始化的系统，App Shield 根据 getter 的名称检索请求的对象数组

Getter 函数名称

函数信息

函数签名

返回类型

获取模块

返回一个数组，其中包含有关加载到操作系统内核中的系统模块（驱动程序）的信息。
复制
已复制！
            

            
doca_error_t doca_apsh_modules_get(struct doca_apsh_system *system, struct doca_apsh_module ***modules, int *modules_size);

  • struct doca_apsh_module 数组

  • int – 返回数组的大小

  • doca_error 状态

获取进程

返回一个数组，其中包含有关系统上运行的每个进程的信息。
复制
已复制！
            

            
doca_error_t doca_apsh_processes_get(struct doca_apsh_system *system, struct doca_apsh_process ***processes, int *processes_size);

  • struct doca_apsh_process 数组

  • int – 返回数组的大小

  • doca_error 状态

获取库

对于指定的进程，此函数返回一个数组，其中包含有关加载到此进程中的每个库的信息。
复制
已复制！
            

            
doca_error_t doca_apsh_libs_get(struct doca_apsh_process *process, struct doca_apsh_lib ***libs, int *libs_size);

  • struct doca_apsh_lib 数组

  • int – 返回数组的大小

  • doca_error 状态

获取线程

对于指定的进程，此函数返回一个数组，其中包含有关在此进程中运行的每个线程的信息。
复制
已复制！
            

            
doca_error_t doca_apsh_threads_get(struct doca_apsh_process *process, struct doca_apsh_thread ***threads, int *threads_size);

  • struct doca_apsh_thread 数组

  • int – 返回数组的大小

  • doca_error 状态

获取虚拟内存区域/虚拟地址描述

对于指定的进程，此函数返回一个数组，其中包含有关此进程中每个虚拟内存区域的信息。
复制
已复制！
            

            
doca_error_t doca_apsh_vads_get(struct doca_apsh_process *process, struct doca_apsh_vad ***vads, int *vads_size);

  • struct doca_apsh_vma 数组

  • int – 返回数组的大小

  • doca_error 状态

获取权限

对于指定的进程，此函数返回一个数组，其中包含有关此进程的每个可能权限的信息，如此处所述。

注意

仅在 Windows 主机上可用。
复制
已复制！
            

            
doca_error_t doca_apsh_privileges_get(struct doca_apsh_process *process, struct doca_apsh_privilege ***privileges, int *privileges_size);

  • struct doca_apsh_privilege 数组

  • int – 返回数组的大小

  • doca_error 状态

获取环境变量

对于指定的进程，此函数返回一个数组，其中包含有关此进程中每个环境变量的信息。

注意

仅在 Windows 主机上可用。
复制
已复制！
            

            
doca_error_t doca_apsh_envars_get(struct doca_apsh_process *process, struct doca_apsh_envar ***envars, int *envars_size);

  • struct doca_apsh_envar 数组

  • int – 返回数组的大小

  • doca_error 状态

获取句柄

对于指定的进程，此函数返回一个数组，其中包含有关此进程拥有的每个句柄的信息。

注意

仅在 Windows 主机上可用。
复制
已复制！
            

            
doca_error_t doca_apsh_handles_get(struct doca_apsh_process *process, struct doca_apsh_handle ***handles, int *handles_size);

  • struct doca_apsh_handle 数组

  • int – 返回数组的大小

  • doca_error 状态

获取 LDR 模块

对于指定的进程，此函数返回一个数组，其中包含有关此进程中每个加载模块的信息。

注意

仅在 Windows 主机上可用。
复制
已复制！
            

            
doca_error_t doca_apsh_ldrmodules_get(struct doca_apsh_process *process, struct doca_apsh_ldrmodule ***ldrmodules, int *ldrmodules_size);

  • struct doca_apsh_ldrmodule 数组

  • int – 返回数组的大小

  • doca_error 状态

进程证明

对于指定的进程，此函数根据作为输入提供的预先计算的黄金哈希文件来证明进程的内存页。

注意

Beta 级别支持单线程进程。
复制
已复制！
            

            
doca_error_t doca_apsh_attestation_get(struct doca_apsh_process *process, const char *exec_hash_map_path, struct doca_apsh_attestation ***attestation, int *attestation_size);

  • struct doca_apsh_attestation 数组

  • int – 返回数组的大小

  • doca_error 状态

证明刷新

使用新的快照刷新进程的单个证明处理程序。
复制
已复制！
            

            
doca_error_t doca_apsh_attst_refresh(struct doca_apsh_attestation ***attestation, int *attestation_size);

  • struct doca_apsh_attestation 数组

  • int – 返回数组的大小

  • doca_error 状态

获取 NetScan

此函数扫描系统的物理内存 (Windows) 或内核内存空间 (Linux)，并返回一个数组，其中包含有关内存中每个套接字的信息。

注意

仅在具有 Linux OS 或以下 Windows 10 OS 版本之一的主机上可用：

架构

内部版本号

x86

10240

10586

14393

15063

17134

19041

x64

15063

16299

17134

17763

18362

18363

19041

注意

此功能当前在 Beta 级别受支持。
复制
已复制！
            

            
doca_error_t doca_apsh_netscan_get(struct doca_apsh_system *system, struct doca_apsh_netscan ***connections, int *connections_size);

  • struct doca_apsh_netscan 数组

  • int – 返回数组的大小

  • doca_error 状态

获取进程参数

对于指定的进程，此函数返回一个结构对象（不是数组），其中包含有关进程参数的信息（未包含在“获取进程”功能中的参数）。

注意

仅在 Windows 主机上可用。

注意

此功能当前在 Beta 级别受支持。
复制
已复制！
            

            
doca_error_t doca_apsh_process_parameters_get(struct doca_apsh_process *process, struct doca_apsh_process_parameters **process_parameters);

  • struct doca_apsh_process_paramters 对象

  • doca_error 状态

获取安全标识符 (SID)

对于指定的进程，此函数返回一个数组，其中包含有关进程安全上下文中包含的每个 SID（安全标识符）的信息。

注意

仅在 Windows 主机上可用。
复制
已复制！
            

            
doca_error_t doca_apsh_sids_get(struct doca_apsh_process *process, struct doca_apsh_sid ***sids, int *sids_size);

  • struct doca_apsh_sid 数组

  • int – 返回数组的大小

  • doca_error 状态

执行 Yara 扫描

对于指定的进程，此函数返回一个数组，其中包含有关在进程内存中找到的每个 Yara 规则匹配项的信息。

注意

在 Windows 主机和 Ubuntu 22.04 DPU 上可用。
复制
已复制！
            

            
doca_error_t doca_apsh_yara_get(struct doca_apsh_process *process,
enum doca_apsh_yara_rule *yara_rules_arr, uint32_t yara_rules_arr_size,
uint64_t scan_type, struct doca_apsh_yara ***yara_matches, int *yara_matches_size);
注意

要更好地理解参数，请参阅 doca_apsh.h 中的文档。

  • struct doca_apsh_yara 数组

  • int – 返回数组的大小

  • doca_error 状态

获取容器

返回一个数组，其中包含有关系统上运行的每个容器的信息。

注意

仅在 Linux 主机上可用。

注意

仅适用于以下运行时的容器

  • runc

  • containerd
复制
已复制！
            

            
doca_error_t doca_apsh_containers_get(struct doca_apsh_system *system, struct doca_apsh_container ***containers, int *containers_size);

  • struct doca_apsh_container 数组

  • int – 返回数组的大小

  • doca_error 状态

获取容器的进程

对于指定的容器，此函数返回一个数组，其中包含有关在此容器中运行的每个进程的信息。

注意

仅在 Linux 主机上可用。

注意

仅适用于以下运行时的容器

  • runc

  • containerd
复制
已复制！
            

            
doca_error_t doca_apsh_container_processes_get(struct doca_apsh_container *container, struct doca_apsh_process ***processes, int *processes_size);

  • struct doca_apsh_process 数组

  • int – 返回数组的大小

  • doca_error 状态

获取进程 NetScan

此函数扫描系统的物理内存 (Windows) 或内核内存空间 (Linux)，并返回一个数组，其中包含有关内存中每个套接字的信息。

注意

仅在具有 Linux OS 或以下 Windows 10 OS 版本之一的主机上可用：

架构

内部版本号

x86

10240

10586

14393

15063

17134

19041

x64

15063

16299

17134

17763

18362

18363

19041

注意

此功能当前在 Beta 级别受支持。
复制
已复制！
            

            
doca_error_t doca_apsh_process_netscan_get(struct doca_apsh_process *process, struct doca_apsh_netscan ***connections, int *connections_size);

  • struct doca_apsh_netscan 数组

  • int – 返回数组的大小

  • doca_error 状态

以下属性 getter 返回从上面列出的 getter 函数返回的数组中获取的对象的特定属性，具体取决于请求的属性

复制
已复制！
            

            
doca_apsh_process_info_get(struct doca_apsh_proccess *process, enum doca_apsh_process_attr attr);
doca_apsh_module_info_get(struct doca_apsh_module *module, enum doca_apsh_module_attr attr);
doca_apsh_lib_info_get(struct doca_apsh_lib *lib, enum doca_apsh_lib_attr attr);
doca_apsh_thread_info_get(struct doca_apsh_thread *thread, enum doca_apsh_lib_attr attr);
doca_apsh_vad_info_get(struct doca_apsh_vad *vad, enum doca_apsh_vad_attr attr);
doca_apsh_privilege_info_get(struct doca_apsh_privilege *privilege, enum doca_apsh_privilege_attr attr);
doca_apsh_envar_info_get(struct doca_apsh_envar *envar, enum doca_apsh_envar_attr attr);
doca_apsh_handle_info_get(struct doca_apsh_handle *handle, enum doca_apsh_handle_attr attr);
doca_apsh_ldrmodule_info_get(struct doca_apsh_ldrmodule *ldrmodule, enum doca_apsh_ldrmodule_attr attr);
doca_apsh_attst_info_get(struct doca_apsh_attestation *attestation, enum doca_apsh_attestation_attr attr);
doca_apsh_netscan_info_get(struct doca_apsh_netscan *connection, enum doca_apsh_netscan_attr attr)
doca_apsh_process_parameters_info_get(struct doca_apsh_process_parameters *process_parameters, enum doca_apsh_process_parameters_attr attr);
doca_apsh_sid_info_get(struct doca_apsh_sid *sid, enum doca_apsh_sid_attr attr);
doca_apsh_yara_info_get(struct doca_apsh_yara *yara, enum doca_apsh_yara_attr attr);
doca_apsh_container_info_get(struct doca_apsh_container *container, enum doca_apsh_container_attr attr);

属性 getter 的返回类型可以在 doca_apsh_attr.h 中找到。

使用示例

复制
已复制！
            

            
const uint pid = doca_apsh_process_info_get(processes[i], DOCA_APSH_PROCESS_PID);
const char *proc_name = doca_apsh_process_info_get(processes[i], DOCA_APSH_PROCESS_COMM);


App Shield 初始化和拆卸

要使用 App Shield，用户必须初始化和配置两个主要结构。本节介绍这些结构，并解释如何与它们交互。

doca_apsh_ctx

doca_apsh_ctx 是 App Shield 使用的基本结构，它定义了用于执行运行 App Shield 所需的内存取证技术的 DMA 设备。

注意

同一个 doca_apsh_ctx 结构可用于在不同系统（例如，主机上的两个不同 VM）上运行多个 App Shield 实例。

  1. 要获取 doca_apsh_ctx 结构的实例，请使用以下函数

    复制
    已复制！
                
    
            
    struct doca_apsh_ctx *doca_apsh_create(void);

  2. 要使用要使用的 DMA 设备配置 doca_apsh_ctx 实例

    复制
    已复制！
                
    
            
    doca_error_t doca_apsh_dma_dev_set(struct doca_apsh_ctx *ctx, struct doca_dev *dma_dev);

  3. 要启动 doca_apsh_ctx 实例，请调用以下函数

    复制
    已复制！
                
    
            
    doca_error_t doca_apsh_start(struct doca_apsh_ctx *ctx);

  4. 要在不再需要 doca_apsh_ctx 实例时销毁它，请调用

    复制
    已复制！
                
    
            
    void doca_apsh_destroy(struct doca_apsh_ctx *ctx);

doca_apsh_system

doca_apsh_system 结构构建在 doca_apsh_ctx 实例之上。此结构是为每个运行 App Shield 的系统创建的。doca_apsh_system 定义了 App Shield 用于成功执行特定系统内存分析的多个属性。

  1. 要获取 doca_apsh_system 结构的实例，请使用以下函数

    复制
    已复制！
                
    
            
    const uint pid = doca_apsh_process_info_get(processes[i], DOCA_APSH_PROCESS_PID);
const char *proc_name = doca_apsh_process_info_get(processes[i], DOCA_APSH_PROCESS_COMM);

  2. 要为系统实例配置不同的属性

    • 操作系统类型 – 指定系统的操作系统类型。

      复制
      已复制！
                  
      
            
      doca_error_t doca_apsh_sys_os_type_set(struct doca_apsh_system *ctx, enum doca_apsh_system_os os_type);

      注意

      当前支持的类型：Windows 或 Linux。

    • 系统代表 – 指定连接到系统以运行 App Shield 的设备的代表（可以是 VF/PF 的代表）。有关查询 DOCA 设备的信息，请参阅DOCA Core。

      获取 DOCA 设备后，使用以下函数将其配置到系统实例中

      复制
      已复制！
                  
      
            
      doca_error_t doca_apsh_sys_dev_set(struct doca_apsh_system *system, struct doca_dev_rep *dev);

    • 系统符号映射 – 包括有关 App Shield 尝试在其上运行的操作系统的信息（例如，Window 10 Build 18363）以及操作系统结构的大小和字段，这有助于 App Shield 使用其内存取证技术来访问和分析系统内存中的这些结构。可以通过在系统计算机上运行 doca_apsh_config.py 来获得。

      获得后，有两种选择可以提供文件

      • 第一种选择是显式指定文件路径

        复制
        已复制！
                    
        
            
        doca_error_t doca_apsh_sys_os_symbol_map_set(struct doca_apsh_system *system, const char *system_os_symbol_map_path);

      • 第二种选择是提供文件所在的文件夹

        复制
        已复制！
                    
        
            
        doca_error_t doca_apsh_sys_os_symbol_map_folder_set(struct doca_apsh_system *system, const char *system_os_symbol_folder_path);

        注意

        在此选项中，文件名必须保持为 doca_apsh_config.py。

    • 内存区域 – 包括为系统内存 RAM 映射的内存区域的物理地址。这是为了防止 App Shield 访问其他内存区域，例如内存映射 I/O 区域。可以通过在系统计算机上运行 doca_apsh_config.py 工具来获得。

      获得后，运行

      复制
      已复制！
                  
      
            
      doca_error_t doca_apsh_sys_mem_region_set(struct doca_apsh_system *system, const char *system_mem_region_path);

    • KPGD 文件（可选且仅与 Linux OS 相关）– 包含 KPGD 物理地址和 init_task 的虚拟地址。由于 App Shield 从物理内存中的内核结构中提取数据，因此需要此信息。因此，内核页目录表必须转换这些结构的虚拟地址。可以通过在系统计算机上运行 doca_apsh_config.py 工具并使用标志 find_kpgd=1 来获得。由于设置此属性是可选的，因此 App Shield 可以在没有它的情况下工作，但提供它可以加快 App Shield 的初始化过程。

      获得后，运行

      复制
      已复制！
                  
      
            
      doca_error_t doca_apsh_sys_kpgd_file_set(struct doca_apsh_system *system, const char *system_kpgd_file_path);

  3. 要启动 doca_apsh_system

    复制
    已复制！
                
    
            
    doca_error_t doca_apsh_system_start(struct doca_apsh_system *system);

  4. 要在不再需要 doca_apsh_system 实例时销毁它，请调用

    复制
    已复制！
                
    
            
    void doca_apsh_system_destroy(struct doca_apsh_system *system);

doca_apsh_config.py 工具

doca_apsh_config.py 工具是一个 python3 脚本，可用于获取运行 doca_apsh_system 实例所需的所有属性。

以下参数是使用该工具所必需的

参数

描述

pid (可选)

我们要对其运行证明功能的进程的进程 ID

os (必需)

机器的操作系统类型（即 Linux 或 Windows）

find_kpgd (可选)

仅与 Linux OS 相关，AS 标志用于启用/禁用创建 kpgd_file.conf。默认值为 0。

files (必需)

工具要创建的文件列表。文件选项：hash、symbols、memregions、kpgd_file（仅与 Linux 相关）。

注意

确保设置的值适合您的设置。

path (必需)

  • Linux – dwarf2json 可执行文件的路径。默认值为 ./dwarf2json。可以通过使用 Go 编译以下项目来获得此文件。

  • Windows – pdbparse-to-json.py 的路径。默认值为 ./pdbparse-to-json.py。可以在此处找到此文件。

注意

确保设置的值适合您的设置。

该工具创建以下文件

  • 符号映射 – 此文件在系统内核更新或安装内核模块后更改。系统重新启动时，该文件不会更改。

  • 内存区域 – 此文件在添加或删除影响系统内存映射的硬件或驱动程序时更改（例如，在添加寄存器地址时）。系统重新启动时，该文件不会更改。

  • hash.zip – 此文件是证明所必需的，但对于所有其他功能来说是不必要的。ZIP 文件包含证明单个进程所需的数据。该文件在库或可执行文件更新时更改。

  • kpgd_file.conf（仅与 Linux OS 相关）– 有助于加快库的初始化速度。系统重新启动时，该文件会更改。

DOCA App Shield 示例

本节提供基于 BlueField 的 DOCA App Shield 库示例实现。

信息

本节中描述的所有 DOCA 示例均受 BSD-3 软件许可协议的管辖。

示例前提条件

按照“前提条件”部分中的指南进行操作，然后将生成的 JSON 文件 symbols.json 和 mem_regions.json 复制到 /tmp/ 目录。

运行示例

  1. 请参阅以下文档

    • DOCA Linux 安装指南，了解有关如何安装 BlueField 相关软件的详细信息。

    • DOCA 故障排除，了解您在 DOCA 示例的安装、编译或执行过程中可能遇到的任何问题。

  2. 要构建给定的示例

    复制
    已复制！
                
    
            
    cd /opt/mellanox/doca/samples/doca_apsh/<sample_name>
meson /tmp/build
ninja -C /tmp/build

    注意

    二进制文件 doca_<sample_name> 将在 /tmp/build/ 下创建。

  3. 示例（例如，apsh_libs_get）用法

    复制
    已复制！
                
    
            
    Usage: doca_apsh_libs_get [DOCA Flags] [Program Flags]
 
DOCA Flags:
  -h, --help                        Print a help synopsis
  -v, --version                     Print program version information
  -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
  -j, --json <path>                 Parse all command flags from an input json file
 
Program Flags:
  -p, --pid                         Process ID of process to be analyzed
  -f, --vuid                        VUID of the System device
  -d, --dma                         DMA device name
  -s, --osty <windows|linux>        System OS type - windows/linux

  4. 有关每个示例的更多信息，请使用 -h 选项

    复制
    已复制！
                
    
            
    /tmp/build/doca_<sample_name> -h

示例

Apsh Libs Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取特定进程的可加载库列表。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的供应商唯一标识符 (VUID) 打开 DOCA 远程 PCI 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 Apsh API 获取系统进程列表，并搜索具有给定 PID 的特定进程。

  8. 使用 doca_apsh_libs_get Apsh API 调用获取进程可加载库列表。

  9. 使用 doca_apsh_lib_info_get Apsh API 调用查询 3 个选定字段的库。

  10. 将库属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_libs_get/apsh_libs_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_libs_get/apsh_libs_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_libs_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Modules Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取受监控系统上安装的模块列表。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCI 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 doca_apsh_modules_get Apsh API 调用获取系统安装的模块列表。

  8. 使用 doca_apsh_module_info_get Apsh API 调用查询模块名称。

  9. 将最多 5 个模块属性的属性打印到终端。

  10. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_modules_get/apsh_modules_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_modules_get/apsh_modules_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_modules_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Pslist

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取受监控系统上运行的进程列表。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCI 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 doca_apsh_processes_getApsh API 调用获取系统上运行的进程列表。

  8. 使用 doca_apsh_proc_info_get Apsh API 调用查询 4 个选定属性的进程。

  9. 将最多 5 个进程的属性打印到终端。

  10. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_pslist/apsh_pslist_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_pslist/apsh_pslist_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_pslist/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Threads Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取特定进程的线程列表。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCI 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 Apsh API 获取系统进程列表，并搜索具有给定 PID 的特定进程。

  8. 使用 doca_apsh_threads_get Apsh API 调用获取进程线程列表。

  9. 使用 doca_apsh_thread_info_get Apsh API 调用查询最多 3 个选定字段的线程。

  10. 将线程属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_threads_get/apsh_threads_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_threads_get/apsh_threads_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_threads_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Vads Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取特定进程的虚拟地址描述符 (VAD) 列表。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCI 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 Apsh API 获取系统进程列表，并搜索具有给定 PID 的特定进程。

  8. 使用 doca_apsh_vads_get Apsh API 调用获取进程 VAD 列表。

  9. 使用 doca_apsh_vad_info_get Apsh API 调用查询 3 个选定字段的 VAD。

  10. 将最多 5 个 VAD 的属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_vads_get/apsh_vads_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_vads_get/apsh_vads_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_vads_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Envars Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取特定进程的环境变量列表。

注意

此示例仅在具有 Windows OS 的目标系统上有效。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCIe 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 Apsh API 获取系统进程列表，并搜索具有给定 PID 的特定进程。

  8. 使用 doca_apsh_envars_get Apsh API 调用获取进程 envar 列表。

  9. 使用 doca_apsh_envar_info_get Apsh API 调用查询 2 个选定字段的 envar。

  10. 将 envar 属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_envars_get/apsh_envars_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_envars_get/apsh_envars_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_envars_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Privileges Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取特定进程的权限列表。

注意

此示例仅在具有 Windows OS 的目标系统上有效。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCIe 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 Apsh API 获取系统进程列表，并搜索具有给定 PID 的特定进程。

  8. 使用 doca_apsh_privileges_get Apsh API 调用获取进程权限列表。

  9. 使用 doca_apsh_privilege_info_get Apsh API 调用查询 5 个选定字段的权限。

  10. 将权限属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_privileges_get/apsh_privileges_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_privileges_get/apsh_privileges_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_privileges_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Containers Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取受监控系统上运行的容器列表，以及获取每个容器的进程列表。

注意

此示例仅在具有 Linux OS 的目标系统上有效。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 使用特定 VUID 打开 DOCA 远程 PCIe 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 doca_apsh_containers_get Apsh API 调用获取系统上运行的容器列表。

  8. 使用 doca_apsh_container_info_get Apsh API 调用查询容器的容器 ID 属性。

  9. 使用 doca_apsh_container_processes_get Apsh API 调用获取每个容器的进程列表。

  10. 将最多 5 个进程的属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_containers_get/apsh_containers_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_containers_get/apsh_containers_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_containers_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Netscan Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取受监控系统上打开的网络连接列表。

注意

此示例仅在具有 Linux OS 和特定 Windows OS 版本的目标系统上有效。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 使用特定 VUID 打开 DOCA 远程 PCIe 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 doca_apsh_netscan_get Apsh API 调用获取系统上打开的连接列表。

  8. 使用 doca_apsh_netscan_info_get Apsh API 调用查询某些连接属性的连接。

  9. 将所有连接的属性打印到终端。

  10. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_netscan_get/apsh_netscan_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_netscan_get/apsh_netscan_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_netscan_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h

Apsh Process Netscan Get

此示例说明如何正确初始化 DOCA App Shield 并使用其 API 获取特定进程的打开的网络连接列表。

注意

此示例仅在具有 Linux OS 和特定 Windows OS 版本的目标系统上有效。

示例逻辑包括

  1. 打开具有 DMA 能力的 DOCA 设备。

  2. 创建 DOCA Apsh 上下文。

  3. 设置并启动 Apsh 上下文。

  4. 通过给定的 VUID 打开 DOCA 远程 PCI 设备。

  5. 创建 DOCA Apsh 系统处理程序。

  6. 设置字段并启动 Apsh 系统处理程序。

  7. 使用 Apsh API 获取系统进程列表，并搜索具有给定 PID 的特定进程。

  8. 使用 doca_apsh_process_netscan_get Apsh API 调用获取进程连接列表。

  9. 使用 doca_apsh_netscan_info_get Apsh API 调用查询某些连接属性的连接。

  10. 将连接属性打印到终端。

  11. 清理。

参考

  • /opt/mellanox/doca/samples/doca_apsh/apsh_process_netscan_get/apsh_process_netscan_get_sample.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_process_netscan_get/apsh_process_netscan_get_main.c

  • /opt/mellanox/doca/samples/doca_apsh/apsh_process_netscan_get/meson.build

  • /opt/mellanox/doca/samples/doca_apsh/apsh_common.c; /opt/mellanox/doca/samples/doca_apsh/apsh_common.h
© 版权所有 2025 NVIDIA。 上次更新于 2025 年 2 月 12 日。
此处内容