Cluster Bring-Up and Validation
From pallets on the data-center floor to "ready for users": every phase, every test, what each test proves, and how to troubleshoot when something fails. Organized against the official NCP-AII exam blueprint: every objective has its own section, and a tracker shows your coverage weighted by domain.
NCP-AII exam blueprint: what's tested and where to study it
This guide is organized around the official NVIDIA-Certified Professional: AI Infrastructure (NCP-AII) exam blueprint. The exam checks that you can deploy, configure, and validate NVIDIA AI infrastructure: GPU servers, networking, storage, and the cluster software that runs on them. Responsibilities listed on the page are infrastructure deployment, platform and cluster management, testing and performance validation, troubleshooting and optimization, and monitoring, security, and scalability.
| Exam detail | Value (from the official page) |
|---|---|
| Level | Professional (intermediate) |
| Length | 2 hours, about 70–75 questions |
| Scoring | Pass / fail |
| Delivery | Online, remotely proctored, through a Certiverse account |
| Validity | 2 years; recertify by retaking the exam |
| Recommended background | 2–3 years deploying, configuring, and validating GPU servers and AI clusters; data-center networking, storage, power, cooling, cabling; NVIDIA GPUs, BlueField DPUs, firmware, drivers, OSes, and cluster management tools |
| Domain | Weight | ≈ Questions (of 70–75) | What it's about |
|---|---|---|---|
| 1. System and Server Bring-Up | 31% | 22–23 | Rack, power, cooling, BMC/OOB/TPM, firmware (incl. HGX), cables and transceivers, installing GPUs and servers, hardware validation, third-party storage setup |
| 2. Physical Layer Management | 5% | 3–4 | BlueField network platform, MIG |
| 3. Control Plane Installation and Configuration | 19% | 13–14 | BCM + HA, OS, categories and interfaces, Slurm/Enroot/Pyxis, GPU and DOCA drivers, Container Toolkit, Docker with GPUs, NGC CLI |
| 4. Cluster Test and Verification | 33% | 23–25 | Stress tests, HPL, NCCL (single-node, E/W, burn-in), NeMo burn-in, cable signal quality and correctness, switch/BlueField/transceiver firmware, ClusterKit, storage tests |
| 5. Troubleshooting and Optimization | 12% | 8–9 | Finding and replacing faulty GPUs, cards, fans, PSUs; AMD and Intel server tuning; storage optimization |
Objective tracker
Every official objective, with the sections that cover it. Tick objectives as you study them. Progress is saved in this browser only.
Context: what an "AI factory" is
An AI factory is NVIDIA's name for a data center built to produce AI: trained models and inference tokens, measured by output such as time-to-train and tokens per second. It's a full stack (facility, compute, fabrics, storage, management, software) built from validated reference architectures like DGX BasePOD and DGX SuperPOD, not a product you install. This guide covers the build and validate (Day 1) stage of its lifecycle.
The design side lives in the AI factory architecture guide: BasePOD vs SuperPOD vs Enterprise RAs, scalable units, the four networks, rail-optimized topology, sizing math, and the lifecycle and productivity metrics.
1. The big picture: the 3 golden rules
- Bottom-up. Validate each layer before the one that depends on it: power and cables → firmware → OS → GPUs → NVLink → InfiniBand → NCCL → storage → scheduler → real workloads. A failure high up is almost always caused by an untested layer underneath.
- Small to large. One GPU → one node → a pair of nodes → a rack → the whole cluster. If you start with a 128-node test and it's slow, you have no idea where the problem is.
- Measure against a baseline. Every test needs a pass number (expected bandwidth, diagnostics PASS,
#wrong = 0, HPL efficiency). Record "golden" results at handover so future problems can be compared against them.
2. The layer model: what can break, and what tests it
| Layer | Typical failures | Primary test tools |
|---|---|---|
| Facility (power, cooling) | Tripped PDUs, overheating, power capping | BMC sensors, ipmitool sdr, Redfish, DCGM thermal/power fields |
| Hardware / firmware | Mismatched BIOS, BMC, NIC, GPU, NVSwitch firmware; dead PSU or fan | BMC inventory, nvsm show health (DGX), firmware update tools |
| OS / provisioning | Wrong image, PXE failure, missing packages | BCM (cmsh, Base View), node status |
| GPU hardware | Bad memory (ECC), GPU fell off bus, overheating | nvidia-smi, DCGM diagnostics |
| Intra-node fabric (NVLink / NVSwitch) | Fabric Manager down, NVLink errors | nvidia-smi topo -m, nvidia-smi nvlink -s, DCGM, single-node nccl-tests |
| Inter-node fabric (InfiniBand) | No subnet manager, links down or degraded, bad cables, routing | ibstat, ibdiagnet, UFM, perftest (ib_write_bw) |
| Communication stack (NCCL, GDR) | Socket fallback, one HCA in use, no GPUDirect RDMA | Multi-node nccl-tests with NCCL_DEBUG=INFO |
| Storage | Low throughput, mount issues, GDS not working | fio, gdsio, gdscheck |
| Scheduler / containers | Nodes DOWN, munge errors, container can't see IB | sinfo, srun, pyxis/enroot test jobs |
| Whole system | Instability under sustained load, thermal throttling, intermittent errors | HPL / HPL-MxP, real training jobs, multi-day burn-in |
3. The four networks of an AI cluster 1.2
Many bring-up questions test whether you know which network is involved. A DGX SuperPOD has four separate fabrics: compute (GPU-to-GPU, NCCL), storage (datasets and checkpoints), in-band management (SSH, PXE, Slurm, NFS home directories), and out-of-band (BMCs). Hardware per network, BasePOD and GB200 differences, and a traffic-mapping exercise are in AI factory architecture: the four networks.
0Physical install, power, cooling, cabling 1.11.51.8
- Site readiness: rack power capacity (a DGX H100 draws about 10.2 kW at maximum), cooling, floor loading, PDUs, redundant power feeds.
- Racking and power-on: confirm every PSU is green and no fans have failed.
- Cabling against the cabling plan: each DGX's compute ports go to the correct leaf switch (rail-optimized: port/rail i on every node goes to leaf i), plus the storage, in-band, and BMC cables.
- Label everything. Most "mysterious" fabric problems later turn out to be swapped or bad cables.
ibnetdiscover / ibdiagnet topology checks).1Firmware and BMC / out-of-band 1.31.4
- Configure BMC IP addresses and credentials on the out-of-band network. Test remote power and console with
ipmitoolor Redfish. - Bring all firmware to one validated set: BIOS/UEFI, BMC, GPU VBIOS, NVSwitch, ConnectX NIC firmware, and SSD firmware. On DGX, NVIDIA provides a firmware update container/tool. Mismatched firmware between nodes causes inconsistent, hard-to-debug behavior.
- BIOS settings: boot order (PXE on the provisioning NIC first for BCM-managed nodes), and performance settings recommended by NVIDIA.
ipmitool -I lanplus -H <bmc-ip> -U admin -P *** chassis power status
ipmitool -I lanplus -H <bmc-ip> -U admin -P *** sdr # sensors: temps, fans, PSUs
nvsm show health # DGX: overall system health
nvsm show firmware # DGX: component firmware versions (if available)
2Head node, BCM, provisioning 3.13.23.3
- Install Base Command Manager on the head node (usually two head nodes for high availability).
- Define networks, software images (DGX OS based), and categories (for example
dgx-h100). Register nodes by MAC address or switch port. - Nodes PXE boot from the head node, the node installer syncs the image to local disk, and the node boots.
- The centralized model applies: change the image or category, not individual nodes (see the earlier BCM guides).
cmsh -c "device; list" # all nodes
cmsh -c "device; status" # UP / DOWN / installing
cmsh -c "softwareimage; list"
cmsh -c "category; list"
2b. bcm-pod-setup: one-time BasePOD configuration
After BCM is installed on the head node, NVIDIA provides bcm-pod-setup to apply the DGX BasePOD / SuperPOD reference configuration in one pass, instead of configuring everything by hand in cmsh. It sets up the cluster-wide basics: networks (internal/provisioning, InfiniBand compute, IPMI/BMC), DGX node categories and software images, kernel parameters, and related settings.
| Question | Answer |
|---|---|
| When? | Once, during initial cluster configuration, right after the BCM head node install and before nodes go into production. |
| Where? | On the head node. It writes into BCM's central configuration (networks, categories, images), and nodes receive the result through normal provisioning. It's not run on each compute node. |
| Limitation | It's not a maintenance or "reset" tool. Re-running it on a deployed cluster can overwrite customized networks, categories, and kernel or image settings, and disrupt running workloads. |
| After deployment, use… | cmsh / Base View to change networks, categories, and software images, then sync or reprovision nodes. |
bcm-pod-setup as the builder's setup wizard for a new house: run once to lay out the wiring. After people move in, you don't re-run the wizard to change a light switch, because it would rewire the whole house. You make targeted changes (cmsh) instead.bcm-pod-setup should be re-run after reboots, run on every node, or used to "safely reset" a production cluster are wrong. The correct pattern: initial configuration only, not after the cluster is deployed.3Software stack on compute nodes 3.43.5
| Component | Why it matters | Quick check |
|---|---|---|
| NVIDIA driver | Everything GPU-related | nvidia-smi |
| Fabric Manager | Required on NVSwitch systems. Its version must match the driver version. Without it, CUDA apps fail or can't use NVLink. | systemctl status nvidia-fabricmanager |
| nvidia-persistenced | Keeps the driver initialized, for faster job start | systemctl status nvidia-persistenced |
| MLNX_OFED / DOCA-OFED | InfiniBand drivers and tools | ofed_info -s, ibstat |
| nvidia-peermem | GPUDirect RDMA (NIC ↔ GPU memory directly) | lsmod | grep nvidia_peermem |
| CUDA toolkit / NCCL / HPC-X (MPI) | Running tests and workloads | nvcc --version, mpirun --version |
| DCGM | GPU health, diagnostics, monitoring | systemctl status nvidia-dcgm, dcgmi discovery -l |
| Slurm (slurmd, munge) or Kubernetes | Scheduling | systemctl status slurmd munge |
| Container runtime (enroot + pyxis, or Docker/containerd + NVIDIA Container Toolkit) | Running NGC containers | Test container job |
| Time sync (chrony/NTP) | Munge authentication and logs need synced clocks | chronyc tracking |
| GPUDirect Storage (if planned) | Storage ↔ GPU memory DMA through cuFile | lsmod | grep nvidia_fs, gdscheck.py -p |
Turning each feature on: install, enable, prove
Exam questions often give a feature and ask for the missing step, or describe a step and ask what's still missing. Each row is the minimum sequence; the linked guide has the detail. On BCM, packages and modprobe files go in the software image and kernel parameters go in the category.
| Feature | Prerequisites | Turn it on | Prove it | Gotcha |
|---|---|---|---|---|
| Fabric Manager (NVSwitch systems) | Driver installed | apt install nvidia-fabricmanager-<branch> (same version as the driver); systemctl enable --now nvidia-fabricmanager | nvidia-smi -q | grep -A2 -i fabric → State Completed, Status Success | Version mismatch means FM won't start. B200/B300 also need the NVLink stack (nvlsm, libnvsdm) updated with the driver (FM guide). |
| Persistence | Driver | systemctl enable --now nvidia-persistenced | nvidia-smi shows Persistence-M: On | The daemon is preferred over legacy nvidia-smi -pm 1 (nvidia-smi guide) |
| GPUDirect RDMA | Driver plus DOCA-OFED/MLNX_OFED; ACS disabled for P2P; NIC and GPU under the same PCIe switch | modprobe nvidia_peermem (persist it), or DMA-BUF with the open kernel modules and a recent kernel | lsmod | grep nvidia_peermem; NCCL log shows GDRDMA; ib_write_bw --use_cuda | Without it NCCL still works but stages through host memory, with lower bus bandwidth (NCCL guide) |
| GPUDirect Storage | IOMMU off/pt (x86), ACS off, storage transport drivers for NVMe/NVMe-oF/NFS over RDMA (not on DGX OS 6+), GDS-capable filesystem | apt install nvidia-gds; modprobe nvidia_fs; ext4 with explicit data=ordered or XFS, RAID 0; cufile.json if defaults don't fit | gdscheck.py -p shows nvfs/dmabuf/p2pdma (not just compat); gdsio -x 0 beats -x 1 | Compatibility mode hides failures (GDS procedure) |
| DCGM | Driver | apt install datacenter-gpu-manager; systemctl enable --now nvidia-dcgm | dcgmi discovery -l | Package names vary by version (DCGM guide) |
| Containers with GPUs (Docker/containerd) | Driver | Install nvidia-container-toolkit; nvidia-ctk runtime configure --runtime=docker; restart Docker | docker run --rm --gpus all nvcr.io/nvidia/cuda:<tag> nvidia-smi | Slurm clusters usually use Enroot + Pyxis instead (NGC guide) |
| MIG | MIG-capable GPU; drain jobs | nvidia-smi -i 0 -mig 1 (may need a GPU reset), then create GPU and compute instances (nvidia-smi mig -cgi … -C) | nvidia-smi -L lists MIG devices | The mode survives reboots, but instances don't unless recreated (nvidia-smi guide) |
| ECC | Data-center GPU | nvidia-smi -e 1 | nvidia-smi -q -d ECC: Current = Enabled | Takes effect only after a reboot or GPU reset (Pending vs Current) |
| vGPU with SR-IOV (KVM, Ampere and later) | BIOS VT-d/IOMMU, SR-IOV, ARI; vGPU Manager installed | /usr/lib/nvidia/sriov-manage -e <BDF|ALL>, then pick a vGPU type per VF | VFs visible in lspci -d 10de: | VFs disappear after a host reboot or driver reload (virtualization guide) |
| NIC SR-IOV (ConnectX) | BIOS SR-IOV/VT-d | mlxconfig -d <dev> set SRIOV_EN=1 NUM_OF_VFS=<n>, firmware reset, then echo <n> > /sys/class/net/<if>/device/sriov_numvfs | lspci | grep -i virtual, ip link show | mlxconfig changes need a firmware reset or reboot (MFT guide) |
| SHARP (in-network reductions) | SHARP-capable Quantum switches; SHARP enabled in the Subnet Manager (UFM) | NCCL SHARP plugin (HPC-X); NCCL_COLLNET_ENABLE=1 | NCCL log shows CollNet/SHARP in use; all-reduce bus bandwidth improves | No plugin or no SM support means silent fallback to ring/tree (NCCL guide) |
| Secure Boot with NVIDIA modules | Signed modules, or a MOK-enrolled key | Sign the DKMS modules (driver, nvidia_fs, nvidia_peermem, OFED) and enroll the key with mokutil --import; confirm at the reboot prompt | mokutil --sb-state; modules load (lsmod) | Every DKMS rebuild after a kernel update needs signing (Domain 1) |
4InfiniBand fabric bring-up 1.84.44.5
The Subnet Manager (SM)
An InfiniBand fabric needs a Subnet Manager to assign addresses (LIDs) and compute routes. Until an SM runs, ports stay in state Initializing and no traffic flows. In NVIDIA clusters the SM is usually run by UFM (Unified Fabric Manager) or on the switches. OpenSM is the open-source option.
Checks
ibstat # per port: State Active? Physical state LinkUp? Rate 400?
ibstatus # compact version
ibdev2netdev # map mlx5_X devices to interfaces and Up/Down
sminfo # is a subnet manager present?
iblinkinfo # every link in the fabric with speed/width
ibnetdiscover # discover topology (compare with cabling plan)
ibdiagnet # full fabric diagnostic: errors, speeds, topology, bad links
ibqueryerrors # ports with error counters above threshold
mlxlink -d mlx5_0 # deep link diagnostics: BER, cable info (needs mst)
| ibstat field | Healthy | Problem |
|---|---|---|
| State | Active | Initializing = no SM · Down = no link |
| Physical state | LinkUp | Polling / Disabled = cable, transceiver, or far end problem |
| Rate | 400 (NDR) | 200 or lower = degraded link (bad cable, wrong cable type, link width down) |
ibdiagnet reports no errors or warnings for symbol errors, link-downed counters, or speed/width mismatches.5Single-node validation (GPU health) 1.61.71.104.1
5a. Quick sanity with nvidia-smi
nvidia-smi -L # expect 8 GPUs on a DGX H100
nvidia-smi --query-gpu=index,name,driver_version,persistence_mode,ecc.mode.current,mig.mode.current,\
pstate,temperature.gpu,power.limit --format=csv
nvidia-smi -q -d ECC,ROW_REMAPPER # no uncorrectable errors, no pending remaps
nvidia-smi topo -m # GPUs NV18 to each other; each GPU PIX to its NIC
nvidia-smi nvlink -s # all links up
dmesg | grep -i xid # no XID errors
5b. DCGM diagnostics: the main per-node hardware test
dcgmi discovery -l # DCGM sees all GPUs (and NVSwitches)
dcgmi diag -r 3 # long diag: stress, memory, PCIe/NVLink bandwidth, power
dcgmi diag -r 4 # extended, for burn-in / acceptance
dcgmi diag -r 3 -j > /tmp/$(hostname)-diag.json # save results as evidence
Run these on every node (Slurm or pdsh can run them in parallel across nodes). Collect the results.
5c. DGX-specific health
nvsm show health # DGX System Management: overall health
nvsm dump health # collect a health/log bundle (for NVIDIA support)
Full coverage of NVSM commands, alerts, the object tree, and how NVSM compares to DCGM and the BMC: the NVSM guide.
6Single-node NCCL (NVLink) 4.3
For raw NVLink and PCIe copy bandwidth per GPU pair (nvbandwidth), link status, and NVLink errors, see the NVLink guide.
# One process, all 8 GPUs, NVLink/NVSwitch only
./all_reduce_perf -b 8 -e 8G -f 2 -g 8
./all_gather_perf -b 8 -e 8G -f 2 -g 8
./reduce_scatter_perf -b 8 -e 8G -f 2 -g 8
This uses no network at all, so it isolates NVLink, NVSwitch, Fabric Manager, and GPU P2P.
#wrong = 0, and similar results on every node. A node that's clearly below its peers is suspect.7Raw network tests (perftest) 4.44.10
Before involving NCCL, test the InfiniBand links themselves with the perftest tools. These measure the network directly, with no GPU or NCCL in the way.
# On node A (server side), for HCA mlx5_0
ib_write_bw -d mlx5_0 --report_gbits
# On node B (client side), pointing at node A
ib_write_bw -d mlx5_0 --report_gbits nodeA
# Latency
ib_write_lat -d mlx5_0 nodeA
# With GPU memory (GPUDirect RDMA path), if perftest was built with CUDA
ib_write_bw -d mlx5_0 --use_cuda=0 --report_gbits nodeA
Repeat for each rail (mlx5_0…mlx5_7) and across many node pairs. Scripts or vendor tools such as NVIDIA ClusterKit (part of HPC-X) can run all-pairs tests automatically. See the ClusterKit guide.
8Multi-node NCCL (the fabric end-to-end) 4.104.11
Now test the full communication path: GPU → NVLink → NIC → InfiniBand → NIC → GPU, through NCCL, exactly as training jobs use it.
Scale up step by step
- Pairs of nodes (2 × 8 = 16 GPUs): test many different pairs.
- Groups: a rack, or one scalable unit (SU).
- The full cluster.
# 2 nodes, Open MPI style
mpirun -np 16 -N 8 --host nodeA:8,nodeB:8 \
-x NCCL_DEBUG=INFO -x LD_LIBRARY_PATH \
./all_reduce_perf -b 8 -e 8G -f 2 -g 1
# Full cluster under Slurm (32 nodes)
srun -N 32 --ntasks-per-node=8 --gpus-per-node=8 --mpi=pmix \
./all_reduce_perf -b 8 -e 16G -f 2 -g 1
# Also test other collectives used by real workloads
srun ... ./all_gather_perf ... ; srun ... ./alltoall_perf ...
Check the logs
NET/IB : Using [0]mlx5_0 … [7]mlx5_7: all 8 compute HCAsvia NET/IB/x/GDRDMA: GPUDirect RDMA in use- Not
NET/Socket, and not onlymlx5_0 Init COMPLETEon all ranks
#wrong = 0, and no hangs. A big drop when scaling from a rack to the full cluster points to spine links, routing, or congestion.9Storage validation 1.114.145.5
df -h ; mount | grep -E "lustre|nfs|gpfs|wekafs" # filesystems mounted everywhere?
fio --name=seqread --rw=read --bs=1M --size=10G --numjobs=8 --direct=1 --directory=/mnt/data
fio --name=seqwrite --rw=write --bs=1M --size=10G --numjobs=8 --direct=1 --directory=/mnt/data
/usr/local/cuda/gds/tools/gdscheck -p # GPUDirect Storage support/config
/usr/local/cuda/gds/tools/gdsio -f /mnt/data/f -d 0 -w 8 -s 10G -i 1M -x 0 -I 0 # GDS read test
- Test one node, then many nodes at once (aggregate throughput is what training at scale needs).
- Check checkpoint write speed. Large models write huge checkpoints.
- Local NVMe RAID (
/raidon DGX) works as a fast cache. Test it too.
10Scheduler and containers 3.33.53.6
sinfo # all nodes idle (not down / drain)
scontrol show node dgx01 # GPUs (Gres=gpu:8), state, reason
srun -N 32 hostname # can a job reach every node?
srun -N 2 --gpus-per-node=8 nvidia-smi -L
munge -n | ssh dgx01 unmunge # munge auth works across nodes (same key, synced time)
srun --container-image=nvcr.io#nvidia/pytorch:24.05-py3 -N 2 --gpus-per-node=8 \
python -c "import torch; print(torch.cuda.device_count())" # pyxis/enroot container test
- Verify the GRES GPU config (
gres.conf) and cgroup GPU isolation. - Set up a prolog/epilog with quick health checks (
dcgmi diag -r 1ordcgmi health -c) that drain a node if the check fails. - Make sure containers can see InfiniBand devices (multi-node NCCL inside containers).
Kubernetes and NVIDIA Run:ai (the other scheduler path)
Slurm is the classic choice for training clusters, but many AI factories also (or instead) run Kubernetes, especially for inference, interactive notebooks, and mixed teams. NVIDIA Run:ai (NVIDIA acquired Run:ai in 2024) is a GPU orchestration layer that runs on top of Kubernetes. It adds the things plain Kubernetes is weak at for AI: team quotas, fair sharing of idle GPUs, queueing, gang scheduling of distributed jobs, and fractional GPUs.
| Slurm | Kubernetes (plain) | Run:ai on Kubernetes | |
|---|---|---|---|
| Unit of work | Batch job (sbatch / srun) | Pods / Jobs from containers | Workloads (training, inference, interactive workspaces) submitted to a project |
| GPU allocation | Whole GPUs (or MIG) via GRES | Whole GPUs via nvidia.com/gpu resource (or MIG) | Whole GPUs, MIG, or fractions of a GPU |
| Sharing between teams | Partitions, QOS, fair-share accounting | Namespaces + resource quotas (static) | Guaranteed quota per project/department, plus over-quota use of idle GPUs that can be preempted when the owner needs them back |
| Multi-node training | Native (srun -N) | Needs operators (for example PyTorch / MPI job operators) | Gang scheduling: all pods of a distributed job start together or not at all |
| Typical users | HPC and large training | Platform / inference teams | Shared enterprise GPU pools: research teams, notebooks, training, inference |
The stack, bottom to top:
- Kubernetes on the GPU nodes (BCM can deploy Kubernetes as well as Slurm).
- NVIDIA GPU Operator: installs and manages the driver (or uses the host's), container toolkit, device plugin (which advertises
nvidia.com/gpu), MIG manager, and DCGM exporter on every GPU node. - NVIDIA Network Operator (for multi-node training): exposes InfiniBand / RoCE devices to pods so NCCL can use RDMA.
- Run:ai: a cluster component (installed with Helm) that connects to the Run:ai control plane (hosted or self-hosted). Admins create departments and projects with GPU quotas; users submit work through the UI, the
runaiCLI, or the API.
# Validate the Kubernetes GPU layer before Run:ai
kubectl get pods -n gpu-operator # all GPU Operator pods Running / Completed
kubectl describe node dgx01 | grep nvidia.com/gpu # node advertises 8 GPUs (Capacity / Allocatable)
# One-GPU smoke test pod
cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata: { name: gpu-smoke }
spec:
restartPolicy: Never
containers:
- name: cuda
image: nvcr.io/nvidia/cuda:12.4.1-base-ubuntu22.04
command: ["nvidia-smi"]
resources: { limits: { nvidia.com/gpu: 1 } }
EOF
kubectl logs gpu-smoke # should print one GPU
Then validate Run:ai itself: the cluster shows as connected in the Run:ai UI, nodes and GPUs appear in its inventory, a test project with a quota can run a 1-GPU job, a distributed multi-node job starts all its workers together and gets RDMA (check NCCL_DEBUG=INFO shows NET/IB), and an over-quota job is preempted when the quota owner submits work.
nvidia.com/gpu advertised → smoke-test pod → Network Operator / RDMA → Run:ai projects and quotas.sbatch" points to Slurm.Full detail: the dedicated NVIDIA Run:ai guide (quotas, reclaim, gang scheduling, fractions vs MIG, CLI, troubleshooting).
nvidia-smi, multi-node pods use RDMA, and Run:ai shows the cluster connected with projects, quotas, and preemption working as designed.11Application benchmarks and burn-in 4.24.124.13
| Benchmark | What it stresses | Why run it |
|---|---|---|
| HPL (High-Performance Linpack), from NVIDIA's HPC-Benchmarks NGC container | FP64 compute + memory + communication, at full power, for a long time | The classic whole-system stress and performance test (the TOP500 benchmark). Shows thermal/power problems and slow nodes. |
| HPL-MxP (mixed precision) | Low-precision tensor core compute (closer to AI) | Checks AI-relevant compute throughput |
| HPCG | Memory bandwidth and sparse communication | Complements HPL |
| Real training workload (for example NeMo / Megatron LLM training, MLPerf Training) | Everything together: GPUs, NCCL, storage, scheduler | The truest "ready for users" proof. Compare tokens/s or step time to the reference. |
| Burn-in (repeated HPL / DCGM r4 / training for 24–72+ h) | Sustained load | Catches early-life hardware failures ("infant mortality") and intermittent errors |
# Example idea: HPL in NVIDIA's HPC-Benchmarks container across 4 nodes
srun -N 4 --ntasks-per-node=8 --gpus-per-node=8 \
--container-image=nvcr.io#nvidia/hpc-benchmarks:<tag> \
./hpl.sh --dat /path/HPL.dat
12Monitoring, baselines, handover
- Monitoring: DCGM Exporter → Prometheus → Grafana for GPUs, UFM for the IB fabric, BCM monitoring for nodes, and alerting on XIDs, ECC, temperature, and link errors.
- Baselines: save "golden" DCGM results, nccl-tests busbw (single-node and multi-node), perftest numbers, HPL results, and storage throughput.
- Ongoing health: Slurm prolog/epilog checks, periodic DCGM diagnostics on drained nodes, periodic nccl-tests sweeps.
- Documentation: firmware and software versions, topology, cabling map, test results, known issues.
Domain 1 deep dive: System and Server Bring-Up 31%
NVIDIA's summary of this domain: end-to-end hardware deployment, meaning rack, power, BMC, security, firmware, physical installation, initial server and network setup, cable validation, and hardware verification, so that everything is deployed, configured, and working before AI operations scale up.
1.1 The sequence of events for deployment and validation
The exam expects you to know the order and the gate between steps: you don't move on until the current step passes.
| # | Step | Gate to pass before the next step | Phase in this guide |
|---|---|---|---|
| 1 | Site readiness: power, cooling, floor, network drops, cabling plan | Facility signed off for the rack power and heat load | 0 |
| 2 | Receive, inspect, rack and stack, connect power | No shipping damage; every PSU powers on with no faults | 0 |
| 3 | Cable compute, storage, in-band, and OOB networks against the plan | Labels and port map match the plan | 0 |
| 4 | Initial BMC / OOB / TPM configuration; change default credentials | Every BMC reachable on the OOB network; remote power and console work | 1, 1.3 |
| 5 | Firmware to one validated baseline (BIOS, BMC, GPU/HGX, NIC, DPU, NVMe, switches, transceivers); BIOS settings | Identical versions on every node; no faults after update | 1, 1.4 |
| 6 | Network infrastructure: switch OS and config, Subnet Manager / UFM, management Ethernet | Switches up and at the baseline version; SM running | 4 |
| 7 | Head node(s): OS, BCM, HA, networks, categories, software images | BCM healthy; HA failover tested | 2, Domain 3 |
| 8 | Provision compute nodes; driver, Fabric Manager, DOCA, DCGM, container stack | All nodes UP with identical software | 2, 3 |
| 9 | Hardware verification per node: inventory, nvidia-smi, DCGM diag, stress | Every node passes on its own | 5, 1.7 |
| 10 | Fabric verification: link states, cabling correctness, signal quality, firmware on switches/DPUs/transceivers | All links at full rate, no errors, topology matches | 4, Domain 4 |
| 11 | Single-node NCCL → perftest → multi-node NCCL → ClusterKit | Bandwidth at expected levels, consistent across nodes | 6–8 |
| 12 | Storage verification | Throughput meets spec, per node and aggregate | 9 |
| 13 | Scheduler and containers | Jobs run on every node, with GPUs and RDMA | 10 |
| 14 | Benchmarks and burn-in: HPL, NCCL, NeMo | Stable for the burn-in period, performance at reference | 11 |
| 15 | Monitoring, baselines, handover | Golden results recorded; operations accepted | 12 |
1.2 Network topologies for AI factories
This objective is covered in the AI factory architecture guide:
- The four networks: compute, storage, in-band, out-of-band; east-west vs north-south.
- Compute fabric topology: rail-optimized, non-blocking fat tree, PXN, and why a swapped cable slows NCCL.
- Scalable units and sizing math: leaf and spine counts, cables, transceivers.
- GB200 NVL72: a 72-GPU NVLink domain per rack.
For bring-up, the topology turns into one check: cabling must match the plan, port i of every node on leaf i, verified with ibnetdiscover / ibdiagnet before performance tests (phase 4).
1.3 Initial configuration of BMC, OOB, and TPM
BMC and OOB first-time setup
- Connect each BMC port to the OOB switch (the dedicated BMC port, not a shared host NIC, on GPU servers).
- Set addressing: DHCP reservations, or static from the host or BIOS setup screen.
- Change default credentials, create named admin accounts, and set roles.
- Set time (NTP), hostname / DNS, and a syslog or event destination.
- Install trusted TLS certificates for Redfish and the web UI; prefer Redfish over IPMI-over-LAN, and disable IPMI-over-LAN if it isn't needed.
- Test remote power, the remote console (KVM / Serial over LAN), sensors, and the event log.
- Register BMC addresses and credentials in BCM so it can power-control nodes.
# In-band, from the host OS (first-time network config of the local BMC)
sudo ipmitool lan print 1
sudo ipmitool lan set 1 ipsrc static
sudo ipmitool lan set 1 ipaddr 10.0.100.11
sudo ipmitool lan set 1 netmask 255.255.255.0
sudo ipmitool lan set 1 defgw ipaddr 10.0.100.1
sudo ipmitool user list 1
sudo ipmitool user set password <user-id> # prompts for the new password
# Out-of-band checks with Redfish
curl -s -u $BMC_USER:$BMC_PASS --cacert bmc-ca.pem https://$BMC/redfish/v1/Managers/<bmc-id>/EthernetInterfaces
curl -s -u $BMC_USER:$BMC_PASS --cacert bmc-ca.pem https://$BMC/redfish/v1/Systems/<system-id> | jq .PowerState
TPM (Trusted Platform Module)
A TPM is a small security chip (TPM 2.0 on current servers) that stores keys and measurements of the boot process. It enables measured boot (each boot stage is hashed into the TPM's registers), attestation (proving to a remote party that the server booted known-good firmware and software), and sealing of keys such as disk-encryption keys so they're only released to a trusted boot.
| Task | Where / how |
|---|---|
| Enable the TPM (and choose TPM 2.0) | BIOS/UEFI security settings, or the BMC's BIOS-settings interface |
| Enable UEFI Secure Boot | BIOS; only signed bootloaders and kernels load. Signed NVIDIA kernel modules (or enrolled keys) are then required. |
| Check from the OS | ls /dev/tpm0 /dev/tpmrm0, dmesg | grep -i tpm, tpm2_getcap properties-fixed (tpm2-tools), mokutil --sb-state |
| Check out-of-band | Redfish Systems/<id> → TrustedModules (interface type, firmware version, status) |
| Clear / take ownership | BIOS or OS tools. Clearing a TPM destroys keys sealed in it (for example disk-encryption keys). |
nvidia-smi fails and dmesg shows a key/signature rejection. Use signed drivers or enroll a Machine Owner Key (MOK).More depth: Redfish, IPMI & BMC.
1.4 Firmware upgrades (including HGX) and fault detection
| Component | Typical tool / path | Verify with |
|---|---|---|
| BIOS/UEFI, BMC, CPLD, PSUs | BMC web UI or Redfish UpdateService; vendor tools; on DGX, NVIDIA's firmware update tooling (for example nvfwupd or the DGX firmware update container, depending on platform) | Redfish UpdateService/FirmwareInventory, dmidecode -t bios, ipmitool mc info |
| HGX baseboard: GPUs, NVSwitches, HGX management controller (HMC), baseboard FPGA/CPLD | Firmware packages pushed through the host BMC's Redfish to the HMC (the HGX board's own management controller) | Redfish firmware inventory (HGX entries), nvidia-smi -q | grep -i vbios |
| ConnectX NICs (and BlueField NIC firmware) | mlxfwmanager (query / update from a package), flint (burn a specific image) | mlxfwmanager --query, flint -d <dev> q |
| NVMe drives | nvme fw-download + nvme fw-commit, or vendor tools | nvme list, nvme id-ctrl |
| Switches (IB / Ethernet) | Switch OS image upgrade, or UFM for fleets | Switch show version / nv show system, UFM inventory |
| Transceivers | Vendor / MFT tooling where supported | mlxlink -m module info |
# Example: NVIDIA's firmware tool against a DGX/HGX BMC (syntax varies by version: check --help)
nvfwupd -t ip=$BMC user=$BMC_USER password=$BMC_PASS show_version
nvfwupd -t ip=$BMC user=$BMC_USER password=$BMC_PASS update_fw -p <package>.fwpkg
# NIC firmware on the host
sudo mst start
sudo mlxfwmanager --query # all Mellanox/NVIDIA devices, current vs available FW
sudo mlxfwmanager -u -i <fw-package>.bin # update (then reset or power cycle to activate)
Best practice
- Use one validated firmware recipe (the versions NVIDIA or the OEM tested together) for every node. Read the release notes for order and dependencies.
- Update a canary node first, validate it, then roll out in batches (drained nodes only).
- Don't interrupt power during an update. Some components only activate after a full AC power cycle or a BMC/host cold reset; do what the release notes say.
- After the update: re-read every version, check the event log, run
nvidia-smi,nvsm show health(DGX), and a short DCGM diag.
Fault detection during and after updates
- Redfish task ends in
Exception/ failed state, or the component'sStatus.HealthisWarning/Critical. - SEL or Redfish log entries for the component; GPU missing from
nvidia-smi; NVSwitch errors; NICs missing fromlspci. - Version mismatch between nodes after a partial rollout: compare inventories and re-apply.
- Recovery: retry the update, reset the BMC (
ipmitool mc reset cold), or use the component's recovery / backup image if it has dual-bank firmware.
Deeper: HGX firmware & nvfwupd guide (BMC vs HMC, activation, rollout plan builder) and the networking firmware (MFT) guide (NICs, DPUs, switches).
1.5 Validate power and cooling parameters
- Capacity: a DGX H100 can draw about 10.2 kW at maximum, and has multiple redundant PSUs. Rack PDUs, circuits, and feeds must cover the maximum draw with redundancy (A and B feeds).
- Cooling: front-to-back airflow, hot/cold aisle containment, blanking panels, inlet temperature within the system's operating range. Rack-scale systems such as GB200 NVL72 are liquid cooled: check coolant distribution units (CDUs), flow, temperatures, and leak detection.
- Check under load, not just at idle: HPL and burn-in are also power and cooling tests.
# BMC side
ipmitool -I lanplus -H $BMC -U $BMC_USER -E sdr type "Power Supply" # every PSU present and OK
ipmitool -I lanplus -H $BMC -U $BMC_USER -E sdr type Temperature # inlet / exhaust / CPU temps
ipmitool -I lanplus -H $BMC -U $BMC_USER -E sdr type Fan
ipmitool -I lanplus -H $BMC -U $BMC_USER -E dcmi power reading # current system power
# GPU side
nvidia-smi -q -d POWER,TEMPERATURE,PERFORMANCE
nvidia-smi --query-gpu=index,power.draw,power.limit,temperature.gpu,temperature.memory,clocks_event_reasons.active --format=csv -l 5
dcgmi dmon -e 150,140,155 -d 1000 # GPU temp, memory temp, power usage
1.6 Install GPU-based servers (SMI)
Here "SMI" refers to the NVIDIA System Management Interface, nvidia-smi: you install the server and then prove, with nvidia-smi, that the OS and driver see the GPUs correctly.
- Rack the server on the correct rails. GPU servers are very heavy (a DGX H100 is well over 100 kg); use a lift and follow the site's safety rules.
- Connect power (both feeds), the OOB BMC port, management, compute, and storage networks.
- Power on, configure the BMC, update firmware, set BIOS settings, install or provision the OS and driver.
- Verify with
nvidia-smi:
nvidia-smi # driver version, all GPUs, no errors
nvidia-smi -L # GPU count and UUIDs
nvidia-smi --query-gpu=index,name,pci.bus_id,serial,vbios_version,persistence_mode,ecc.mode.current,mig.mode.current,power.limit --format=csv
nvidia-smi topo -m # NVLink between GPUs, GPU↔NIC affinity
nvidia-smi nvlink -s # every NVLink active
systemctl is-active nvidia-persistenced nvidia-fabricmanager
More: nvidia-smi deep dive.
1.7 Validate installed hardware
Compare what the OS and BMC see against the bill of materials. Missing or downgraded parts are easier to fix now than after users arrive.
lscpu | grep -E "Model name|Socket|NUMA" # CPUs and NUMA nodes
free -g ; sudo dmidecode -t memory | grep -c "Size: [0-9]" # memory total and populated DIMMs
lspci | grep -i nvidia # GPUs and NVSwitches
lspci -d 15b3: # NVIDIA networking (ConnectX, BlueField)
sudo lspci -vv -s <bus:dev.fn> | grep -E "LnkCap|LnkSta" # PCIe link speed/width: LnkSta should match LnkCap
nvme list # NVMe drives, models, firmware
ibstat | grep -E "CA '|State|Rate" # HCAs, port state, rate
ibdev2netdev # HCA to interface map
sudo nvsm show health # DGX: overall health and inventory checks
curl -s -u $BMC_USER:$BMC_PASS --cacert bmc-ca.pem https://$BMC/redfish/v1/Systems/<system-id> | jq '{Model, ProcessorSummary, MemorySummary}'
LnkSta: Speed 16GT/s, Width x8 when LnkCap says 32GT/s, x16) works but is slow. Causes: seating, riser, cable, BIOS slot setting, or a fault. It's a classic "everything passes but one node is slower" root cause.1.8 Describe and validate cable types and transceivers
| Type | Reach | Power | Typical use |
|---|---|---|---|
| DAC (passive direct-attach copper) | A few meters at 400G | None (cheapest, most reliable) | Inside a rack (node to top-of-rack leaf) |
| ACC (active copper) | Slightly longer than DAC | Low | Adjacent racks |
| AOC (active optical cable) | Tens of meters | Medium | Row-level runs |
| Transceivers + fiber (multimode SR4, single-mode DR4/FR4) | ~50 m (multimode) to 500 m – 2 km (single-mode) | Highest | Leaf to spine, across halls |
- Form factors: OSFP (DGX H100 and Quantum-2 switches use twin-port OSFP, 2 × 400G per cage), QSFP112 / QSFP56. Fiber connectors: MPO (parallel) or LC (duplex).
- 400G NDR uses PAM4 signaling and requires RS-FEC. Healthy links have a low raw (pre-FEC) BER and zero effective (post-FEC) errors.
- Validate: cable type and part number match the plan (
mlxlink -m), link at full speed and width (ibstat,iblinkinfo), BER and error counters clean under load (mlxlink -c,ibdiagnet).
Full detail, including a BER calculator: InfiniBand physical layer.
1.9 Install physical GPUs
On DGX and HGX systems the GPUs are SXM modules on a baseboard that's serviced as a unit. On PCIe GPU servers (NVIDIA-Certified Systems from OEMs), you may install cards yourself:
- Check the server's qualified configuration: which GPU models, how many, in which slots, with which risers and power cables.
- Power off, remove AC power, use ESD protection.
- Install in x16 slots (PCIe Gen5 for H100-class), balanced across CPU sockets, ideally on the same PCIe switch or root complex as the NIC each GPU will use.
- Connect the auxiliary power cable the card needs (for example the 16-pin 12V-2x6 / 12VHPWR connector) fully seated; don't bend it sharply near the connector.
- Install NVLink bridges on paired cards that support them (for example H100 NVL pairs).
- Data-center GPUs are passively cooled: the server's fans and airflow (and fan profile) must be the ones specified for GPUs; fill empty slots with blanks.
- BIOS: enable above-4G decoding and resizable/large BAR support as required; set slot speed to auto/Gen5.
- Verify:
lspci(all cards, full link width and speed),nvidia-smi,nvidia-smi topo -m, then a DCGM diag.
lspci usually means seating, riser, power cable, or BIOS (above-4G) problems.1.10 Validate hardware operation for workloads
"Hardware works" means more than "it's detected". Load it the way workloads will:
| Check | Tool | Pass |
|---|---|---|
| GPU hardware, memory, PCIe/NVLink, power | dcgmi diag -r 3 (or -r 4 for acceptance) | All tests PASS on every GPU |
| Sustained compute load and thermals | gpu-burn, dcgmproftester | No errors, no throttling, clocks stable |
| Copy bandwidth (host↔GPU, GPU↔GPU) | nvbandwidth | Matches peers and platform expectation |
| GPU-to-GPU collectives in the node | Single-node all_reduce_perf -g 8 | Expected busbw, #wrong 0 |
| Whole-node compute | Single-node HPL | Residual PASSED, performance in line with peers |
See phase 5, gpu-burn & dcgmproftester, and the DCGM deep dive.
1.11 Configure initial parameters for third-party storage
Most AI clusters use partner storage (parallel filesystems or high-performance NFS). Initial configuration on the compute side:
- Network: the storage fabric NICs, IP addressing, MTU (jumbo frames, 9000, end to end on Ethernet), and RDMA settings (for RoCE: lossless or congestion-controlled configuration on switches and NICs).
- Client software: install the vendor's client (for example a Lustre client, a GPFS / Storage Scale client, a WEKA client), or use NFS with recommended options (for example
nconnectfor multiple TCP connections, or NFS over RDMA). - Mounts: mount options from the vendor's guide, mounted on every node. In BCM, define the mount in the node category (
fsmounts) so every node gets it, instead of editing/etc/fstabby hand. - GPUDirect Storage (if planned): IOMMU off/pt and ACS disabled, install
nvidia-gds, loadnvidia_fs, configure/etc/cufile.jsonfor the storage NICs and filesystem, and check withgdscheck -pthat the filesystem shows a real GDS mode, not justcompat(full procedure). - Test a single node, then many nodes at once (phase 9).
# Examples (vendor guides give the real options)
sudo mount -t nfs -o vers=4.1,nconnect=16,rsize=1048576,wsize=1048576 storage01:/datasets /mnt/datasets
sudo mount -t lustre 10.10.0.10@o2ib:/aifs /mnt/aifs # Lustre over InfiniBand (LNet o2ib)
lnetctl net show # Lustre networking status
# BCM: add the mount to the category, not to individual nodes
cmsh -c "category use dgx-h100; fsmounts; add /mnt/datasets; set device storage01:/datasets; set filesystem nfs; set mountoptions vers=4.1,nconnect=16; commit"
/usr/local/cuda/gds/tools/gdscheck -p # GDS: drivers, filesystem support, config
Deeper: Lustre & third-party storage guide, shared storage, GPUDirect Storage.
Domain 2 deep dive: Physical Layer Management 5%
Configuring and maintaining the physical resources: GPU and BlueField DPU networks, cables and transceivers, and GPU partitioning with MIG.
2.1 Configure and manage a BlueField network platform
BlueField is NVIDIA's DPU (data processing unit): a ConnectX network adapter plus its own Arm CPU cores, memory, and accelerators, running its own Linux OS. BlueField-3 also ships as a SuperNIC for Spectrum-X east-west traffic. On a DGX H100, BlueField-3 DPUs typically serve storage and in-band networking, while ConnectX-7 adapters serve the compute rails.
| Concept | What to know |
|---|---|
| DPU mode (the default for DPUs) | The Arm cores own the NIC's embedded switch. Host traffic passes through the DPU's switching (for example OVS on the Arm side), which enables offloads, isolation, and security policies the host can't bypass. |
| NIC mode | The BlueField behaves like a ConnectX NIC for the host; the Arm cores aren't in the data path. Simpler, and used when you only want a fast NIC. |
| Port type | Ports can be InfiniBand or Ethernet (LINK_TYPE_P1 / P2 in mlxconfig: 1 = IB, 2 = ETH) |
| BFB image | The bundle (Arm OS + DOCA runtime + firmware) installed onto the DPU from the host through RShim |
| RShim | Host-side driver/service that gives the host a console, a virtual network (tmfifo_net0), and image push to the DPU over PCIe |
| DPU management | Its own OOB Ethernet port and, on BlueField-3, its own BMC |
| DOCA | NVIDIA's SDK and runtime for BlueField (and the DOCA-Host driver package on the host) |
# On the host
sudo mst start ; sudo mst status -v # find the device (for example /dev/mst/mt41692_pciconf0 for BlueField-3)
sudo mlxconfig -d /dev/mst/mt41692_pciconf0 q | grep -E "LINK_TYPE|INTERNAL_CPU" # port types and DPU/NIC mode settings
sudo flint -d /dev/mst/mt41692_pciconf0 q # firmware version and PSID
systemctl status rshim # RShim service
sudo bfb-install --bfb <image>.bfb --rshim rshim0 # install a BFB image onto the DPU
# Reach the DPU's Arm OS
ssh ubuntu@192.168.100.2 # over tmfifo_net0 (host side is typically 192.168.100.1)
# or the RShim console, or the DPU's OOB management port
# On the DPU (Arm)
cat /etc/mlnx-release # installed BFB / DOCA version
sudo ovs-vsctl show # DPU-mode switching (OVS bridges and ports)
mlxconfig change, a firmware reset or host power cycle is needed for it to take effect. Follow the BlueField / DOCA documentation for your version.2.2 Configure MIG (AI and HPC)
MIG (Multi-Instance GPU) splits one A100/H100-class GPU into up to 7 isolated instances, each with its own SMs, memory, and cache.
sudo nvidia-smi -i 0 -mig 1 # enable MIG mode on GPU 0 (GPU must be idle; may need a GPU reset)
nvidia-smi mig -lgip # list GPU instance profiles (for example 1g.10gb, 3g.40gb, 7g.80gb on H100 80GB)
sudo nvidia-smi mig -cgi 9,9 -C # create two GPU instances (profile ID 9 = 3g.40gb on H100 80GB) plus compute instances
nvidia-smi mig -lgi ; nvidia-smi mig -lci # list GPU / compute instances
nvidia-smi -L # MIG devices now listed with their own UUIDs
sudo nvidia-smi mig -dci ; sudo nvidia-smi mig -dgi # delete compute, then GPU instances
sudo nvidia-smi -i 0 -mig 0 # disable MIG
| Use | Typical MIG layout | Why |
|---|---|---|
| AI inference / notebooks / dev | Many small instances (for example 7 × 1g.10gb) | Many small, isolated workloads with guaranteed QoS |
| HPC throughput (many small jobs) | Mid-size instances (for example 2–3 instances) | Run several independent jobs per GPU without interference |
| Large training / large HPC jobs | MIG off | Need the whole GPU and NVLink between GPUs |
- Profile IDs differ by GPU model; always list them with
-lgipfirst. - MIG configurations aren't automatically recreated at boot. Use a declarative tool (for example
nvidia-mig-parted, the Kubernetes GPU Operator's MIG manager, or BCM configuration) to make them persistent. - Slurm: GRES can auto-detect MIG devices (
AutoDetect=nvmlingres.conf). Kubernetes: the GPU Operator exposes MIG with a single or mixed strategy. - Inside MIG instances there's no NVLink P2P between instances, so MIG is a poor fit for multi-GPU training.
Full command reference: nvidia-smi MIG.
Domain 3 deep dive: Control Plane Installation and Configuration 19%
Installing and configuring operating systems, cluster managers, drivers, container tools, and management software.
3.1 Install BCM, configure, and verify HA
- Install the head node from the Base Command Manager installer (ISO via BMC virtual media or USB): choose networks (internal/provisioning, external, IPMI/BMC, InfiniBand), disk layout, and admin settings.
- Install the license (for example
request-license, then verify withcmsh -c "main; licenseinfo"). - Apply the DGX BasePOD/SuperPOD reference configuration once with
bcm-pod-setupwhere applicable. - Configure high availability: add a second head node and run the HA setup wizard (
cmha-setup). HA uses a shared virtual IP that moves to the active head node, replicates the BCM database, and needs shared storage for directories both head nodes serve (for example/cm/sharedand/home). - Verify HA:
cmha statusshows both head nodes healthy; perform a controlled failover (for examplecmha makeactiveon the passive node) and check that provisioning, cmsh, and Slurm control keep working.
cmha status # HA state: active / passive, checks OK?
cmha makeactive # (run on the passive head node) take over as active
cmsh -c "device; status" # nodes still UP after failover
cmsh -c "main; licenseinfo"
3.2 Install the OS
| Where | OS | How |
|---|---|---|
| DGX systems (standalone) | DGX OS (Ubuntu-based, with the NVIDIA stack preconfigured) | Preinstalled at the factory. Reimage from the DGX OS ISO via BMC virtual media or USB; or install Ubuntu and add the DGX Software Stack (see below) |
| Head nodes | A Linux distribution supported by the BCM release (for example Ubuntu or a RHEL-compatible OS) | The BCM installer includes the base OS |
| BCM-managed compute nodes | A software image (for example DGX OS based) stored on the head node | Create or clone the image, assign it to the category, nodes PXE boot and sync it |
cmsh -c "softwareimage; list"
cmsh -c "softwareimage; clone dgx-os-image dgx-os-image-test; commit" # test changes on a copy
cm-chroot-sw-img /cm/images/dgx-os-image-test # enter the image to install packages
- After install: apply updates, pin (hold) the kernel version your driver and OFED/DOCA builds support, blacklist
nouveau, set time sync. - Keep OS, kernel, driver, and DOCA versions identical across nodes (BCM images make this automatic).
DGX OS: releases and install paths
| DGX OS | Based on | Notes |
|---|---|---|
| 5 | Ubuntu 20.04 | Upgrade to 6 first; you can't jump straight to 7 |
| 6 | Ubuntu 22.04 | Release-upgrade to 7 only from the latest 6.x (6.3.2 or later) |
| 7 | Ubuntu 24.04 | DOCA OFED replaces MLNX_OFED; kernel 6.8 on x86_64 DGX (H100, H200, B200, B300); ARM64 DGX (GB200, GB300) use an NVIDIA kernel |
The major number follows the Ubuntu release. Minor releases (7.1, 7.2…) add backward-compatible NVIDIA features and fixes. Upgrades are cumulative: apt always installs the latest packages in the repositories, which can be newer than the latest ISO, and you can't stop at a chosen minor version. The GPU driver stays on its current branch until that branch reaches end of support.
| Path | When | What it gives you |
|---|---|---|
| Preinstalled | New system | Run the first-boot wizard, then update packages |
| Reimage from the ISO | Install the latest or an older version, corrupted OS, OS drive(s) replaced, enable root encryption, return to factory state | The default DGX layout, unattended after you pick a boot option |
| Ubuntu + DGX Software Stack | Custom partitions, or automated (non-interactive) installs across a cluster | Ubuntu 24.04 plus NVIDIA's repositories and DGX packages |
| BCM software image | Nodes managed by BCM | One image per category, provisioned over PXE |
Reimaging from the ISO
- Get the ISO from the NVIDIA Enterprise Support Download Center (needs a support account) and check it:
md5sum DGXOS-7.x.x-<date>-amd64.isoagainst the value in the release announcement. - Boot it:
- Remotely through the BMC: Remote Control → Launch KVM → Browse File (the ISO) → Start Media, then Power → Hard Reset.
- USB: at least 16 GB. Write it as a raw image:
sudo dd if=<iso> bs=2048 of=/dev/sdX(check the device withlsblkfirst;dderases it). On Windows, Rufus in DD Image mode. A plain file copy won't boot. Press F11 at the NVIDIA logo for the boot menu.
- Pick a GRUB option (table below). The install runs unattended for about 15–60 minutes. It also updates the ConnectX firmware (up to 5 minutes per card); no other system firmware is updated.
- The system reboots into the first-boot wizard.
| GRUB option | What it does |
|---|---|
| Install DGX OS | Repartitions the OS drives and the data drives: rebuilds the data RAID and mounts it at /raid. Everything on both is erased. |
| Install DGX OS: Without Reformatting Data RAID | Keeps the data drives. /raid is created but commented out in /etc/fstab, and cachefilesd is left disabled. Uncomment both and mount /raid to use it as cache again. |
| Advanced: Without NVIDIA Drivers | Installs without the GPU driver, so you can install a different branch yourself |
| Advanced: With Encrypted Root (optionally without reformatting the data RAID) | Encrypts the root filesystem. You type the passphrase at the console (or BMC KVM) at every boot. Can't be turned on or off later without reimaging. |
| Boot Into Live Environment | Minimal OS in memory without drivers; touches no disks. For debugging. |
| Check Media for Defects | Tests the install media. Rarely the problem. |
/home. To keep files, move them to /raid and choose "Without Reformatting Data RAID". Reimaging does not change persistent hardware settings such as MIG mode or data-drive encryption.First boot (DGX servers)
The wizard runs on a display: a monitor or the BMC's KVM, not a serial console.
- Accept the EULA; choose language, keyboard, time zone, and the UTC clock.
- Create the admin user (lowercase). The same username becomes the BMC and GRUB username: the default BMC admin account is disabled and replaced. The BMC won't accept
sysadminas a username. - Set the BMC password (13–20 characters) and a GRUB password (at least 8; leaving it blank disables GRUB protection). If you chose encrypted root, set its passphrase.
- Pick the primary network interface for in-band management (
eno3on DGX H100/H200/B200). Don't pick the USB/Redfish interface (bmc_redfish0or similar). Then DHCP or static, name servers, and hostname. - Before the first reboot, wait for the data RAID to finish building:
sudo systemctl status nvidia-raid-configuntil "Finished NVIDIA RAID Configuration" (about 10 minutes). - Update packages right away (the ISO is a snapshot):
sudo apt update && sudo apt full-upgrade, then reboot.
Ubuntu + the DGX Software Stack
Install Ubuntu 24.04 Server (OS on the RAID 1 pair, and don't install Docker as a snap: Docker CE comes with the DGX packages), then add NVIDIA's repositories and the DGX metapackages:
curl https://repo.download.nvidia.com/baseos/ubuntu/noble/x86_64/dgx-repo-files.tgz | sudo tar xzf - -C /
sudo apt update && sudo apt upgrade
sudo apt install nvidia-system-core nvidia-system-utils nvidia-system-extra # configs, tools (NVSM), Docker CE
sudo apt install nvidia-mig-manager nvdebug dgx-server-grub nvidia-grub-params
sudo apt install -y linux-tools-generic nvidia-peermem-loader
sudo apt install nvidia-driver-580-open libnvidia-nscq nvidia-modprobe \
nvidia-fabricmanager datacenter-gpu-manager-4-cuda13 nv-persistence-mode # DGX H100/H200
sudo systemctl enable nvidia-fabricmanager nvidia-persistenced nvidia-dcgm
sudo reboot # then nvidia-smi: all GPUs, Persistence-M On
nvlsm and libnvsdm with Fabric Manager (see Fabric Manager). Check the user guide for your DGX OS release.Verify an install or upgrade
cat /etc/dgx-release # DGX_SWBUILD_VERSION = ISO installed; each DGX_OTA_VERSION line = a network upgrade since
uname -r # kernel at least the release notes' minimum
nvidia-smi # all GPUs, expected driver branch
systemctl status nvidia-fabricmanager nvidia-persistenced nvidia-dcgm
df -h /raid # data RAID mounted (unless you kept it unmounted on purpose)
sudo dcgmi diag -r 2 # quick functional check before handing the node back
Upgrading DGX OS
| Type | Example | How |
|---|---|---|
| Package upgrade | 7.1 → latest 7.x, security fixes | apt update, apt full-upgrade, reboot |
| Release upgrade | 6 → 7 | Latest 6.x first, then nvidia-release-upgrade |
| Driver branch change | 570 → 580 | Not automatic: install the new branch's packages explicitly (driver, Fabric Manager, and friends together) |
Before any upgrade: read the release notes; drain the node (Slurm/Kubernetes); upgrade one or two systems first and test your applications; use the BMC console rather than SSH if you can (with DHCP the IP can change at reboot, VPNs drop, and Docker's default 172.17.0.0/16 bridge makes a DGX on that subnet unreachable); confirm the node reaches the Ubuntu and NVIDIA repositories (or use a local mirror).
# Package upgrade
sudo apt update
sudo apt full-upgrade -s # dry run: review what will change
sudo apt full-upgrade # GRUB prompts: keep the current config and the default install devices
sudo reboot # required for a new driver or kernel
# Release upgrade, DGX OS 6 → 7
sudo apt update && sudo apt -y full-upgrade # to the latest 6.x; reboot if prompted
sudo apt install -y nvidia-release-upgrade
sudoedit /etc/update-manager/release-upgrades.d/nvidia.cfg # optional: DriverBranch=...
sudo nvidia-release-upgrade # sudo -E behind a proxy; reboot when prompted
- Config-file prompts: take the maintainer's
/etc/apt/sources.list.d/dgx.list; keep your local/etc/ssh/sshd_config. - Over SSH, the upgrader asks to continue and starts a spare
sshdon port 1022 for recovery. - Third-party repositories are disabled (Canonical and DGX ones are kept); re-enable them afterwards.
- MLNX_OFED is replaced by DOCA OFED during 6 → 7. Check applications that depend on MOFED.
- Packages with no DGX OS 7 candidate stop the upgrade; the release notes list what was removed.
nvidia-smi fails with Failed to initialize NVML: Driver/library version mismatch.| Upgrade interrupted (power, network) | Recovery |
|---|---|
| System still reaches a shell | sudo dpkg --configure -a, sudo apt -f install -y, rerun the upgrader from /tmp/ubuntu-release-upgrader-* (./noble --frontend=DistUpgradeViewText), then bash /usr/bin/nvidia-post-release-upgrade and reboot |
| Kernel panic after reboot | No network recovery: reimage from the ISO |
apt on the nodes. Clone the software image, upgrade inside it (cm-chroot-sw-img, then apt update && apt full-upgrade), point one canary node at the clone and reboot it, validate, then move the category. Driver and kernel changes need a reboot; imageupdate -w only pushes user-space changes. See BCM software images.3.3 Install the cluster: categories, interfaces, Slurm / Enroot / Pyxis
Categories and nodes
cmsh
% category clone default dgx-h100 # one category per node type
% category use dgx-h100
% set softwareimage dgx-os-image
% commit
% device use dgx01
% set category dgx-h100
% commit
Interfaces
% device use dgx01
% interfaces
% add physical ib0 # an InfiniBand interface (IPoIB) on node dgx01
% set network ibnet
% set ip 10.149.0.11
% commit
% list # check bootif (provisioning), BMC (ipmi0 / rf0), ib interfaces
Node identity: BCM recognizes nodes by MAC address of the boot interface (or by switch port). Replacing a motherboard or NIC changes the MAC, so update the node's record.
Slurm, Enroot, Pyxis
- Slurm: BCM's workload-manager setup wizard (
cm-wlm-setup) installs Slurm, assigns the server role to the head node(s) and the client role to the compute category, and generates the configuration, including GPU GRES. - Enroot turns container images into unprivileged sandboxes; Pyxis is the Slurm SPANK plugin that adds
--container-imagetosrun. Both go into the software image; Pyxis is enabled in Slurm'splugstack.conf. - NGC credentials for Enroot:
~/.config/enroot/.credentialswithmachine nvcr.io login $oauthtoken password <NGC API key>.
sinfo ; scontrol show node dgx01 | grep -E "Gres|State"
srun -N 2 --gpus-per-node=8 --container-image=nvcr.io#nvidia/pytorch:<tag> nvidia-smi -L
More: Base Command Manager mastery (cmsh, overlays, images, HA, with a lab), NGC with Enroot and Pyxis, BCM node recovery.
3.4 Install, update, and remove NVIDIA GPU and DOCA drivers
GPU driver
# Install from NVIDIA's repository (Ubuntu example; package names depend on branch and distro)
sudo apt install nvidia-driver-<branch>-server-open nvidia-fabricmanager-<branch>
sudo systemctl enable --now nvidia-fabricmanager nvidia-persistenced
# Update: drain the node, stop GPU users and services, upgrade driver AND Fabric Manager together, reboot
sudo systemctl stop nvidia-dcgm nvidia-fabricmanager nvidia-persistenced
sudo apt install --only-upgrade 'nvidia-*<branch>*'
sudo reboot
# Remove
sudo apt purge 'nvidia-*' 'libnvidia-*' ; sudo apt autoremove # package installs
sudo /usr/bin/nvidia-uninstall # .run installs
# Verify
nvidia-smi ; cat /proc/driver/nvidia/version ; systemctl is-active nvidia-fabricmanager
- Use one install method per system: mixing a
.runinstaller with packages causes conflicts. - Fabric Manager must match the driver version exactly on NVSwitch systems. Upgrade them together.
- Hold the packages (
apt-mark hold) so a routine OS update doesn't change the driver unexpectedly. - Open vs proprietary kernel modules: recent data-center GPUs support (and newer drivers default to) the open kernel modules; follow the release notes.
DOCA drivers (networking)
DOCA-Host is the current host package for ConnectX and BlueField drivers and tools, replacing standalone MLNX_OFED. It comes in profiles (for example doca-ofed for the OFED-equivalent drivers and tools).
sudo /usr/sbin/ofed_uninstall.sh # remove an old MLNX_OFED first, if present
sudo apt install doca-ofed # after adding the DOCA repository for your distro
sudo /etc/init.d/openibd restart # reload the RDMA stack (or reboot)
ofed_info -s ; ibstat ; ibv_devinfo
lsmod | grep -E "mlx5_core|ib_core|nvidia_peermem"
sudo apt remove 'doca-*' ; sudo apt autoremove # removal
cm-chroot-sw-img), then update the nodes (image update or reboot). Installing on individual nodes by SSH is overwritten at the next sync.nvidia-peermem not rebuilt or loaded (no GDRDMA), and the DKMS module not built for the running kernel (nvidia-smi fails). Check all three.Deep dive with a lab: GPU drivers, DOCA-Host, and the Container Toolkit.
3.5 Install the NVIDIA Container Toolkit
sudo apt install nvidia-container-toolkit # after adding NVIDIA's container toolkit repository
sudo nvidia-ctk runtime configure --runtime=docker # writes the nvidia runtime into /etc/docker/daemon.json
sudo systemctl restart docker
sudo nvidia-ctk runtime configure --runtime=containerd # for containerd (Kubernetes) instead
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml # Container Device Interface spec (Podman, CDI-aware runtimes)
nvidia-ctk --version
The toolkit doesn't contain a GPU driver: it makes the host's driver and GPUs available inside containers. In Kubernetes, the GPU Operator can install and configure it for you.
3.6 Use NVIDIA GPUs with Docker
docker run --rm --gpus all nvcr.io/nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi # all GPUs
docker run --rm --gpus 2 ... # any two GPUs
docker run --rm --gpus '"device=0,3"' ... # specific GPUs (index or UUID)
docker run --rm --gpus all -e NVIDIA_VISIBLE_DEVICES=0 ... # alternative selection
# Realistic training container on one node, with InfiniBand access for multi-node NCCL
docker run --rm -it --gpus all --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
--device=/dev/infiniband --cap-add=IPC_LOCK --network=host \
-v /mnt/datasets:/data nvcr.io/nvidia/pytorch:<tag>
echo "$NGC_API_KEY" | docker login nvcr.io -u '$oauthtoken' --password-stdin # pull from NGC
docker run --gpus all fails with "could not select device driver", the NVIDIA Container Toolkit isn't installed or Docker wasn't restarted after nvidia-ctk runtime configure. Installing a driver inside the container is the wrong fix.3.7 Install the NGC CLI on hosts
# Download the NGC CLI for Linux (from the NGC website / documentation), then:
unzip ngccli_linux.zip
chmod u+x ngc-cli/ngc
echo 'export PATH="$PATH:$HOME/ngc-cli"' >> ~/.bashrc
ngc config set # prompts for API key, org, team, output format
ngc config current
ngc registry image list nvidia/pytorch
ngc registry model download-version nvidia/<model>:<version>
The NGC CLI manages NGC resources (images, models, resources, orgs). Pulling containers is still done with Docker, Enroot, or the cluster's runtime. More: NGC CLI.
Domain 4 deep dive: Cluster Test and Verification 33%
Validating cluster health and readiness through stress testing, benchmarking, cable integrity checks, firmware validation, and bandwidth verification, ending with burn-in.
4.1 Single-node stress test
dcgmi diag -r 3 # hardware diagnostics incl. stress, memory, PCIe/NVLink, power
dcgmi diag -r 4 # extended (longer) for acceptance and burn-in
./gpu_burn -d 3600 # 1 hour of sustained compute (double precision with -d)
dcgmproftester12 --no-dcgm-validation -t 1004 -d 300 # tensor-core load (field 1004); name varies with CUDA version
nvidia-smi dmon -s pucvmet # watch power, utilization, clocks, violations, memory, ECC, temps
See gpu-burn & dcgmproftester and the DCGM deep dive.
4.2 Execute HPL
- Run NVIDIA's HPC-Benchmarks NGC container (
hpl.shwith anHPL.dat), single node first, then multi-node. - Size
Nto fill most of GPU memory, pickNBfor the GPU, and chooseP × Q= number of GPUs. - Pass: residual check PASSED, performance (Rmax) close to the expected fraction of peak, and consistent per node.
Everything else: HPL mastery (sizing calculator, output, tuning).
4.3 Single-node NCCL, including verifying the NVLink Switch
systemctl status nvidia-fabricmanager # must be active on NVSwitch systems
nvidia-smi topo -m # GPU pairs show NV18 (H100 SXM: 18 NVLinks per GPU)
nvidia-smi nvlink -s # every link up at the same speed
nvidia-smi nvlink -e # NVLink error counters (should not grow)
nvidia-smi -q | grep -i -A3 fabric # fabric registration state on newer drivers / platforms
./all_reduce_perf -b 8 -e 8G -f 2 -g 8 # single-node NCCL across all 8 GPUs (NVLink/NVSwitch only)
NCCL_DEBUG=INFO ./all_reduce_perf -b 1G -e 1G -g 8 2>&1 | grep -E "via P2P|NVLS|SHM" # P2P / NVLS in use, not SHM
#wrong 0.See phase 6, NVLink & nvbandwidth, Fabric Manager, nccl-tests mastery.
4.4 Validate cables by verifying signal quality
sudo mlxlink -d mlx5_0 -m # module / cable info: type, vendor, part number, length, temperature, firmware
sudo mlxlink -d mlx5_0 -c # counters: raw (pre-FEC) BER, effective (post-FEC) BER, symbol errors
sudo mlxlink -d mlx5_0 --pc # clear counters, then run traffic (perftest / NCCL) and check again
sudo mlxlink -d mlx5_0 -e # eye opening (signal margin) where supported
ibdiagnet # fabric-wide: error counters, link speed/width, cable info, BER warnings
ibqueryerrors # ports whose error counters exceed thresholds
Full detail: InfiniBand physical layer, BER, and FEC, and the transceivers, cables & signal quality guide (form factors, eye diagrams, DDM, test duration).
4.5 Confirm cabling is correct
- At scale, use NVIDIA's UFM Cable Validation Tool (CVT). A collector container on the management network deploys agents to every switch (and optionally hosts) and validates each link against the P2P cabling plan (or a
.topo/.dotfile). It reports Wrong-neighbor, Wrong-port, Extra-cable, Media unplugged, flapping, BER, and power/temperature anomalies, and separates non-cable issues (AdminDown, negotiation fail, unreachable device). Details: CVT section. - Discover the real topology (
ibnetdiscover,iblinkinfo, UFM topology view) and compare it with the cabling plan: every node port connects to the planned switch and port. Good for spot checks and small fabrics. - Rail check: on every node, HCA i (
mlx5_i) must connect to leaf / rail i. A swapped pair still links up, but breaks rail alignment and slows NCCL. - Ethernet networks: use LLDP neighbor information (on hosts and switches) to confirm which switch port each NIC is plugged into.
- Count links: every expected link present, none missing between leaf and spine (missing uplinks show up only at scale).
iblinkinfo | grep dgx05 # which switch ports node dgx05's HCAs reach
ibnetdiscover > fabric.topo # save, then diff against the expected topology
ibdiagnet # reports topology, speeds, and mismatches; can compare with a reference topology (options vary)
sudo lldptool -t -n -i eth0 # Ethernet: neighbor switch and port (or lldpctl)
4.6 Confirm firmware and software on switches
ibswitches # all IB switches in the fabric (GUID, LID, description)
sudo flint -d lid-<switch-LID> q # in-band firmware query of an IB switch (needs MFT with in-band access)
# On the switch CLI (depends on switch OS):
show version # MLNX-OS / Onyx style
nv show system # NVOS / Cumulus style
For a fleet, use UFM's inventory to list every switch's model, OS, and firmware. All switches of the same role should run the same validated version, matching the cluster's firmware recipe.
Deeper: InfiniBand and Ethernet switch upgrades in the networking firmware guide.
4.7 Confirm firmware and software on BlueField-3
# Host side: NIC firmware of the DPU
sudo mlxfwmanager --query
sudo flint -d /dev/mst/mt41692_pciconf0 q
# DPU side (Arm OS): BFB image, DOCA runtime, drivers
ssh ubuntu@192.168.100.2 'cat /etc/mlnx-release; ofed_info -s'
# Its BMC (BlueField-3): Redfish firmware inventory on the DPU BMC address
curl -s -u $BMC_USER:$BMC_PASS --cacert bmc-ca.pem https://$DPU_BMC/redfish/v1/UpdateService/FirmwareInventory
4.8 Confirm firmware on transceivers
- Optical transceivers have their own firmware. Mismatched or old module firmware can cause link flaps or high BER.
- Host side:
mlxlink -d mlx5_X -mshows module vendor, part number, and firmware information for each port. - Fabric-wide:
ibdiagnetcollects cable/module information for every link; UFM shows cable inventory. - Switch side: the switch OS's transceiver commands show the modules plugged into each switch port.
- Compare against the qualified module list and firmware versions; update through the vendor-supported tool where needed.
- More: transceiver firmware in the signal-quality guide.
4.9 Run ClusterKit for a multifaceted node assessment
ClusterKit (part of HPC-X) runs a battery of tests across many nodes at once: GPU and CPU checks, memory bandwidth, and pairwise and simultaneous network bandwidth and latency. It points to outlier nodes and links quickly.
Details, output, and how it compares with DCGM, perftest, and nccl-tests: ClusterKit vs other tools.
4.10 Run NCCL to verify east-west fabric bandwidth
Multi-node all_reduce_perf (and all_gather_perf, reduce_scatter_perf, alltoall_perf) through Slurm or MPI, scaling from pairs to racks to the whole cluster. Check NET/IB with all HCAs and GDRDMA in the logs. See phase 8, the NCCL deep dive, and the GPU0 bottleneck case.
4.11 NCCL burn-in
The goal is stability over time at full fabric load, not a single good number.
# Repeated full-cluster runs with correctness checking, logged for later comparison
for i in $(seq 1 48); do
srun -N 32 --ntasks-per-node=8 --gpus-per-node=8 --mpi=pmix \
./all_reduce_perf -b 1G -e 16G -f 2 -g 1 -n 200 -c 1 | tee -a nccl-burnin.log
done
grep -E "Avg bus bandwidth|#wrong" nccl-burnin.log | tail
ibqueryerrors # did any link's error counters grow during the burn-in?
#wrong = 0, busbw stays within a small band of the baseline throughout, and no link errors, Xids, or ECC errors appear.4.12 HPL burn-in
- Run HPL repeatedly (or with a long run time) on all nodes at the same time, so the whole facility runs at maximum power and heat. This is also the real test of power and cooling.
- Check every run: residual PASSED, Gflops per node consistent, no node drops out, no throttling, no Xids/ECC errors.
- Watch rack power draw and inlet temperatures during the run.
See HPL validation strategy and the burn-in guide (sequence, monitoring, and a lab for NCCL, HPL, and NeMo).
4.13 NeMo burn-in
NeMo is NVIDIA's framework for training and customizing large language and multimodal models. A NeMo burn-in runs a real LLM pretraining workload (for example a GPT- or Llama-style model) across the cluster for hours, usually with synthetic ("mock") data so storage isn't the bottleneck, then optionally with real data and checkpointing.
| Why NeMo after HPL and NCCL | What it adds |
|---|---|
| Mixed, realistic load | Tensor-core math in low precision, plus overlapping NCCL collectives (AllReduce, AllGather, ReduceScatter for tensor/pipeline/data parallelism) |
| Software stack | Exercises the NGC container, Slurm/Pyxis or Kubernetes, NCCL settings, and the framework together |
| Storage | Checkpoint writes (and data loading if you use real data) |
# Sketch: launch from the NeMo NGC container under Slurm (recipes and arguments differ between NeMo versions)
srun -N 16 --ntasks-per-node=8 --gpus-per-node=8 \
--container-image=nvcr.io#nvidia/nemo:<tag> --container-mounts=/mnt/ckpt:/ckpt \
python <nemo-pretraining-script-or-recipe> <model-size and parallelism options> <mock-data option>
In depth: NeMo burn-in (parallelism and throughput math with a calculator, log fields, checkpoints and the resume test, failure signatures, and a NeMo practice set).
4.14 Test storage
| Test | Tool |
|---|---|
| Sequential read/write throughput, one node | fio (--direct=1, large block sizes, several jobs) |
| Aggregate throughput, many nodes at once | fio in parallel (Slurm/pdsh), or IOR (MPI-based parallel I/O benchmark) |
| Metadata (file create/stat/delete rates, many small files) | mdtest |
| GPUDirect Storage path | gdscheck -p, gdsio |
| Local NVMe RAID cache | fio on /raid |
| Checkpoint pattern | Large parallel writes from all ranks at once (or a real NeMo checkpoint) |
See phase 9 and benchmarking with fio.
Domain 5 deep dive: Troubleshooting and Optimization 12%
Detecting, analyzing, and resolving hardware faults and performance bottlenecks: root cause, component replacement, server and storage tuning.
5.1 5.2 Identify and troubleshoot hardware faults; identify faulty cards, GPUs, and PSUs
| Component | Symptoms | Where to look |
|---|---|---|
| GPU | Missing from nvidia-smi; Xid errors; ECC errors; row-remap failures; diag failures; throttling | dmesg | grep -i xid, nvidia-smi -q -d ECC,ROW_REMAPPER,PERFORMANCE, dcgmi health -c, dcgmi diag -r 3, nvsm show health |
| NVLink / NVSwitch | Xid 74, links down, low single-node NCCL | nvidia-smi nvlink -s / -e, Fabric Manager log, DCGM NVLink tests |
| Network card (ConnectX / BlueField) | Port down or flapping, low rate, missing device, PCIe errors | ibstat, mlxlink, dmesg | grep -i mlx5, lspci link status, dmesg | grep -i aer (PCIe errors) |
| Fan | Fan sensor failed or low RPM, rising temperatures, throttling | ipmitool sdr type Fan, SEL, Redfish Chassis/<id>/Thermal, nvsm show alerts |
| Power supply | PSU failed / AC lost, redundancy lost, power capping | ipmitool sdr type "Power Supply", ipmitool sel elist, Redfish PowerSupplies[].Status, PSU LEDs |
| Memory (DIMM), CPU | Correctable error storms, machine-check errors | SEL, dmesg/journalctl -k (MCE / EDAC) |
| NVMe | Media errors, wear, missing drive | nvme smart-log, nvme list, dmesg |
Xid codes worth knowing
| Xid | Meaning | Usually |
|---|---|---|
| 13, 31, 43 | Graphics engine exception / GPU memory page fault / GPU stopped processing | Often the application (bad kernel, out-of-bounds access); suspect hardware only if it repeats across apps |
| 48 | Double-bit ECC error | Hardware memory error |
| 63, 64 | Row remapping event / failure | Memory repair; 64 = remap failed → RMA candidate |
| 74 | NVLink error | NVLink / NVSwitch hardware or Fabric Manager |
| 79 | GPU has fallen off the bus | PCIe, power, or GPU hardware failure |
| 92 | High single-bit ECC error rate | Degrading memory |
| 94, 95 | Contained / uncontained ECC error | 94: only affected app killed; 95: GPU needs reset |
| 119, 120 | GSP (GPU System Processor) timeout / error | Driver/firmware issue; collect a bug report |
All codes, ECC/row-remap states, CUDA/NCCL/NVML messages, and the restart → reset → reboot → drain → RMA ladder: error codes guide.
Find the physical part
nvidia-smi --query-gpu=index,pci.bus_id,serial,uuid --format=csv # map a failing GPU to its serial and PCI address
ipmitool -I lanplus -H $BMC -U $BMC_USER -E chassis identify 120 # blink the locator LED for 2 minutes
sudo nvsm show gpus # DGX: GPU inventory and health
On DGX/HGX, use the platform's service documentation to map PCI bus IDs / GPU indexes to physical module positions. The nvidia-smi index isn't guaranteed to match the slot label; use serial numbers or bus IDs (see GPU ordering & visibility).
5.3 Replace faulty cards, GPUs, and power supplies
- Collect evidence for the RMA:
nvidia-bug-report.sh,nvsm dump health(DGX), DCGM diag JSON, SEL, serial numbers. - Drain the node so no new jobs land on it:
scontrol update nodename=dgx07 state=drain reason="GPU4 Xid79 RMA"(or cordon/drain in Kubernetes). - Wait for running jobs to finish (or requeue them), then power down through the BMC or BCM.
- Replace the part following the service guide. Hot-swappable parts such as redundant PSUs and fans on many servers can be replaced while running; GPUs, GPU baseboards, NICs, and DIMMs need the system powered off. ESD protection always.
- Bring the new part to the firmware baseline (replacement parts often ship with different firmware).
- Update identity if it changed: a new motherboard or boot NIC means a new MAC address for BCM provisioning; a new BMC may need its network and credentials set again.
- Re-validate:
nvidia-smi,dcgmi diag -r 3, single-node NCCL, and a multi-node test with a known-good peer. - Return to service:
scontrol update nodename=dgx07 state=resume, and record what was replaced.
5.4 Performance optimization for AMD and Intel servers
The GPUs do the math, but the host CPU, memory, and PCIe topology feed them. Tuning focuses on predictable performance, NUMA locality, and PCIe/RDMA efficiency.
| Area | AMD EPYC | Intel Xeon | Why |
|---|---|---|---|
| Power / performance profile | Performance determinism / maximum performance; limit deep C-states | Performance power profile; energy-performance bias to performance; limit deep C-states | Avoid clock and latency variation |
| NUMA layout | NPS (NUMA nodes per socket: NPS1, NPS2, NPS4) | SNC (Sub-NUMA Clustering) on/off | Match the vendor's guidance for GPU servers; keep GPU, NIC, CPU cores, and memory local |
| SMT / Hyper-Threading | SMT | Hyper-Threading | Workload-dependent; follow the platform's recommended setting |
| IOMMU | amd_iommu=on iommu=pt (pass-through mode) when IOMMU is needed | intel_iommu=on iommu=pt | Full IOMMU translation can slow DMA and RDMA; pass-through keeps isolation features with less overhead |
| PCIe | Slots at full Gen5 x16; ACS (Access Control Services) settings that allow peer-to-peer where GPUDirect P2P/RDMA crosses PCIe switches; relaxed ordering where recommended | GPUDirect RDMA and P2P paths | |
| Memory | All memory channels populated evenly with identical DIMMs | Full memory bandwidth | |
OS-level tuning (both)
sudo cpupower frequency-set -g performance # CPU frequency governor
sudo tuned-adm profile throughput-performance # or the profile the vendor recommends
numactl -H ; nvidia-smi topo -m # which NUMA node / CPU cores each GPU and NIC is near
srun --cpu-bind=cores --gpus-per-task=1 ... # bind each rank to cores near its GPU
sudo mlnx_tune # NVIDIA networking tuning report / profiles
cat /sys/kernel/mm/transparent_hugepage/enabled # follow framework / vendor guidance
SYS in topo -m), a power-saving BIOS profile, or full IOMMU translation can pass every functional test and still be slower. Compare BIOS settings with a known-good node when one node underperforms.Deeper: AMD vs Intel server tuning guide (knob translator, ACS/IOMMU, NUMA pinning, locality checker).
5.5 Storage optimization
- Use the right network: storage traffic on the storage fabric with RDMA (IB, RoCE, NFS over RDMA) or many parallel TCP connections (NFS
nconnect), jumbo frames on Ethernet. - Parallel filesystems: stripe large files across many storage targets (for example Lustre
lfs setstripe -c -1on directories with large files); avoid millions of tiny files. - Local caching: stage datasets to the local NVMe RAID (
/raid) or use a caching layer, so every epoch doesn't hit shared storage. - GPUDirect Storage: DMA directly between storage and GPU memory, bypassing CPU bounce buffers.
- Data format and loader: fewer, larger files (sharded record formats), enough data-loader workers, prefetching, pinned memory.
- Checkpoints: asynchronous or distributed checkpointing; spread writes across storage targets.
- Measure before and after with fio / IOR / mdtest, and confirm GPUs are no longer waiting on input (DCGM activity metrics or Nsight Systems timelines).
Deeper: Lustre & third-party storage guide, filesystems and tuning, local caching, spotting input-bound jobs.
Master test matrix: which tool proves what
| Question | Tool | Scope | Pass looks like |
|---|---|---|---|
| Is the hardware healthy at the chassis level? | BMC / ipmitool / nvsm show health | Per node | No alerts |
| Are all nodes provisioned identically? | BCM (cmsh) | Cluster | All UP, same image |
| Does the node see all GPUs, with sane settings? | nvidia-smi | Per node | 8 GPUs, ECC on, no errors |
| Is each GPU's hardware sound? | dcgmi diag -r 3/4 | Per node / per GPU | All PASS |
| Do GPUs inside a node talk at full NVLink speed? | Single-node all_reduce_perf -g 8 | Per node | Expected busbw, #wrong 0 |
| Is the IB fabric up and cabled correctly? | ibstat, ibdiagnet, UFM | Fabric | All Active at 400, no errors |
| Does each IB link reach line rate? | ib_write_bw (perftest) | Node pairs / per rail | Close to 400 Gb/s |
| Which nodes or links are outliers across the whole cluster? Does the fabric hold up under simultaneous load? | ClusterKit (HPC-X). See the ClusterKit guide | All nodes, pairwise + simultaneous | No outlier pairs or nodes, effective bandwidth near pairwise |
| Does NCCL use the fabric properly across nodes? | mpirun/srun all_reduce_perf -g 1 | Pairs → full cluster | Near network limit, scales, #wrong 0 |
| Is storage fast enough? | fio, gdsio | Per node and aggregate | Meets spec |
| Can users run jobs? | Slurm (sinfo, srun), containers | Cluster | Jobs run on all nodes |
| Is the whole system stable and fast under sustained load? | HPL, real training, burn-in | Cluster | Expected performance, no errors over days |
DCGM vs nccl-tests vs perftest vs HPL
| DCGM diag | perftest (ib_write_bw) | nccl-tests (mpirun/srun) | HPL / training | |
|---|---|---|---|---|
| Layer | GPU hardware (in one node) | Raw IB link | GPU communication stack, intra- and inter-node | Whole system |
| Involves the network? | No (only intra-node PCIe/NVLink checks) | Yes (IB only, no NCCL) | Yes (NVLink + IB + GDR + NCCL) | Yes |
| Finds | Bad GPU memory, ECC, thermal, power, PCIe faults | Bad cable or port, degraded link | Misconfigured HCAs, socket fallback, no GDR, Fabric Manager, routing, slow node | Instability, throttling, overall performance gaps |
| Can pinpoint the faulty part? | Yes (GPU and test) | Yes (a specific link) | Partly (needs bisecting) | No (system-level) |
| When | First, on every node | After the IB fabric is up | After DCGM + perftest | Last |
Troubleshooting method: isolate and bisect
- Pin down the symptom: hang, error, slow, or wrong results? All nodes or some? Inside one node or across nodes?
- Go down the layers: if multi-node NCCL is slow, check single-node NCCL. If that's fine, it's the network. Then perftest, then
ibstat. - Bisect: split the node list in half, test each half, and repeat until you find the bad node or link.
- Compare with a known-good: diff firmware, driver, settings, and test results against a healthy node.
- Read the logs:
NCCL_DEBUG=INFO,dmesg(XIDs), DCGM health,ibdiagnetreports, Slurm logs. - Fix centrally: in BCM, fix the image or category rather than patching one node by hand. Drain the node before hardware work. RMA failing parts with DCGM or
nvsmevidence.
Sample outputs
What the commands in this guide print. Expand a command to see a typical result and what to check in it.
cmsh -c "device; list"Every node provisioned and UP
Type Hostname (key) MAC Category Ip Network Status
---------------- ---------------- ------------------ ---------------- ---------------- ---------------- ----------------
HeadNode bcm-head01 52:54:00:AA:00:01 10.141.255.254 internalnet [ UP ]
PhysicalNode dgx01 0C:42:A1:3E:00:01 dgx-h100 10.141.0.1 internalnet [ UP ]
PhysicalNode dgx02 0C:42:A1:3E:00:02 dgx-h100 10.141.0.2 internalnet [ UP ]
PhysicalNode dgx03 0C:42:A1:3E:00:03 dgx-h100 10.141.0.3 internalnet [ UP ]
PhysicalNode dgx04 0C:42:A1:3E:00:04 dgx-h100 10.141.0.4 internalnet [ UP ]
PhysicalNode dgx05 0C:42:A1:3E:00:05 dgx-h100 10.141.0.5 internalnet [ UP ]
PhysicalNode dgx06 0C:42:A1:3E:00:06 dgx-h100 10.141.0.6 internalnet [ UP ]
PhysicalNode dgx07 0C:42:A1:3E:00:07 dgx-h100 10.141.0.7 internalnet [ UP ]
PhysicalNode dgx08 0C:42:A1:3E:00:08 default 10.141.0.8 internalnet [ DOWN ]What to look at: The pass criterion is every compute node in category dgx-h100 and UP. dgx08 here is still in default and DOWN, so it either hasn't been assigned or failed to PXE boot.
nvidia-smiDriver, GPU count, persistence, ECC
Tue Nov 10 19:52:11 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.95.05 Driver Version: 580.95.05 CUDA Version: 13.0 |
+-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA H100 80GB HBM3 On | 00000000:1B:00.0 Off | 0 |
| N/A 31C P0 71W / 700W | 0MiB / 81559MiB | 0% Default |
| | | Disabled |
+-----------------------------------------+------------------------+----------------------+
| 1 NVIDIA H100 80GB HBM3 On | 00000000:43:00.0 Off | 0 |
| N/A 30C P0 69W / 700W | 0MiB / 81559MiB | 0% Default |
| | | Disabled |
+-----------------------------------------+------------------------+----------------------+
...
| 7 NVIDIA H100 80GB HBM3 On | 00000000:DF:00.0 Off | 0 |
| N/A 32C P0 72W / 700W | 0MiB / 81559MiB | 0% Default |
| | | Disabled |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+What to look at: Check the driver and CUDA versions in the header match your validated recipe, eight GPUs are listed, Persistence-M is On, and Volatile Uncorr. ECC is 0. "Failed to initialize NVML: Driver/library version mismatch" means a driver was upgraded without a reboot.
ofed_info -sInstalled OFED / DOCA-OFED version
OFED-internal-25.04-0.6.1:What to look at: Every node should report the same version. A MLNX_OFED_LINUX- prefix means the older MLNX_OFED stack, which DGX OS 7 replaces with DOCA-OFED; "command not found" means no OFED is installed.
lsmod | grep -E "mlx5_core|ib_core|nvidia_peermem"RDMA stack and GPUDirect RDMA modules
nvidia_peermem 16384 0
nvidia 11563008 152 nvidia_uvm,nvidia_peermem,nvidia_modeset
ib_core 520192 9 rdma_cm,ib_ipoib,nvidia_peermem,iw_cm,ib_umad,rdma_ucm,ib_uverbs,mlx5_ib,ib_cm
mlx5_core 2629632 1 mlx5_ib
mlxfw 36864 1 mlx5_coreWhat to look at: A nvidia_peermem line of its own means GPUDirect RDMA is loaded, and ib_core lists it as a user. If it's missing, NCCL still runs but stages through host memory and the log won't show GDRDMA.
nvcc --versionCUDA toolkit version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2025 NVIDIA Corporation
Built on Wed_Aug_20_01:58:59_PM_PDT_2025
Cuda compilation tools, release 13.0, V13.0.88
Build cuda_13.0.r13.0/compiler.36424714_0What to look at: The release line is the toolkit version, which must not be newer than the CUDA Version that nvidia-smi reports for the driver. "command not found" usually just means /usr/local/cuda/bin isn't on PATH, or the toolkit isn't installed.
ibstatHCA port state, rate, firmware
CA 'mlx5_0'
CA type: MT4129
Number of ports: 1
Firmware version: 28.43.1014
Hardware version: 0
Node GUID: 0x946dae0300a1b2c0
System image GUID: 0x946dae0300a1b2c0
Port 1:
State: Active
Physical state: LinkUp
Rate: 400
Base lid: 17
LMC: 0
SM lid: 1
Capability mask: 0xa751e848
Port GUID: 0x946dae0300a1b2c0
Link layer: InfiniBand
CA 'mlx5_1'
CA type: MT4129
...
State: Initializing
Physical state: LinkUp
Rate: 400
...What to look at: Every compute port should be Active, LinkUp, and Rate 400 (NDR) on ConnectX-7. Initializing with LinkUp means the cable is fine but no subnet manager has configured the port; Polling or Down means a cable or switch-port problem.
ibdev2netdevMap HCAs to interfaces and link state
mlx5_0 port 1 ==> ibp24s0 (Up)
mlx5_1 port 1 ==> ibp64s0 (Down)
mlx5_2 port 1 ==> ibp79s0 (Up)
mlx5_3 port 1 ==> ibp94s0 (Up)
mlx5_4 port 1 ==> ibp154s0 (Up)
mlx5_5 port 1 ==> ibp192s0 (Up)
mlx5_6 port 1 ==> ibp206s0 (Up)
mlx5_7 port 1 ==> ibp220s0 (Up)
...What to look at: All eight compute HCAs should show (Up). A (Down) entry, here mlx5_1, names the exact interface and cable to chase, and should match what ibstat reports for that HCA.
nvidia-smi --query-gpu=index,name,driver_version,persistence_mode,ecc.mode.current,mig.mode.current,pstate,temperature.gpu,power.limit --format=csvPer-GPU settings in one table
index, name, driver_version, persistence_mode, ecc.mode.current, mig.mode.current, pstate, temperature.gpu, power.limit [W]
0, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 31, 700.00 W
1, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 30, 700.00 W
2, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 32, 700.00 W
3, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 31, 700.00 W
4, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 29, 700.00 W
5, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Enabled, P0, 30, 700.00 W
6, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 31, 700.00 W
7, NVIDIA H100 80GB HBM3, 580.95.05, Enabled, Enabled, Disabled, P0, 33, 700.00 WWhat to look at: Every row should be identical apart from index and temperature; diff this output across nodes. Here GPU 5 has MIG enabled when the rest don't, and a power.limit below 700 W on an H100 SXM means a lowered cap.
nvidia-smi -q -d ECC,ROW_REMAPPERECC errors and row remapping
==============NVSMI LOG==============
Timestamp : Tue Nov 10 19:53:40 2026
Driver Version : 580.95.05
CUDA Version : 13.0
Attached GPUs : 8
GPU 00000000:1B:00.0
ECC Mode
Current : Enabled
Pending : Enabled
ECC Errors
Volatile
SRAM Correctable : 0
SRAM Uncorrectable Parity : 0
SRAM Uncorrectable SEC-DED : 0
DRAM Correctable : 0
DRAM Uncorrectable : 0
Aggregate
SRAM Correctable : 0
SRAM Uncorrectable Parity : 0
SRAM Uncorrectable SEC-DED : 0
DRAM Correctable : 12
DRAM Uncorrectable : 0
SRAM Threshold Exceeded : No
Remapped Rows
Correctable Error : 0
Uncorrectable Error : 0
Pending : No
Remapping Failure Occurred : No
Bank Remap Availability Histogram
Max : 2560 bank(s)
High : 0 bank(s)
Partial : 0 bank(s)
Low : 0 bank(s)
None : 0 bank(s)
GPU 00000000:43:00.0
...What to look at: Uncorrectable counts must be 0, Pending must be No, and Remapping Failure Occurred must be No. A few aggregate correctable errors are tolerated, but Pending: Yes needs a GPU reset, and a remapping failure or rising uncorrectable count means RMA.
nvidia-smi topo -mNVLink and GPU-to-NIC affinity
GPU0 GPU1 GPU2 GPU3 GPU4 GPU5 GPU6 GPU7 NIC0 NIC1 NIC2 NIC3 NIC4 NIC5 NIC6 NIC7 CPU Affinity NUMA Affinity GPU NUMA ID
GPU0 X NV18 NV18 NV18 NV18 NV18 NV18 NV18 PIX NODE NODE NODE SYS SYS SYS SYS 0-55,112-167 0 N/A
GPU1 NV18 X NV18 NV18 NV18 NV18 NV18 NV18 NODE PIX NODE NODE SYS SYS SYS SYS 0-55,112-167 0 N/A
GPU2 NV18 NV18 X NV18 NV18 NV18 NV18 NV18 NODE NODE PIX NODE SYS SYS SYS SYS 0-55,112-167 0 N/A
GPU3 NV18 NV18 NV18 X NV18 NV18 NV18 NV18 NODE NODE NODE PIX SYS SYS SYS SYS 0-55,112-167 0 N/A
GPU4 NV18 NV18 NV18 NV18 X NV18 NV18 NV18 SYS SYS SYS SYS PIX NODE NODE NODE 56-111,168-223 1 N/A
GPU5 NV18 NV18 NV18 NV18 NV18 X NV18 NV18 SYS SYS SYS SYS NODE PIX NODE NODE 56-111,168-223 1 N/A
GPU6 NV18 NV18 NV18 NV18 NV18 NV18 X NV18 SYS SYS SYS SYS NODE NODE PIX NODE 56-111,168-223 1 N/A
GPU7 NV18 NV18 NV18 NV18 NV18 NV18 NV18 X SYS SYS SYS SYS NODE NODE NODE PIX 56-111,168-223 1 N/A
NIC0 PIX NODE NODE NODE SYS SYS SYS SYS X NODE NODE NODE SYS SYS SYS SYS
NIC1 NODE PIX NODE NODE SYS SYS SYS SYS NODE X NODE NODE SYS SYS SYS SYS
NIC2 NODE NODE PIX NODE SYS SYS SYS SYS NODE NODE X NODE SYS SYS SYS SYS
NIC3 NODE NODE NODE PIX SYS SYS SYS SYS NODE NODE NODE X SYS SYS SYS SYS
NIC4 SYS SYS SYS SYS PIX NODE NODE NODE SYS SYS SYS SYS X NODE NODE NODE
NIC5 SYS SYS SYS SYS NODE PIX NODE NODE SYS SYS SYS SYS NODE X NODE NODE
NIC6 SYS SYS SYS SYS NODE NODE PIX NODE SYS SYS SYS SYS NODE NODE X NODE
NIC7 SYS SYS SYS SYS NODE NODE NODE PIX SYS SYS SYS SYS NODE NODE NODE X
Legend:
X = Self
SYS = Connection traversing PCIe as well as the SMP interconnect between NUMA nodes (e.g., QPI/UPI)
NODE = Connection traversing PCIe as well as the interconnect between PCIe Host Bridges within a NUMA node
PIX = Connection traversing at most a single PCIe bridge
NV# = Connection traversing a bonded set of # NVLinks
NIC Legend:
NIC0: mlx5_0
NIC1: mlx5_1
...What to look at: On a DGX H100 every GPU pair should be NV18 and each GPU should be PIX to its own NIC. A GPU pair showing SYS or PHB instead of NV18 means NVLink or Fabric Manager is down, and that pair falls back to PCIe.
nvidia-smi nvlink -sEvery NVLink up at full speed
GPU 0: NVIDIA H100 80GB HBM3 (UUID: GPU-3f9a1c2e-0b4d-4e71-9a55-1c0d2e3f4a01)
Link 0: 26.562 GB/s
Link 1: 26.562 GB/s
Link 2: 26.562 GB/s
...
Link 17: 26.562 GB/s
GPU 1: NVIDIA H100 80GB HBM3 (UUID: GPU-3f9a1c2e-0b4d-4e71-9a55-1c0d2e3f4a02)
Link 0: 26.562 GB/s
...
GPU 7: NVIDIA H100 80GB HBM3 (UUID: GPU-3f9a1c2e-0b4d-4e71-9a55-1c0d2e3f4a08)
Link 0: 26.562 GB/s
...
Link 5: <inactive>
...
Link 17: 26.562 GB/sWhat to look at: Each H100 should show 18 links, all at the same speed. Any <inactive> link, here on GPU 7, lowers NVLink bandwidth for that GPU and needs nvidia-smi nvlink -e and a support case.
dcgmi diag -r 3Long GPU diagnostic (level 3)
Successfully ran diagnostic for group.
+---------------------------+------------------------------------------------+
| Diagnostic | Result |
+===========================+================================================+
|----- Metadata ----------+------------------------------------------------|
| DCGM Version | 4.2.3 |
| Driver Version Detected | 580.95.05 |
| GPU Device IDs Detected | 2330,2330,2330,2330,2330,2330,2330,2330 |
|----- Deployment --------+------------------------------------------------|
| software | Pass |
+----- Integration -------+------------------------------------------------+
| pcie | Pass - All |
+----- Hardware ----------+------------------------------------------------+
| memory | Pass - All |
| diagnostic | Pass - All |
| nvbandwidth | Pass - All |
+----- Stress ------------+------------------------------------------------+
| targeted_stress | Pass - All |
| targeted_power | Pass - All |
| memory_bandwidth | Pass - All |
+---------------------------+------------------------------------------------+What to look at: Every test should read Pass for all GPUs. A Fail lists the GPU index and a reason (for example a PCIe or memory error), and a Warn on targeted_power often points to cooling or a lowered power limit.
./all_reduce_perf -b 8 -e 8G -f 2 -g 8Single-node NCCL over NVLink
# nThread 1 nGpus 8 minBytes 8 maxBytes 8589934592 step: 2(factor) warmup iters: 5 iters: 20 agg iters: 1 validation: 1 graph: 0
#
# Using devices
# Rank 0 Group 0 Pid 41210 on dgx01 device 0 [0x1b] NVIDIA H100 80GB HBM3
# Rank 1 Group 0 Pid 41210 on dgx01 device 1 [0x43] NVIDIA H100 80GB HBM3
...
# Rank 7 Group 0 Pid 41210 on dgx01 device 7 [0xdf] NVIDIA H100 80GB HBM3
#
# out-of-place in-place
# size count type redop root time algbw busbw #wrong time algbw busbw #wrong
# (B) (elements) (us) (GB/s) (GB/s) (us) (GB/s) (GB/s)
8 2 float sum -1 24.91 0.00 0.00 0 24.33 0.00 0.00 0
16 4 float sum -1 24.60 0.00 0.00 0 24.48 0.00 0.00 0
...
67108864 16777216 float sum -1 357.2 187.88 328.79 0 355.9 188.56 329.98 0
134217728 33554432 float sum -1 621.4 215.99 377.99 0 619.8 216.55 378.96 0
...
4294967296 1073741824 float sum -1 16091 266.92 467.11 0 16077 267.15 467.51 0
8589934592 2147483648 float sum -1 32042 268.08 469.15 0 32019 268.28 469.49 0
# Out of bounds values : 0 OK
# Avg bus bandwidth : 171.094
#What to look at: Look at busbw for the largest sizes (about 450 GB/s or more is typical for a healthy DGX H100) and #wrong, which must be 0. The Avg bus bandwidth line is dragged down by small messages, so don't compare it with the peak.
ib_write_bw -d mlx5_0 --report_gbits nodeARDMA bandwidth between two nodes
---------------------------------------------------------------------------------------
RDMA_Write BW Test
Dual-port : OFF Device : mlx5_0
Number of qps : 1 Transport type : IB
Connection type : RC Using SRQ : OFF
PCIe relax order: ON
ibv_wr* API : ON
TX depth : 128
CQ Moderation : 1
Mtu : 4096[B]
Link type : IB
Max inline data : 0[B]
rdma_cm QPs : OFF
Data ex. method : Ethernet
---------------------------------------------------------------------------------------
local address: LID 0x11 QPN 0x0128 PSN 0x5a3c1e RKey 0x1fff00 VAddr 0x007f3a2c000000
remote address: LID 0x2b QPN 0x0129 PSN 0x7b2d4f RKey 0x1fff01 VAddr 0x007f91e8000000
---------------------------------------------------------------------------------------
#bytes #iterations BW peak[Gb/sec] BW average[Gb/sec] MsgRate[Mpps]
65536 5000 392.45 392.31 0.748270
---------------------------------------------------------------------------------------What to look at: On a 400 Gb/s NDR link, BW average should be close to line rate (around 390 Gb/s). Half that or less points to a link trained at lower speed or width, a bad cable, or the wrong HCA chosen for the GPU.
sinfo ; scontrol show node dgx01 | grep -E "Gres|State"Nodes idle with 8 GPUs in Slurm
PARTITION AVAIL TIMELIMIT NODES STATE NODELIST
batch* up infinite 7 idle dgx[01-07]
batch* up infinite 1 down* dgx08
Gres=gpu:8
State=IDLE ThreadsPerCore=2 TmpDisk=0 Weight=1 Owner=N/A MCS_label=N/AWhat to look at: All nodes should be idle and each should show Gres=gpu:8. down* means slurmctld can't reach slurmd on that node, and Gres=(null) or a lower GPU count means gres.conf or the slurmclient role is wrong.
ipmitool -I lanplus -H $BMC -U $BMC_USER -E sdr type "Power Supply"Every PSU present and OK
PSU0_Status | 8Ah | ok | 10.0 | Presence detected
PSU1_Status | 8Bh | ok | 10.1 | Presence detected
PSU2_Status | 8Ch | ok | 10.2 | Presence detected
PSU3_Status | 8Dh | ok | 10.3 | Presence detected
PSU4_Status | 8Eh | ok | 10.4 | Presence detected, Power Supply AC lost
PSU5_Status | 8Fh | ok | 10.5 | Presence detectedWhat to look at: Read the last column, not the ok in the middle: a healthy PSU says only Presence detected. "Power Supply AC lost" or "Failure detected" means a dead feed or PSU, so the node has lost power redundancy.
lspci | grep -i nvidiaGPUs and NVSwitches on the PCIe bus
05:00.0 Bridge: NVIDIA Corporation Device 22a3 (rev a1)
06:00.0 Bridge: NVIDIA Corporation Device 22a3 (rev a1)
07:00.0 Bridge: NVIDIA Corporation Device 22a3 (rev a1)
08:00.0 Bridge: NVIDIA Corporation Device 22a3 (rev a1)
1b:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
43:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
52:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
61:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
9d:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
c3:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
d1:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)
df:00.0 3D controller: NVIDIA Corporation GH100 [H100 SXM5 80GB] (rev a1)What to look at: Expect eight 3D controller lines (GPUs) and four NVSwitch bridge lines on a DGX H100. A GPU missing here is a hardware or PCIe problem below the driver, so no software fix will bring it back.
sudo lspci -vv -s 1b:00.0 | grep -E "LnkCap|LnkSta"PCIe link speed and width
LnkCap: Port #0, Speed 32GT/s, Width x16, ASPM not supported
LnkSta: Speed 32GT/s, Width x16
LnkCap2: Supported Link Speeds: 2.5-32GT/s, Crosslink- Retimer+ 2Retimers+ DRS-
LnkSta2: Current De-emphasis Level: -3.5dB, EqualizationComplete+ EqualizationPhase1+What to look at: LnkSta must match LnkCap: Speed 32GT/s, Width x16 for an H100 on PCIe Gen5. A downgraded link such as "Speed 16GT/s, Width x8 (downgraded)" points to a seating, riser, or retimer problem and caps host-to-device bandwidth.
cat /etc/dgx-releaseInstalled DGX OS release and upgrades
DGX_NAME="DGX Server"
DGX_PRETTY_NAME="NVIDIA DGX Server"
DGX_SWBUILD_DATE="2025-06-12-09-41-17"
DGX_SWBUILD_VERSION="7.1.0"
DGX_COMMIT_ID="4b1d9e7"
DGX_PLATFORM="DGX Server for DGX H100"
DGX_SERIAL_NUMBER="<redacted>"
DGX_OTA_VERSION="7.2.0"
DGX_OTA_DATE="Thu Aug 21 10:14:52 AM UTC 2025"
DGX_OTA_VERSION="7.3.1"
DGX_OTA_DATE="Mon Nov 2 03:22:10 PM UTC 2026"What to look at: DGX_SWBUILD_VERSION is the ISO the node was imaged with, and the last DGX_OTA_VERSION is the release it is on now (7.3.1 here). Nodes with different final OTA versions aren't on one validated recipe.
sudo apt full-upgrade -sDry run: what an upgrade would change
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
The following NEW packages will be installed:
linux-image-6.8.0-1032-nvidia linux-modules-6.8.0-1032-nvidia
The following packages will be upgraded:
datacenter-gpu-manager-4-core datacenter-gpu-manager-4-cuda13 libnvidia-nscq
nvidia-driver-580-open nvidia-fabricmanager nvidia-system-core ...
37 upgraded, 4 newly installed, 0 to remove and 0 not upgraded.
Inst nvidia-fabricmanager [580.82.07-1] (580.95.05-1 NVIDIA CUDA:cuda [amd64])
Inst nvidia-driver-580-open [580.82.07-0ubuntu1] (580.95.05-0ubuntu1 NVIDIA CUDA:cuda [amd64])
...
Conf nvidia-driver-580-open (580.95.05-0ubuntu1 NVIDIA CUDA:cuda [amd64])What to look at: Check that the driver and Fabric Manager move to the same version together and that nothing important is listed under "to remove". A new kernel or driver in the list means a reboot is required after the real upgrade.
sudo nvidia-release-upgradeDGX OS 6 to 7 release upgrade
Checking for a new Ubuntu release
...
Continue running under SSH?
This session appears to be running under ssh. It is not recommended
to perform a upgrade over ssh currently because in case of failure it
is harder to recover.
If you continue, an additional ssh daemon will be started at port
'1022'.
Do you want to continue?
Continue [yN] y
...
Do you want to start the upgrade?
5 installed packages are no longer supported by Canonical. You can
still get support from the community.
48 packages are going to be removed. 412 new packages are going to be
installed. 2187 packages are going to be upgraded.
You have to download a total of 3,912 M. This download will take
about 6 minutes with your connection.
Continue [yN] Details [d] y
...
System upgrade is complete.
Restart required
To finish the upgrade, a restart is required.
If you select 'y' the system will be restarted.
Continue [yN] yWhat to look at: The SSH warning and the spare sshd on port 1022 are expected when not on the BMC console. "No new release found" means the node isn't on the latest DGX OS 6.x yet, so run apt full-upgrade first; after the reboot, cat /etc/dgx-release should show a 7.x version.
sudo mlxlink -d mlx5_0 -cLink counters and BER
Operational Info
----------------
State : Active
Physical state : LinkUp
Speed : IB-NDR
Width : 4x
FEC : Interleaved_Standard_RS_FEC_PLR - (544,514)
Loopback Mode : No Loopback
Auto Negotiation : ON
Troubleshooting Info
--------------------
Status Opcode : 0
Group Opcode : N/A
Recommendation : No issue was observed
Physical Counters and BER Info
------------------------------
Time Since Last Clear [Min] : 1442.6
Effective Physical Errors : 0
Effective Physical BER : 15E-255
Raw Physical Errors Per Lane : 102,98,131,87
Raw Physical BER : 3E-12
Link Down Counter : 0
Link Error Recovery Counter : 0What to look at: Speed should be IB-NDR at 4x width with Recommendation "No issue was observed". Some raw (pre-FEC) errors are normal, but Effective Physical Errors above 0, a raw BER worse than about 1E-8, or a growing Link Down Counter points to a bad cable or transceiver.
Problem scenarios (44). Click to expand
Scenarios 27–42 map to specific blueprint objectives (shown in the LAYER line).
For each one, try to name the layer and cause before you open it.
Searchable command reference
| Command | Purpose | Phase |
|---|
Exam heuristics and traps
- "First step" or "before running multi-node tests" → validate individual nodes first (nvidia-smi, DCGM diag), not a full-cluster NCCL run.
- "Verify GPU hardware health" / "burn-in" → DCGM diag level 3/4. "Verify interconnect performance" → nccl-tests (and perftest for raw IB).
- Single-node NCCL test tests only NVLink/NVSwitch. IB settings are irrelevant to it.
- IB ports stuck in "Initializing" → no Subnet Manager (start UFM/OpenSM). Not a NCCL setting.
- Rate shows 200 instead of 400 → degraded link: cable, transceiver, or port.
- CUDA error "system not yet initialized" (802) on an NVSwitch system → Fabric Manager not running, or its version doesn't match the driver.
- Mixed firmware/driver versions across nodes → standardize (with BCM, through the image) before debugging anything else.
- Pair tests fine but the full cluster is slow → look higher in the fabric: spine links, routing, congestion, a bad node in the larger set (bisect).
- One node consistently slower in HPL → thermal or power throttling, a weak GPU. Check
nvidia-smi -q -d PERFORMANCEand DCGM. - Slurm node DOWN, "munge" errors → munge key mismatch or clock skew (fix NTP/chrony).
- Containers can't use IB → pass
/dev/infiniband, IPC_LOCK, memlock, shm. #wrong ≠ 0→ data corruption: hardware, not tuning.- "Fix it on the node by hand" in a BCM cluster → usually wrong. Change the image or category and reprovision.
bcm-pod-setup→ initial BasePOD configuration only, run on the head node. Never re-run it after deployment, after reboots, per node, or as a "reset." Usecmshfor later changes.- Average bus bandwidth includes tiny messages. Judge peak with large-message busbw.
- Secure Boot on and the nvidia module won't load → unsigned module or unenrolled key (MOK). Sign/enroll; don't just disable Secure Boot.
- BlueField behaving like a plain NIC vs running its own Arm OS → NIC mode vs DPU mode, set with
mlxconfigand applied after a power cycle. - MIG changes "not taking effect" → MIG mode needs a GPU reset (no processes on it), and instances must be recreated after a reboot unless a config manager reapplies them.
- Head-node failover questions → BCM HA (
cmha-setup,cmha status), shared storage for the HA directories, and a failover test before handover. - PCIe device slower but error-free → compare
LnkStawithLnkCap(downtrained speed/width). - Replacing a part → drain, replace, bring firmware to the cluster baseline, update the MAC in BCM if a NIC/board changed, then re-run DCGM and NCCL before returning it to service.
Practice quiz (73 questions)
Filter by domain: