diff --git a/docs/ubdiag_integration_guide.md b/docs/ubdiag_integration_guide.md
new file mode 100644
index 0000000000..2282331a5d
--- /dev/null
+++ b/docs/ubdiag_integration_guide.md
@@ -0,0 +1,205 @@
+# Mooncake UbDiag 两层集成使用指南
+
+Mooncake 在配置阶段提供两个互斥的 UbDiag 编译层。构建完成后不能在运行时切换层级；如需切换，应重新配置并编译。
+
+| 层 | 配置 | UbDiag 来源 | 生成结果 |
+|---|---|---|---|
+| Layer 0：Mock | `MOONCAKE_ENABLE_UBDIAG=OFF` | Mooncake 拉取固定源码头文件 | PerfPoint 为空实现，无 UbDiag 运行时依赖 |
+| Layer 1：System | `MOONCAKE_ENABLE_UBDIAG=ON` | 用户预装的 UbDiag RPM | Mooncake 链接系统 `.so`，并可将同版本 CLI/`.so` 打入单一 RPM |
+
+## 1. Layer 0：默认 Mock
+
+### 1.1 配置与编译
+
+```bash
+cmake -S . -B build \
+  -DMOONCAKE_ENABLE_UBDIAG=OFF
+cmake --build build --parallel
+```
+
+`MOONCAKE_ENABLE_UBDIAG` 默认值为 `OFF`，因此该参数可以省略。
+
+Mooncake 使用 FetchContent 拉取固定修订的 UbDiag 源码，只消费 `include/ubdiag` 公共头文件，并通过统一目标 `UbDiag::ubdiag_lib` 传播 `UBDIAG_DISABLE`。
+
+UbDiag 头文件中的 `UBDIAG_DISABLE` 分支将 PerfPoint 构造、`Start()`、`End()` 和 `Abandon()` 编译为空实现。因此：
+
+- Mooncake 打点源码保持不变；
+- Mooncake ELF 不依赖 `libubdiag.so`；
+- 不生成或打包 UbDiag CLI；
+- 不创建 UbDiag SHM；
+- 系统中已安装的 UbDiag 不参与该构建。
+
+离线环境可以指定已准备好的 UbDiag 源码目录：
+
+```bash
+cmake -S . -B build \
+  -DMOONCAKE_ENABLE_UBDIAG=OFF \
+  -DMOONCAKE_UBDIAG_SOURCE_DIR=/opt/src/ubdiag
+```
+
+## 2. Layer 1：系统 UbDiag
+
+### 2.1 前置条件
+
+Layer 1 不下载或编译真实 UbDiag。配置 Mooncake 前，用户必须先安装完整的 UbDiag 运行时 RPM 和开发 RPM。安装结果必须同时提供：
+
+- `UbDiagConfig.cmake`；
+- 导入目标 `UbDiag::ubdiag_lib`；
+- 共享库 `libubdiag.so`；
+- 可被系统找到的 `ubdiag` CLI；
+- `UBDIAG_ENABLE_PERCENTILE`；
+- `UBDIAG_ENABLE_PERFLOG`。
+
+UbDiag RPM 构建时应至少启用：
+
+```text
+UBDIAG_BUILD_SHARED=ON
+ENABLE_PERCENTILE=ON
+ENABLE_PERFLOG=ON
+```
+
+Mooncake 不固定 Layer 1 的 UbDiag 版本或源码 SHA。它通过 RPM 数据库分别查询 `libubdiag.so` 与 CLI 的 `VERSION-RELEASE.ARCH`，并要求二者完全一致。UbDiag RPM 中其他功能的启用情况和功能正确性由 UbDiag 发布包负责。
+
+### 2.2 配置与编译
+
+标准系统路径：
+
+```bash
+cmake -S . -B build-ubdiag \
+  -DMOONCAKE_ENABLE_UBDIAG=ON
+cmake --build build-ubdiag --parallel
+```
+
+自定义 RPM 安装前缀：
+
+```bash
+cmake -S . -B build-ubdiag \
+  -DMOONCAKE_ENABLE_UBDIAG=ON \
+  -DCMAKE_PREFIX_PATH=/opt/ubdiag \
+  -DCMAKE_PROGRAM_PATH=/opt/ubdiag/bin
+```
+
+也可以直接指定 CMake package 和 CLI：
+
+```bash
+cmake -S . -B build-ubdiag \
+  -DMOONCAKE_ENABLE_UBDIAG=ON \
+  -DUbDiag_DIR=/opt/ubdiag/lib64/cmake/UbDiag \
+  -DMOONCAKE_UBDIAG_SYSTEM_CLI=/opt/ubdiag/bin/ubdiag
+```
+
+### 2.3 配置检查
+
+ON 模式依次确认：
+
+1. 找到 UbDiag CMake package 和 `UbDiag::ubdiag_lib`；
+2. package 导出 `SHARED_LIBRARY` 目标；
+3. target 传播 P99 与 PerfLog 能力宏；
+4. 找到 `ubdiag` CLI；
+5. `.so` 与 CLI 均由已安装的 RPM 提供；
+6. 两者的 `VERSION-RELEASE.ARCH` 完全一致。
+
+任一条件不满足都会停止配置。Mooncake 不会回退到源码构建；应先修复或重新安装 UbDiag RPM，再重新配置 Mooncake。
+
+## 3. 构建 Mooncake RPM
+
+### 3.1 Mock RPM
+
+```bash
+bash scripts/build_rpm.sh build rpm-output "$(uname -m)"
+rpm -qlp rpm-output/mooncake-*.rpm
+```
+
+Mock RPM 包含 Mooncake 二进制，但不包含：
+
+```text
+/usr/bin/ubdiag
+/usr/lib64/libubdiag.so*
+/etc/ubdiag/ubdiag.conf
+```
+
+### 3.2 System RPM
+
+```bash
+bash scripts/build_rpm.sh build-ubdiag rpm-output "$(uname -m)"
+rpm -qlp rpm-output/mooncake-*.rpm
+```
+
+System RPM 包含：
+
+```text
+/usr/bin/mooncake_master
+/usr/bin/mooncake_client
+/usr/bin/ubdiag
+/usr/lib64/libubdiag.so*
+/etc/ubdiag/ubdiag.conf    # 系统安装提供该配置时
+```
+
+打包脚本读取 `build-ubdiag/mooncake_ubdiag.env`，并复制 CMake 配置阶段已经选中的 CLI、共享库及其符号链接。CLI 与共享库的版本一致性在 CMake 配置阶段完成检查；如果构建机上的 UbDiag RPM 随后发生变化，应重新配置后再打包。
+
+## 4. 安装与运行
+
+Mooncake RPM 使用标准系统路径安装 Mooncake 和 UbDiag 运行时：
+
+```text
+/usr/bin/mooncake_master
+/usr/bin/mooncake_client
+/usr/bin/ubdiag
+/usr/lib64/libubdiag.so*
+/etc/ubdiag/ubdiag.conf
+```
+
+安装和基础运行命令：
+
+```bash
+sudo rpm -Uvh rpm-output/mooncake-*.rpm
+sudo ldconfig
+
+ubdiag --version
+ubdiag start
+ubdiag status
+
+# 启动 Mooncake master/client 并执行实际读写负载
+
+ubdiag show
+ubdiag show --detail
+```
+
+PerfLog、P99、历史数据和 CSV 参数以所安装 UbDiag CLI 的帮助为准：
+
+```bash
+ubdiag --help
+ubdiag show --help
+```
+
+## 5. 常见错误
+
+### `.so` 或 CLI 不受 RPM 管理
+
+Layer 1 面向系统 UbDiag RPM，不接受手工复制的散装文件。请安装完整的 UbDiag 运行时 RPM 和开发 RPM 后重新配置 Mooncake。
+
+### `.so` 与 CLI 的 RPM 版本不同
+
+卸载冲突版本，并安装同一发布批次的 UbDiag RPM。Mooncake 比较 `VERSION-RELEASE.ARCH`，不通过文件 SHA 判断。
+
+### 找到静态库
+
+重新构建 UbDiag RPM，并设置 `UBDIAG_BUILD_SHARED=ON`。
+
+### 缺少 P99 或 PerfLog
+
+重新构建 UbDiag RPM，并设置：
+
+```text
+ENABLE_PERCENTILE=ON
+ENABLE_PERFLOG=ON
+```
+
+### 从 Mock 切换到 System
+
+推荐使用新的构建目录：
+
+```bash
+cmake -S . -B build-ubdiag \
+  -DMOONCAKE_ENABLE_UBDIAG=ON
+```
diff --git a/mooncake-common/FindUbDiag.cmake b/mooncake-common/FindUbDiag.cmake
new file mode 100644
index 0000000000..a70a306057
--- /dev/null
+++ b/mooncake-common/FindUbDiag.cmake
@@ -0,0 +1,184 @@
+# Two-layer UbDiag integration for Mooncake.
+#
+# Layer 0 (default) uses the UbDiag public headers with UBDIAG_DISABLE. Layer 1
+# consumes a shared UbDiag SDK and CLI installed from system RPMs.
+
+include_guard(GLOBAL)
+
+option(MOONCAKE_ENABLE_UBDIAG
+       "Use the system-installed UbDiag shared library and CLI" OFF)
+
+function(_mooncake_write_ubdiag_manifest layer library cli config)
+  file(
+    WRITE "${CMAKE_BINARY_DIR}/mooncake_ubdiag.env"
+    "MOONCAKE_UBDIAG_LAYER=${layer}\n"
+    "MOONCAKE_UBDIAG_SYSTEM_LIBRARY=${library}\n"
+    "MOONCAKE_UBDIAG_SYSTEM_CLI=${cli}\n"
+    "MOONCAKE_UBDIAG_SYSTEM_CONFIG=${config}\n")
+  set(MOONCAKE_UBDIAG_ACTIVE_LAYER
+      "${layer}"
+      CACHE INTERNAL "Active Mooncake UbDiag layer" FORCE)
+endfunction()
+
+if(NOT MOONCAKE_ENABLE_UBDIAG)
+  set(MOONCAKE_UBDIAG_GIT_REPOSITORY
+      "https://github.com/LinQuickDev/ubdiag.git"
+      CACHE STRING "UbDiag repository used by Layer 0")
+  set(MOONCAKE_UBDIAG_GIT_TAG
+      "8df2c2844d402e2e4dcd5ceab2424e8d36c5f99f"
+      CACHE STRING "UbDiag revision used by Layer 0")
+  set(MOONCAKE_UBDIAG_SOURCE_DIR
+      ""
+      CACHE PATH "Local UbDiag source directory for offline builds")
+
+  include(FetchContent)
+  if(MOONCAKE_UBDIAG_SOURCE_DIR)
+    set(ubdiag_SOURCE_DIR "${MOONCAKE_UBDIAG_SOURCE_DIR}")
+  else()
+    FetchContent_Populate(
+      ubdiag
+      GIT_REPOSITORY "${MOONCAKE_UBDIAG_GIT_REPOSITORY}"
+      GIT_TAG "${MOONCAKE_UBDIAG_GIT_TAG}")
+  endif()
+
+  add_library(mooncake_ubdiag_mock INTERFACE)
+  target_include_directories(mooncake_ubdiag_mock
+                             INTERFACE "${ubdiag_SOURCE_DIR}/include")
+  target_compile_definitions(mooncake_ubdiag_mock INTERFACE UBDIAG_DISABLE)
+  add_library(UbDiag::ubdiag_lib ALIAS mooncake_ubdiag_mock)
+
+  set(MOONCAKE_UBDIAG_LIBRARY_DIR
+      ""
+      CACHE INTERNAL "System UbDiag library directory" FORCE)
+  _mooncake_write_ubdiag_manifest("mock" "" "" "")
+  message(STATUS "UbDiag: Layer 0 UBDIAG_DISABLE headers")
+  return()
+endif()
+
+find_package(UbDiag CONFIG QUIET)
+if(NOT UbDiag_FOUND OR NOT TARGET UbDiag::ubdiag_lib)
+  message(
+    FATAL_ERROR
+      "MOONCAKE_ENABLE_UBDIAG=ON requires the UbDiag runtime and development "
+      "RPMs. Install the RPMs that provide libubdiag.so, the ubdiag CLI, and "
+      "UbDiagConfig.cmake before configuring Mooncake.")
+endif()
+set_property(TARGET UbDiag::ubdiag_lib PROPERTY IMPORTED_GLOBAL TRUE)
+
+get_target_property(_MOONCAKE_UBDIAG_TARGET_TYPE UbDiag::ubdiag_lib TYPE)
+if(NOT _MOONCAKE_UBDIAG_TARGET_TYPE STREQUAL "SHARED_LIBRARY")
+  message(
+    FATAL_ERROR "MOONCAKE_ENABLE_UBDIAG=ON requires a shared libubdiag.so. "
+                "Reinstall UbDiag with UBDIAG_BUILD_SHARED=ON.")
+endif()
+
+function(_mooncake_get_imported_location target output_variable)
+  get_target_property(_configs "${target}" IMPORTED_CONFIGURATIONS)
+  foreach(_config IN LISTS _configs)
+    string(TOUPPER "${_config}" _config_upper)
+    get_target_property(_location "${target}"
+                        "IMPORTED_LOCATION_${_config_upper}")
+    if(_location)
+      set("${output_variable}"
+          "${_location}"
+          PARENT_SCOPE)
+      return()
+    endif()
+  endforeach()
+
+  get_target_property(_location "${target}" IMPORTED_LOCATION)
+  set("${output_variable}"
+      "${_location}"
+      PARENT_SCOPE)
+endfunction()
+
+_mooncake_get_imported_location(UbDiag::ubdiag_lib
+                                MOONCAKE_UBDIAG_SYSTEM_LIBRARY)
+if(NOT MOONCAKE_UBDIAG_SYSTEM_LIBRARY)
+  message(FATAL_ERROR "The installed UbDiag package does not expose its "
+                      "shared-library location.")
+endif()
+get_filename_component(MOONCAKE_UBDIAG_SYSTEM_LIBRARY
+                       "${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}" REALPATH)
+get_filename_component(MOONCAKE_UBDIAG_LIBRARY_DIR
+                       "${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}" DIRECTORY)
+
+get_target_property(_MOONCAKE_UBDIAG_DEFINITIONS UbDiag::ubdiag_lib
+                    INTERFACE_COMPILE_DEFINITIONS)
+foreach(_definition UBDIAG_ENABLE_PERCENTILE UBDIAG_ENABLE_PERFLOG)
+  if(NOT _definition IN_LIST _MOONCAKE_UBDIAG_DEFINITIONS)
+    message(
+      FATAL_ERROR
+        "The installed UbDiag package does not provide ${_definition}. "
+        "Rebuild and reinstall the UbDiag RPM with percentile and PerfLog "
+        "enabled.")
+  endif()
+endforeach()
+
+get_filename_component(_MOONCAKE_UBDIAG_SYSTEM_PREFIX
+                       "${MOONCAKE_UBDIAG_LIBRARY_DIR}" DIRECTORY)
+unset(MOONCAKE_UBDIAG_SYSTEM_CLI)
+unset(MOONCAKE_UBDIAG_SYSTEM_CLI CACHE)
+find_program(
+  MOONCAKE_UBDIAG_SYSTEM_CLI
+  NAMES ubdiag
+  PATHS "${_MOONCAKE_UBDIAG_SYSTEM_PREFIX}/bin"
+  NO_DEFAULT_PATH)
+if(NOT MOONCAKE_UBDIAG_SYSTEM_CLI)
+  message(
+    FATAL_ERROR "The UbDiag SDK was found, but the ubdiag CLI is missing. "
+                "Install the matching UbDiag runtime RPM.")
+endif()
+
+find_program(_MOONCAKE_RPM_EXECUTABLE NAMES rpm)
+if(NOT _MOONCAKE_RPM_EXECUTABLE)
+  message(FATAL_ERROR "The rpm command is required to compare the UbDiag "
+                      "library and CLI versions.")
+endif()
+
+function(_mooncake_get_rpm_identity file_path output_variable)
+  execute_process(
+    COMMAND "${_MOONCAKE_RPM_EXECUTABLE}" -qf --qf
+            "%{VERSION}-%{RELEASE}.%{ARCH}" "${file_path}"
+    RESULT_VARIABLE _result
+    OUTPUT_VARIABLE _identity
+    ERROR_VARIABLE _error
+    OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE)
+  if(NOT _result EQUAL 0)
+    message(FATAL_ERROR "${file_path} is not provided by an installed RPM: "
+                        "${_error}")
+  endif()
+  set("${output_variable}"
+      "${_identity}"
+      PARENT_SCOPE)
+endfunction()
+
+_mooncake_get_rpm_identity("${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}"
+                           _MOONCAKE_UBDIAG_LIBRARY_IDENTITY)
+_mooncake_get_rpm_identity("${MOONCAKE_UBDIAG_SYSTEM_CLI}"
+                           _MOONCAKE_UBDIAG_CLI_IDENTITY)
+if(NOT "${_MOONCAKE_UBDIAG_LIBRARY_IDENTITY}" STREQUAL
+   "${_MOONCAKE_UBDIAG_CLI_IDENTITY}")
+  message(
+    FATAL_ERROR
+      "libubdiag.so and the ubdiag CLI come from different RPM versions: "
+      "${_MOONCAKE_UBDIAG_LIBRARY_IDENTITY} and "
+      "${_MOONCAKE_UBDIAG_CLI_IDENTITY}. Install one matching UbDiag RPM set.")
+endif()
+
+if(EXISTS "/etc/ubdiag/ubdiag.conf")
+  set(MOONCAKE_UBDIAG_SYSTEM_CONFIG "/etc/ubdiag/ubdiag.conf")
+else()
+  set(MOONCAKE_UBDIAG_SYSTEM_CONFIG "")
+endif()
+
+set(MOONCAKE_UBDIAG_LIBRARY_DIR
+    "${MOONCAKE_UBDIAG_LIBRARY_DIR}"
+    CACHE INTERNAL "System UbDiag library directory" FORCE)
+_mooncake_write_ubdiag_manifest(
+  "system" "${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}" "${MOONCAKE_UBDIAG_SYSTEM_CLI}"
+  "${MOONCAKE_UBDIAG_SYSTEM_CONFIG}")
+message(
+  STATUS "UbDiag: Layer 1 system RPM ${_MOONCAKE_UBDIAG_LIBRARY_IDENTITY}; "
+         "library=${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}; "
+         "CLI=${MOONCAKE_UBDIAG_SYSTEM_CLI}")
diff --git a/mooncake-integration/CMakeLists.txt b/mooncake-integration/CMakeLists.txt
index 42e3d1d97c..5bd064941b 100644
--- a/mooncake-integration/CMakeLists.txt
+++ b/mooncake-integration/CMakeLists.txt
@@ -107,7 +107,7 @@ if(WITH_STORE)
                       store/engram_store_py.cpp integration_utils.h)
   set_target_properties(store PROPERTIES INSTALL_RPATH "$ORIGIN")
 
