fix(installer): explain failed OpenIB service

[senthilr-nv]

Summary

Station preparation currently reports only a generic failed-unit error when openibd.service blocks installation. This change preserves the fail-closed gate while explaining that NemoClaw does not require RDMA and giving host owners precise disable-or-repair remediation without changing systemd or networking state.

Related Issue

Fixes #7151

Changes

• Print bounded default-route and NFS mount checks when openibd.service is an unqualified failed unit.
• Direct owners who do not use RDMA to disable the unused service, reboot, and rerun; direct RDMA users to repair OpenIB/OFED.
• Preserve the existing fatal exit and explicitly state that NemoClaw made no systemd or networking changes.
• Add focused regression coverage proving the OpenIB diagnostic and unchanged generic behavior for unrelated failed units.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: existing Station documentation already states that unqualified failed services require administrator review; the new context-sensitive terminal guidance supplies the exact remediation at the failure point.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: fail-closed behavior is unchanged, no diagnostic command is executed, and no systemd or networking state is modified; the boundary is recorded in fix(installer): explain failed OpenIB service during Station preparation #7151.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run test/install-station-openibd-remediation.test.ts test/install-station-host-preparation.test.ts (2 files, 57 tests passed)
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Added OpenIB-specific remediation guidance when DGX Station setup detects failures related to openibd.service, including conditional next steps based on whether RDMA networking is used.
  • Preserved the existing generic failure handling for unrelated failed services.
• Tests
  • Added a Vitest suite that validates the expected remediation messaging for openibd.service failures and confirms unrelated failures don’t trigger OpenIB-specific guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8282099d-1428-4b18-9122-d3bae3125408

📥 Commits

Reviewing files that changed from the base of the PR and between 3c35730 and 151ea64.

📒 Files selected for processing (2)

• scripts/prepare-dgx-station-host.sh
• test/install-station-openibd-remediation.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• scripts/prepare-dgx-station-host.sh
• test/install-station-openibd-remediation.test.ts

---

📝 Walkthrough

Walkthrough

Station preparation now emits targeted remediation guidance when openibd.service fails while continuing to block preparation. Tests verify the OpenIB-specific output and preserve generic fail-closed handling for unrelated failed units.

Changes

OpenIB remediation

Layer / File(s)	Summary
OpenIB failure diagnostics scripts/prepare-dgx-station-host.sh	Adds RDMA-specific disable-or-repair guidance for failed openibd.service units without changing host state.
Remediation behavior tests test/install-station-openibd-remediation.test.ts	Runs the script with controlled failed-unit responses and verifies OpenIB-specific and generic failure output paths.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: area: install, bug-fix, platform: dgx-station

Suggested reviewers: apurvvkumaria, ericksoa

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change to OpenIB failure handling.
Linked Issues check	✅ Passed	The changes add openibd-specific fail-closed remediation and tests, matching the issue requirements.
Out of Scope Changes check	✅ Passed	The PR stays focused on openibd remediation and regression tests without unrelated changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/install-station-openibd-remediation.test.ts (1)

23-25: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Exercise the supported --apply boundary.

checkFailedUnit() sources the script and calls check_failed_units directly, bypassing the bash "$helper" --apply path used by scripts/install.sh at Lines 3492-3550. Add at least one test that invokes the script through its supported entrypoint so argument handling and orchestration regressions cannot pass unnoticed.

As per path instructions, tests should validate observable behavior through the public boundary rather than lock onto implementation details.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/install-station-openibd-remediation.test.ts` around lines 23 - 25,
Extend the tests around check_failed_units to invoke the script through its
supported entrypoint with --apply, rather than only sourcing SCRIPT_UNDER_TEST
and calling the helper directly. Assert the observable remediation behavior and
retain any direct-helper coverage only where needed, ensuring argument parsing
and orchestration are exercised through the public boundary.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/install-station-openibd-remediation.test.ts`:
- Line 48: Update the assertions for both spawnSync results in the OpenIBD
remediation test to explicitly require result.error to be undefined and
result.status to be non-null before asserting the exit status is nonzero. Apply
this to the assertions near the existing openibd.result.status checks,
preserving the output context in failures.

---

Nitpick comments:
In `@test/install-station-openibd-remediation.test.ts`:
- Around line 23-25: Extend the tests around check_failed_units to invoke the
script through its supported entrypoint with --apply, rather than only sourcing
SCRIPT_UNDER_TEST and calling the helper directly. Assert the observable
remediation behavior and retain any direct-helper coverage only where needed,
ensuring argument parsing and orchestration are exercised through the public
boundary.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 83b6bb34-6fef-481d-9be6-312db11ea636

📥 Commits

Reviewing files that changed from the base of the PR and between 227570f and 4b3cfdd.

📒 Files selected for processing (2)

• scripts/prepare-dgx-station-host.sh
• test/install-station-openibd-remediation.test.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections match; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[ericksoa]

Approved at exact head 3dc37d6a48c58bc4826b6d402586d071945626aa against current base fce12723d10fcd9ba91da1e8d57704b542aad9e6 after maintainer review. The change remains fail-closed: it adds bounded remediation guidance for a failed openibd.service, does not disable or ignore services, does not mutate systemd/network/driver state, and preserves the metadata-only --force-station-install boundary. Focused tests passed 57/57 locally; exact-head CI reports 43 successes, 6 intentional skips, and no pending or failing checks; all five commits are GitHub Verified; CodeRabbit and both review-advisor lanes are clear; and no review threads remain unresolved. The local maintainer helper has a confirmed fork-association false negative because GitHub returns pull_requests: [] for these otherwise exact-head runs; lead-admin authorization accepts that tooling exception for this revision.