scott
3361fdd1a6
Adds workflow_check.py: a read-only diagnostic that queries current network settings and firmware versions (IOM + Fabric Card) from both IOMs. Accessible via a new main menu option (3 — System Check); Exit moves to option 4. Supports both serial console (curl over the serial session) and direct network (HTTPS to management IP) connection methods. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Running the Tool
|
|
|
|
```bash
|
|
python3 es24n_conf.py
|
|
```
|
|
|
|
The script requires root or appropriate serial device permissions. If the serial device is inaccessible, re-run with `sudo`.
|
|
|
|
## What This Is
|
|
|
|
An interactive CLI tool for configuring and updating TrueNAS ES24N expansion shelf IOM (I/O Module) controllers via the Redfish API. It supports two connection methods:
|
|
|
|
- **Serial (loopback):** Connects via USB serial cable to the IOM1 console port, then reaches the Redfish API at `https://127.0.0.1` using `root` credentials. Used for initial network configuration when the IOM has no IP address yet.
|
|
- **Network:** Connects directly to the IOM's management IP address using `Admin` credentials. Used for firmware updates and (planned) network reconfiguration once the IOM is reachable on the network.
|
|
|
|
No external dependencies — Python 3 standard library only. Compatible with TrueNAS (FreeBSD) and Linux.
|
|
|
|
## File Structure
|
|
|
|
```
|
|
es24n_conf.py ← Entry point and main menu (run this)
|
|
modules/
|
|
ui.py ← ANSI colours, display helpers, input prompts
|
|
serial_port.py ← SerialPort class (termios/fcntl/select, no pyserial)
|
|
models.py ← IOMConfig and ShelfConfig dataclasses
|
|
redfish.py ← Redfish API client (shared by all workflows)
|
|
workflow_serial.py ← Serial-based IOM network configuration workflow
|
|
workflow_firmware.py ← IOM and Fabric Card firmware update workflow
|
|
workflow_check.py ← Read-only system check (network settings + firmware versions)
|
|
```
|
|
|
|
`es24n_conf.py` adds `modules/` to `sys.path` at startup so all inter-module imports work without a package structure.
|
|
|
|
## Workflows
|
|
|
|
### 1 — Serial Network Configuration (`workflow_serial.py`)
|
|
5-step workflow using the USB serial cable:
|
|
1. Detect USB serial device (`/dev/ttyUSB*`, `/dev/ttyACM*`, `/dev/ttyU*`)
|
|
2. Open 115200-baud 8N1 connection and wake the IOM console
|
|
3. Query current network settings via Redfish (`GET` over `127.0.0.1`)
|
|
4. Collect new settings from user (Static IP or DHCP)
|
|
5. Apply via Redfish `PATCH` over `127.0.0.1`
|
|
|
|
### 2 — Firmware Update (`workflow_firmware.py`)
|
|
Updates IOM firmware and/or Fabric Card firmware over the network:
|
|
- Prompts for which IOM(s) to update (IOM1, IOM2, or both)
|
|
- Uploads firmware via `POST` to `/redfish/v1/UpdateService` (multipart form)
|
|
- Triggers update via Redfish `SimpleUpdate` action
|
|
- Polls `/redfish/v1/TaskService/Tasks/` until completion
|
|
- Restarts the IOM (and fabric card if applicable) after each update
|
|
- The firmware file must be re-uploaded between the IOM and Fabric Card steps — it does not persist after the first update (firmware quirk, documented in `_update_fabric_fw()`)
|
|
- Scans the current working directory for firmware files (`.bin`, `.img`, `.fw`, `.hex`, `.zip`, `.tar`, `.tgz`, `.gz`) and presents them as a numbered list before falling back to manual path entry
|
|
|
|
### 3 — System Check (`workflow_check.py`)
|
|
Read-only diagnostic workflow — queries current network settings and firmware versions, makes no changes:
|
|
- **Serial:** logs in via serial console, queries both IOMs using `_serial_redfish_request()` (curl over the serial session); covers network settings, IOM firmware, and Fabric Card firmware
|
|
- **Network:** prompts for management IP(s), queries via direct HTTPS using `Admin` credentials; reuses `_redfish_request()`, `_get_iom_fw_version()`, `_get_fabric_fw_version()` from `redfish.py`
|
|
- Displays results in two tables: network configuration and firmware versions
|
|
- User selects Serial, Network, or Cancel at the sub-menu prompt
|
|
|
|
## Key Design Notes
|
|
|
|
**Static IP firmware bug workaround:** Setting a static IP requires two sequential PATCH requests:
|
|
- Pass 1: set `IPv4StaticAddresses` (while DHCP is still enabled)
|
|
- Pass 2: disable `DHCPv4` (after the address is committed)
|
|
|
|
A single PATCH combining both fields fails due to a known ES24N firmware bug. Documented in `_apply_iom()` in `workflow_serial.py`.
|
|
|
|
**Authentication:**
|
|
- Serial loopback (`127.0.0.1`): username `root`
|
|
- Network IP: username `Admin`
|
|
|
|
**Redfish API paths:**
|
|
- Network config: `/redfish/v1/Managers/{IOM1|IOM2}/EthernetInterfaces/1`
|
|
- Firmware update: `/redfish/v1/UpdateService`
|
|
- Fabric card: `/redfish/v1/Chassis/{IOM1|IOM2}/NetworkAdapters/1`
|
|
|
|
## Planned Features
|
|
|
|
- Network-based IOM network configuration (`workflow_network.py`) — same config workflow as serial but connecting via the IOM's existing IP address using `Admin` credentials, for cases where the IOM is already reachable on the network
|
|
- Auto-detect password from serial login prompt — the IOM BMC serial number (e.g. `MXE3000043CHA007`) appears to be embedded in the login prompt hostname; if confirmed on a live system, this could allow `_login_serial_console()` to skip the manual password prompt
|