-  find_package(UbDiag REQUIRED)
+  include(${CMAKE_SOURCE_DIR}/mooncake-common/FindUbDiag.cmake)
   target_include_directories(store PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/store)
   target_link_libraries(store PRIVATE UbDiag::ubdiag_lib)
 
diff --git a/mooncake-p2p-store/CMakeLists.txt b/mooncake-p2p-store/CMakeLists.txt
index 5b9980de90..ee815b79b9 100644
--- a/mooncake-p2p-store/CMakeLists.txt
+++ b/mooncake-p2p-store/CMakeLists.txt
@@ -1,8 +1,11 @@
 # Currently you have to manually execute makefile in the src subdirectory.
 add_custom_target(build_p2p_store DEPENDS transfer_engine)
 add_custom_command(
-    TARGET build_p2p_store
-    COMMAND bash build.sh ${CMAKE_CURRENT_BINARY_DIR} ${USE_ETCD} ${USE_REDIS} ${USE_HTTP} ${USE_ETCD_LEGACY} ${CMAKE_BINARY_DIR}
-    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-)
+  TARGET build_p2p_store
+  COMMAND
+    bash build.sh ${CMAKE_CURRENT_BINARY_DIR} ${USE_ETCD} ${USE_REDIS}
+    ${USE_HTTP} ${USE_ETCD_LEGACY} ${CMAKE_BINARY_DIR}
+    "${MOONCAKE_UBDIAG_ACTIVE_LAYER}" "${MOONCAKE_UBDIAG_LIBRARY_DIR}"
+  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  VERBATIM)
 set_property(TARGET build_p2p_store PROPERTY EXCLUDE_FROM_ALL FALSE)
