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

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