Initial commit — bootstrapped from es24n-conf (TrueNAS/Linux edition)
Starting point for Windows packaging. Serial backend will be replaced with pyserial; PyInstaller used to produce a standalone .exe. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
92
CLAUDE.md
Normal file
92
CLAUDE.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# 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)
|
||||
workflow_restart.py ← Restart IOM via network or serial
|
||||
```
|
||||
|
||||
`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. The serial cable connects to one IOM's console port at a time — the user is prompted to select IOM1 or IOM2 after login, and all Redfish paths use that selection.
|
||||
1. Detect USB serial device (`/dev/ttyUSB*`, `/dev/ttyACM*`, `/dev/ttyU*`)
|
||||
2. Open 115200-baud 8N1 connection and wake the IOM console
|
||||
3. Prompt for IOM1 or IOM2, then 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 `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:** prompts for IOM1 or IOM2, logs in via serial console, queries the selected IOM 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
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user