diff --git a/mooncake-p2p-store/build.sh b/mooncake-p2p-store/build.sh
index 520227b0c2..081cf385cd 100644
--- a/mooncake-p2p-store/build.sh
+++ b/mooncake-p2p-store/build.sh
@@ -13,8 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-if [ "$#" -ne 6 ]; then
-    echo "Usage: $0 TARGET_PATH USE_ETCD USE_REDIS USE_HTTP USE_ETCD_LEGACY BUILD_DIR"
+if [ "$#" -ne 8 ]; then
+    echo "Usage: $0 TARGET_PATH USE_ETCD USE_REDIS USE_HTTP USE_ETCD_LEGACY BUILD_DIR UBDIAG_LAYER UBDIAG_LIB_DIR"
     exit 1
 fi
 
@@ -24,6 +24,8 @@ USE_REDIS=$3
 USE_HTTP=$4
 USE_ETCD_LEGACY=$5
 BUILD_DIR=$6
+UBDIAG_LAYER=$7
+UBDIAG_LIB_DIR=$8
 
 cd "src/p2pstore"
 if [ $? -ne 0 ]; then
@@ -35,7 +37,11 @@ EXT_LDFLAGS="-L$BUILD_DIR/mooncake-transfer-engine/src"
 EXT_LDFLAGS+=" -L$BUILD_DIR/mooncake-transfer-engine/src/common/base"
 EXT_LDFLAGS+=" -L$BUILD_DIR/mooncake-common"
 EXT_LDFLAGS+=" -L$BUILD_DIR/mooncake-common/src"
