xrpld
Loading...
Searching...
No Matches
Sanitizer Configuration for Xrpld

This document explains how to properly configure and run sanitizers (AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer) with the xrpld project. Corresponding suppression files are located in the sanitizers/suppressions directory.

‍[!CAUTION] Do not mix Address and Thread sanitizers - they are incompatible. Also, we don't yet support MSVC sanitizers, so this is only for Clang/GCC builds.

  • Sanitizer Configuration for Xrpld
    • Building with Sanitizers
      • Summary
      • Build steps:
        • Install dependencies
    • Running Tests with Sanitizers
      • AddressSanitizer (ASAN)
      • ThreadSanitizer (TSan)
      • LeakSanitizer (LSan)
      • UndefinedBehaviorSanitizer (UBSan)
    • Suppression Files
      • `asan.supp`
      • `lsan.supp`
      • `ubsan.supp`
      • `tsan.supp`
      • `sanitizer-ignorelist.txt`
    • Troubleshooting
      • "ASAN is ignoring requested \_\_asan_handle_no_return" warnings
      • Sanitizer Mismatch Errors
    • References

Building with Sanitizers

Summary

Follow the same instructions as mentioned in BUILD.md but with the following changes:

  1. Make sure you have a clean build directory.
  2. Set the SANITIZERS environment variable before calling conan install. Only set it once. Example: export SANITIZERS=address,undefinedbehavior
  3. Use --profile:all sanitizers with Conan to build dependencies with sanitizer instrumentation.

‍[!NOTE] Building with sanitizer-instrumented dependencies is slower but produces fewer false positives.

  1. Set ASAN_OPTIONS, LSAN_OPTIONS, UBSAN_OPTIONS and TSAN_OPTIONS environment variables to configure sanitizer behavior when running executables. More details below.

Build steps:

cd /path/to/rippled
rm -rf .build
mkdir .build
cd .build

Install dependencies

The SANITIZERS environment variable is used during conan install command.

SANITIZERS=address,undefinedbehavior conan install .. --output-folder . --build missing --settings build_type=Debug --profile:all sanitizers

Proceed with the rest of the build instructions as mentioned in BUILD.md.

Running Tests with Sanitizers

AddressSanitizer (ASAN)

IMPORTANT: ASAN with Boost produces many false positives. Use these options:

export ASAN_OPTIONS="include=sanitizers/suppressions/runtime-asan-options.txt:suppressions=sanitizers/suppressions/asan.supp"
export LSAN_OPTIONS="include=sanitizers/suppressions/runtime-lsan-options.txt:suppressions=sanitizers/suppressions/lsan.supp"
# Run tests
./xrpld --unittest --unittest-jobs=5

Why detect_container_overflow=0?

  • Boost intrusive containers (used in AgedUnorderedContainer) trigger false positives
  • Boost context switching (used in Workers.cpp) confuses ASAN's stack tracking
  • Since we usually don't build Boost (because we don't want to instrument Boost and detect issues in Boost code) with ASAN but use Boost containers in ASAN instrumented xrpld code, it generates false positives.
  • Building dependencies with ASAN instrumentation reduces false positives. But we don't want to instrument dependencies like Boost with ASAN because it is slow (to compile as well as run tests) and not necessary.
  • See: https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow
  • More such flags are detailed here

ThreadSanitizer (TSan)

export TSAN_OPTIONS="include=sanitizers/suppressions/runtime-tsan-options.txt:suppressions=sanitizers/suppressions/tsan.supp"
# Run tests
./xrpld --unittest --unittest-jobs=5

More details here.

LeakSanitizer (LSan)

LSan is automatically enabled with ASAN. To disable it:

export ASAN_OPTIONS="detect_leaks=0"

More details here.

UndefinedBehaviorSanitizer (UBSan)

export UBSAN_OPTIONS="include=sanitizers/suppressions/runtime-ubsan-options.txt:suppressions=sanitizers/suppressions/ubsan.supp"
# Run tests
./xrpld --unittest --unittest-jobs=5

More details here.

Suppression Files

[!NOTE] Attached files contain more details.

<a href="../../sanitizers/suppressions/asan.supp" ><tt>asan.supp</tt></a>

  • Purpose: Suppress AddressSanitizer (ASAN) errors only
  • Format: interceptor_name:<pattern> where pattern matches file names. Supported suppression types are:
    • interceptor_name
    • interceptor_via_fun
    • interceptor_via_lib
    • odr_violation
  • More info: AddressSanitizer
  • Note: Cannot suppress stack-buffer-overflow, container-overflow, etc.

<a href="../../sanitizers/suppressions/lsan.supp" ><tt>lsan.supp</tt></a>

  • Purpose: Suppress LeakSanitizer (LSan) errors only
  • Format: leak:<pattern> where pattern matches function/file names
  • More info: LeakSanitizer

<a href="../../sanitizers/suppressions/ubsan.supp" ><tt>ubsan.supp</tt></a>

  • Purpose: Suppress undefinedbehaviorSanitizer errors
  • Format: <error_type>:<pattern> (e.g., unsigned-integer-overflow:protobuf)
  • Covers: Intentional overflows in sanitizers/suppressions libraries (protobuf, gRPC, stdlib)
  • More info UBSan suppressions.

<a href="../../sanitizers/suppressions/tsan.supp" ><tt>tsan.supp</tt></a>

  • Purpose: Suppress ThreadSanitizer data race warnings
  • Format: race:<pattern> where pattern matches function/file names
  • More info: ThreadSanitizer suppressions

<a href="../../sanitizers/suppressions/sanitizer-ignorelist.txt" ><tt>sanitizer-ignorelist.txt</tt></a>

  • Purpose: Compile-time ignorelist for all sanitizers
  • Usage: Passed via -fsanitize-ignorelist=absolute/path/to/sanitizer-ignorelist.txt
  • Format: <level>:<pattern> (e.g., src:Workers.cpp)

Troubleshooting

"ASAN is ignoring requested \_\_asan_handle_no_return" warnings

These warnings appear when using Boost context switching and are harmless. They indicate potential false positives.

Sanitizer Mismatch Errors

If you see undefined symbols like ___tsan_atomic_load when building with ASAN:

Problem: Dependencies were built with a different sanitizer than the main project.

Solution: Rebuild everything with the same sanitizer:

rm -rf .build
# Then follow the build instructions above

Then review the log files: asan.log.*, ubsan.log.*, tsan.log.*

References

Generated by doxygen 1.9.8