scott
76ee347d91
The serial cable connects to IOM1's console port. IOM2 cannot be queried or configured via the serial connection. Updated all serial-path code to reflect this: workflow_serial.py: - fetch_current_config: query IOM1 only, single-row table - collect_network_config: prompt for IOM1 settings only, drop IOM2 section - apply_configuration: apply to IOM1 only, single-row result table - print_summary: IOM1-only table, updated warning text workflow_check.py (_check_via_serial): - Query IOM1 only for network settings, IOM firmware, and Fabric Card firmware CLAUDE.md updated to document the IOM1-only serial limitation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
92 lines
5.6 KiB
Markdown
92 lines
5.6 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)
|
|
firmware/ ← Firmware files (.bin, .img, .fw, etc.) — scanned at update time
|
|
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. **Serial access is limited to IOM1 only** — the cable connects to IOM1's console port; IOM2 cannot be queried or configured this way.
|
|
1. Detect USB serial device (`/dev/ttyUSB*`, `/dev/ttyACM*`, `/dev/ttyU*`)
|
|
2. Open 115200-baud 8N1 connection and wake the IOM console
|
|
3. Query IOM1 current network settings via Redfish (`GET` over `127.0.0.1`)
|
|
4. Collect new settings from user (Static IP or DHCP) for IOM1
|
|
5. Apply via Redfish `PATCH` over `127.0.0.1` to IOM1
|
|
|
|
### 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 `firmware/` directory (next to `es24n_conf.py`) for firmware files (`.bin`, `.img`, `.fw`, `.fwc`, `.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 IOM1 only using `_serial_redfish_request()` (curl over the serial session); covers network settings, IOM firmware, and Fabric Card firmware. IOM2 is not reachable over serial.
|
|
- **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
|
|
|
|
## Reference Documentation
|
|
|
|
The `docs/` directory contains reference documentation for this project. Check all files there for any Redfish API commands, request/response formats, field names, or configuration procedures when working on this project.
|
|
|
|
## 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`, password auto-detected from hostname
|
|
- Network IP: username `Admin`, password prompted from user
|
|
|
|
**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`
|
|
|
|
**Serial password auto-detection:** The IOM BMC serial number is embedded in the hostname shown on the serial login prompt (e.g. `ves-ves-vds2249r-MXE3000048LHA03C-mgr1 login:`). The `MXE...` segment is the root password. `_login_serial_console()` extracts it automatically — from the login prompt hostname if a login is needed, or by running `hostname` on the shell if already logged in. Falls back to `prompt_password()` if extraction fails.
|
|
|
|
## 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
|