-EXT_LDFLAGS+=" -ltransfer_engine -lubdiag -lbase -lasio -lstdc++ -lnuma -lglog -libverbs -lmlx5 -ljsoncpp -lmooncake_common -lm"
+EXT_LDFLAGS+=" -ltransfer_engine -lbase -lasio -lstdc++ -lnuma -lglog -libverbs -lmlx5 -ljsoncpp -lmooncake_common -lm"
+
+if [ "$UBDIAG_LAYER" = "system" ]; then
+    EXT_LDFLAGS+=" -L$UBDIAG_LIB_DIR -lubdiag"
+fi
 
 if [ -d "/usr/local/cuda/lib64/stubs" ]; then
     EXT_LDFLAGS+=" -L/usr/local/cuda/lib64/stubs"
diff --git a/mooncake-store/src/CMakeLists.txt b/mooncake-store/src/CMakeLists.txt
index c6328b703e..f541551d74 100644
--- a/mooncake-store/src/CMakeLists.txt
+++ b/mooncake-store/src/CMakeLists.txt
@@ -251,7 +251,7 @@ target_link_libraries(
   PRIVATE transfer_engine)
 
 # UbDiag instrumentation
-find_package(UbDiag REQUIRED)
+include(${CMAKE_SOURCE_DIR}/mooncake-common/FindUbDiag.cmake)
 target_link_libraries(mooncake_store PRIVATE UbDiag::ubdiag_lib)
 target_include_directories(mooncake_store PRIVATE
     ${CMAKE_CURRENT_SOURCE_DIR}/../../mooncake-integration/store)
