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