es24n-conf/CLAUDE.md

# 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:
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 `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 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

## 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