diff --git a/mooncake-transfer-engine/src/CMakeLists.txt b/mooncake-transfer-engine/src/CMakeLists.txt
index 80c1cd0a3b..79eb64ce9b 100644
--- a/mooncake-transfer-engine/src/CMakeLists.txt
+++ b/mooncake-transfer-engine/src/CMakeLists.txt
@@ -1,5 +1,5 @@
 file(GLOB ENGINE_SOURCES "*.cpp")
-find_package(UbDiag REQUIRED)
+include(${CMAKE_SOURCE_DIR}/mooncake-common/FindUbDiag.cmake)
 add_subdirectory(common)
 add_subdirectory(transport)
 
diff --git a/scripts/build_rpm.sh b/scripts/build_rpm.sh
index e41b241d26..85f05826ca 100755
--- a/scripts/build_rpm.sh
+++ b/scripts/build_rpm.sh
@@ -10,10 +10,17 @@ set -x
 
 # Get build directory from environment variable or argument
 BUILD_DIR="${BUILD_DIR:-${1:-build}}"
-BUILD_DIR_ABS="$(pwd)/${BUILD_DIR}"
+if [[ "${BUILD_DIR}" = /* ]]; then
+    BUILD_DIR_ABS="${BUILD_DIR}"
+else
+    BUILD_DIR_ABS="$(pwd)/${BUILD_DIR}"
+fi
 
 # Get output directory from environment variable or argument
 OUTPUT_DIR="${OUTPUT_DIR:-${2:-rpm-output}}"
+if [[ "${OUTPUT_DIR}" != /* ]]; then
+    OUTPUT_DIR="$(pwd)/${OUTPUT_DIR}"
+fi
 
 # Detect current host architecture
 HOST_ARCH=$(uname -m)
@@ -50,6 +57,12 @@ rm -rf ${OUTPUT_DIR}/
 build_rpm_for_platform() {
     local PLATFORM=$1
     local LIB_DIR="lib64"
+    local BUILDROOT=""
+    local UBDIAG_CONFIG_RPM_FILE=""
+    local MOONCAKE_UBDIAG_LAYER=""
+    local MOONCAKE_UBDIAG_SYSTEM_LIBRARY=""
+    local MOONCAKE_UBDIAG_SYSTEM_CLI=""
+    local MOONCAKE_UBDIAG_SYSTEM_CONFIG=""
     
     echo "Building RPM for platform: ${PLATFORM}"
     
@@ -65,7 +78,8 @@ build_rpm_for_platform() {
     
     # Create RPM build directory structure for this platform
     mkdir -p rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
-    mkdir -p rpmbuild/BUILDROOT/${PACKAGE_NAME}-${PACKAGE_VERSION}-${PACKAGE_RELEASE}.${PLATFORM}
+    BUILDROOT="rpmbuild/BUILDROOT/${PACKAGE_NAME}-${PACKAGE_VERSION}-${PACKAGE_RELEASE}.${PLATFORM}"
+    mkdir -p "${BUILDROOT}"
     
     # Create target directories in BUILDROOT
     mkdir -p rpmbuild/BUILDROOT/${PACKAGE_NAME}-${PACKAGE_VERSION}-${PACKAGE_RELEASE}.${PLATFORM}/{usr/{bin,${LIB_DIR},include},etc/mooncake}
@@ -76,12 +90,22 @@ build_rpm_for_platform() {
     echo "Copying executables..."
     
     # Determine build subdirectory based on platform
-    local PLATFORM_BUILD_DIR="${BUILD_DIR}"
+    local PLATFORM_BUILD_DIR="${BUILD_DIR_ABS}"
     if [ "${PLATFORM}" != "${HOST_ARCH}" ]; then
         # Cross-compilation path
-        PLATFORM_BUILD_DIR="${BUILD_DIR}-${PLATFORM}"
+        PLATFORM_BUILD_DIR="${BUILD_DIR_ABS}-${PLATFORM}"
         echo "Cross-compilation detected, looking in ${PLATFORM_BUILD_DIR}"
     fi
+
+    source "${PLATFORM_BUILD_DIR}/mooncake_ubdiag.env"
+    case "${MOONCAKE_UBDIAG_LAYER}" in
+        mock|system)
+            ;;
+        *)
+            echo "Error: Unknown Mooncake UbDiag layer: ${MOONCAKE_UBDIAG_LAYER}"
+            return 1
+            ;;
+    esac
     
     # mooncake_master
     if [ -f ${PLATFORM_BUILD_DIR}/mooncake-store/src/mooncake_master ]; then
@@ -170,6 +194,27 @@ build_rpm_for_platform() {
     else
         echo "Warning: store.so not found in ${PLATFORM_BUILD_DIR}, skipping..."
     fi
+
+    if [ "${MOONCAKE_UBDIAG_LAYER}" = "system" ]; then
+        local ubdiag_library_dir
+        local ubdiag_library
+
+        cp "${MOONCAKE_UBDIAG_SYSTEM_CLI}" "${BUILDROOT}/usr/bin/ubdiag"
+        ubdiag_library_dir="$(dirname "${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}")"
+        for ubdiag_library in "${ubdiag_library_dir}"/libubdiag.so*; do
+            if [ "$(readlink -f "${ubdiag_library}")" = \
+                 "${MOONCAKE_UBDIAG_SYSTEM_LIBRARY}" ]; then
+                cp -a "${ubdiag_library}" "${BUILDROOT}/usr/${LIB_DIR}/"
+            fi
+        done
+
+        if [ -n "${MOONCAKE_UBDIAG_SYSTEM_CONFIG}" ]; then
+            mkdir -p "${BUILDROOT}/etc/ubdiag"
+            cp "${MOONCAKE_UBDIAG_SYSTEM_CONFIG}" \
+                "${BUILDROOT}/etc/ubdiag/ubdiag.conf"
+            UBDIAG_CONFIG_RPM_FILE="%config(noreplace) /etc/ubdiag/ubdiag.conf"
+        fi
+    fi
     
     # -------------------------------------------------------------------------
     # Copy header files (only core headers for real_client and dummy_client)
@@ -313,21 +358,11 @@ Requires(pre):  /usr/sbin/ldconfig
 ${PACKAGE_DESCRIPTION}
 
 %files
-/usr/bin/mooncake_master
-/usr/bin/mooncake_client
-/usr/bin/stress_cluster_bench
-/usr/bin/transfer_engine_bench
-/usr/${LIB_DIR}/libmooncake_store.so
-/usr/${LIB_DIR}/libtransfer_engine.so
-/usr/${LIB_DIR}/libmooncake_common.so
-/usr/${LIB_DIR}/libasio.so
-/usr/${LIB_DIR}/libetcd_wrapper.so
-/usr/${LIB_DIR}/libmooncake_engine.so
-/usr/${LIB_DIR}/libmooncake_store_python.so
-/usr/include/mooncake/*.h
-/usr/include/mooncake/*.hpp
-/etc/mooncake/master.yaml
-/etc/mooncake/master.json
+/usr/bin/*
+/usr/${LIB_DIR}/*
+/usr/include/mooncake/*
+%config(noreplace) /etc/mooncake/*
+${UBDIAG_CONFIG_RPM_FILE}
 
 %post
 /sbin/ldconfig
@@ -356,8 +391,9 @@ EOF
     
     # Build the RPM
     rpmbuild -bb \
+        --buildroot "$(pwd)/${BUILDROOT}" \
         --define "_topdir $(pwd)/rpmbuild" \
-        --define "_rpmdir $(pwd)/${OUTPUT_DIR}" \
+        --define "_rpmdir ${OUTPUT_DIR}" \
         rpmbuild/SPECS/${PACKAGE_NAME}-${PLATFORM}.spec
     
     # Move RPM to platform-specific directory
@@ -398,4 +434,4 @@ echo "Created RPM files:"
 ls -la ${OUTPUT_DIR}/*.rpm 2>/dev/null || echo "No RPM files created"
 
 # Cleanup
-rm -rf rpmbuild/
\ No newline at end of file
+rm -rf rpmbuild/