Docs: Managing IPMI Credentials via the REST API

[sethesterline]

Summary

Add a reference section to the existing IPMI page (or a companion page) documenting how to read and update node IPMI credentials programmatically via the VergeOS REST API, including how to locate the node ID required for the calls.

Type

Reference / How-to Guide

Suggested Content

• Audience: Administrators and automation engineers managing IPMI credentials at scale or via scripts
• Prerequisites: Familiarity with the VergeOS REST API and API key authentication; existing IPMI page covers UI-based credential management

Key sections to add:

1. Finding the Node ID

• GET /api/v4/nodes — list all nodes; response includes $key (row key) and fields like name, ipmi_address, ipmi_status
• Filter example: GET /api/v4/nodes?filter=name eq "node1" to locate a specific node by name
• Note that $key from this response is what subsequent calls use

2. Reading IPMI Information

• GET /api/v4/nodes/{key} — retrieve a single node record
• IPMI-relevant fields to call out:

Field	Description
ipmi_address	BMC IP address or hostname
ipmi_user	BMC username
ipmi_password	Stored encrypted — not returned in plaintext
ipmi_status	ready / connecting / offline / error
ipmi_sel_free / ipmi_sel_used	System Event Log capacity counters

3. Setting IPMI Credentials

• PUT /api/v4/nodes/{key} with body:

{
  "ipmi_user": "admin",
  "ipmi_password": "newpassword"
}

• Note: saving credentials automatically triggers a backend connectivity test — no manual ipmi_test action required after a credential PUT
• Verify success by checking ipmi_status returns ready after the update

4. Triggering IPMI Actions via node_actions

• For manual test or SEL clear without a credential change:

POST /api/v4/node_actions
Content-Type: application/json

{
  "$row": "/v4/nodes/{key}",
  "action": "ipmi_test"
}

• Other available actions: clear_sel

5. Caveats

• IPMI applies to host-level nodes only — not tenant nodes
• ipmi_password is write-only via the API; reads return the field encrypted/masked

Context

Requested via support interaction. A customer needed to update IPMI credentials programmatically across multiple nodes. The existing IPMI page covers only the UI workflow; there is no public documentation for the API path.