Basic Usage Guide#

Learn how to run NVDebug collections and understand the results.

Command Structure#

The basic NVDebug command follows this pattern:

nvdebug [OPTIONS]

Required Options:

  • -i, –ip - BMC IP address

  • -u, –user - BMC username with administrative privileges

  • -p, –password - BMC administrator password

  • -t, –platform - Platform type (arm64, x86_64, DGX, HGX-HMC, NVSwitch, PowerShelf)

  • -b, –baseboard - Baseboard type (use quotes for names with spaces)

Common Options:

  • -v, –verbose - Detailed output

  • -o, –outdir - Output directory

  • -C, –config - Configuration file

Basic Examples#

The examples below manually select the baseboard and platform. NVDebug will automatically detect the baseboard and platform if not specified. If NVDebug is unable to detect the baseboard and platform, it will prompt the user to select the baseboard and platform.

Simple Collection:

# ARM64 system collection
nvdebug -i 192.168.1.100 -u admin -p password123 -t "arm64" \
        -b "GB200 NVL"

# With output directory
nvdebug -i 192.168.1.100 -u admin -p password123 -t "arm64" \
        -b "GB200 NVL" -o /path/to/output

# With verbose output
nvdebug -i 192.168.1.100 -u admin -p password123 -t "arm64" \
        -b "GB200 NVL" -v

Remote Mode:

# Remote collection with host access
nvdebug -i 192.168.1.100 -u admin -p password123 -t "arm64" \
        -I 192.168.1.50 -U host_user -H host_password \
        -b "GB200 NVL"

# With baseboard specification
nvdebug -i 192.168.1.100 -u admin -p password123 -t "arm64" \
        -b "GB200 NVL"

Operation Modes#

Remote Mode (Default)#

Collect from a remote machine with access to both BMC and host:

nvdebug -i <BMC_IP> -u <BMC_USER> -p <BMC_PASS> -t <PLATFORM> \
        -I <HOST_IP> -U <HOST_USER> -H <HOST_PASS>

Local Mode#

Run directly on the target system:

# With BMC access
nvdebug -i <BMC_IP> -u <BMC_USER> -p <BMC_PASS> -t <PLATFORM> --local

# Without BMC access (host-only)
nvdebug -t <PLATFORM> --local

Understanding Output#

The output directory contains several key components:

Output Directory Structure:

After running NVDebug, you’ll find output in a timestamped directory:

nvdebug_logs_31_07_2025_12_01_49/
├── .log_signature.txt
├── .nvdebug_stdout.log
├── reports/
│   ├── index.html
│   ├── file_map.html
│   ├── status_complete.html
│   ├── status_error.html
│   ├── status_partial.html
│   └── status_skipped.html
└── <dut_name>/
    ├── config.json
    ├── dut_config.json
    ├── Execution_Summary_Report.txt
    ├── nvdebug_runtime_output.txt
    ├── nvdebug_runtime_output_structured.json
    ├── error_logs/
    ├── healthcheck/
    ├── .metadata/
    ├── redfish/
    │   ├── Redfish_R1_system_event_log/
    │   ├── Redfish_R2_manager_existing_log_dump/
    │   ├── Redfish_R10_chassis_info.json
    │   ├── Redfish_R11_chassis_expand_query.json
    │   └── ...
    └── ssh/
        ├── SSH_S2_bmc_dmesg/
        ├── SSH_S3_network_info/
        ├── SSH_S5_bmc_list_kernel_modules/
        └── ...

Main Output Files:

  • Execution_Summary_Report.txt - Status summary for all collectors

  • nvdebug_runtime_output.txt - Detailed runtime information

  • nvdebug_runtime_output_structured.json - Detailed runtime information in structured format

  • config.json - Configuration used for this run

  • dut_config.json - Device-specific configuration

  • .log_signature.txt - Log integrity verification

  • .nvdebug_stdout.log - Standard output from NVDebug

Directory Structure:

  • reports/ - HTML reports including:

    • index.html - Main report page

    • file_map.html - File organization map

    • status_*.html - Status-specific summaries (complete, error, partial, skipped, unknown)

  • <dut_name>/ - DUT-specific data with numbered collections (D1, D2, etc.)

    • healthcheck/ - System health check data

    • host/ - Host-collected data with numbered sessions (H1, H2, etc.)

    • ipmi/ - IPMI-collected data with numbered sessions (I1, I2, etc.)

    • redfish/ - Redfish API data with numbered collections (R1, R2, etc.)

    • ssh/ - BMC SSH-collected data with numbered sessions (S1, S2, etc.)

    • error_logs/ - Detailed error logs with specific naming patterns

    • .metadata/ - Collection metadata

Interpreting Results#

Execution Summary Report

The Execution_Summary_Report.txt provides a comprehensive overview of all collectors:

Collection Name                          Execution Status        Log Path
bmc_dmesg                                Complete                /ssh/SSH_S2_bmc_dmesg/SSH_S2_bmc_dmesg.txt
bmc_power_status                         Error                   /error_logs/s15_bmc_power_status_errors.txt
chassis_certificates                     Partial                 /redfish/Redfish_R26_chassis_certificates/...
channel_info                             Skipped                 /error_logs/i13_channel_info_errors.txt

Status Types:

  • Complete: Collector ran successfully, data available

  • Error: Collector failed, check error_logs for details

  • Partial: Some data collected but with errors

  • Skipped: Collector was not applicable or disabled

Key Files to Review:

  1. For Complete Collectors: Check the specified log path for collected data

  2. For Error/Skipped Collectors: Review corresponding error files in error_logs/

  3. For Partial Collectors: Check both the data files and error logs

HTML Reports:

Open reports/index.html for a visual summary of all collectors and their status:

<browser> reports/index.html

Collection Levels#

Default Collection (No Flag):

All necessary collectors for the platform.

nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX"

Verbose Collection (-V):

Additional verbose log collectors.

nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -V

Comprehensive Collection (-VV):

All collectors including optional ones that may take hours.

nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -VV

Custom Collection#

Run Specific Collectors:

# Run specific collectors by CID
nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -S R1 R2 R3

# Run collectors by group
nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -g Redfish IPMI

Override Platform Restrictions:

# Run collectors not normally available for this platform
nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -S R1 R2 -e

Common Log Collection:

# Collect only common logs (skip platform-specific)
nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -c

Output Control#

By default, NVDebug logs are compressed into a zip file in the output directory. If the logs are above the size threshold (200MB by default) the zip is split into multiple files for easy upload to NVIDIA Support. Log splitting is enabled by default. The threshold defaults to 200MB as well.

Skip Zip Creation:

nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -z

Skip Zip Splitting:

nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" -Z

Custom Zip Split Threshold:

nvdebug -i 192.168.1.100 -u admin -p password123 -t "DGX" --zipsplit_threshold 500

Tip

Pro Tip: Use the -v (verbose) flag when learning to see detailed information about what NVDebug is doing during collection.

Note

Help: Run NVDebug –help to see all available options, or nvdebug -l to list supported collectors for your platform.