111 lines
5.0 KiB
Markdown
111 lines
5.0 KiB
Markdown
# ES24N IOM Configuration Tool
|
|
|
|
An interactive CLI tool for configuring network settings and updating firmware on TrueNAS ES24N expansion shelf IOM (I/O Module) controllers via the Redfish API.
|
|
|
|
## Requirements
|
|
|
|
- Python 3 (standard library only — no external dependencies)
|
|
- Root or serial device group permissions (for serial-based configuration)
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python3 es24n_conf.py
|
|
```
|
|
|
|
If the serial device is inaccessible, re-run with `sudo`:
|
|
|
|
```bash
|
|
sudo python3 es24n_conf.py
|
|
```
|
|
|
|
## Features
|
|
|
|
### Network Configuration
|
|
|
|
Configure each IOM's management network interface via the Redfish API. Two connection methods are supported:
|
|
|
|
**Serial** — Connects over a USB serial cable using the Redfish loopback (`127.0.0.1`). Used for initial setup when the IOM has no IP address yet.
|
|
|
|
**Network** — Connects directly to the IOM's existing management IP. Used when the IOM is already reachable on the network (e.g. currently on DHCP) and needs its settings changed.
|
|
|
|
Both methods support **Static IP** and **DHCP** configuration, display current settings before making any changes, and support configuring multiple IOMs back-to-back in a single session.
|
|
|
|
### Firmware Updates
|
|
|
|
Connects to each IOM directly over the network and updates IOM and/or Fabric Card firmware via the Redfish API.
|
|
|
|
- Select IOM1 only, IOM2 only, or both
|
|
- Update IOM firmware, Fabric Card firmware, or both in a single run
|
|
- Scans the `firmware/` directory for firmware files automatically
|
|
- Displays current firmware versions before and after the update
|
|
- Polls update task progress automatically
|
|
|
|
### System Check
|
|
|
|
Read-only diagnostic — queries current network settings and firmware versions without making any changes. Available via serial or network connection.
|
|
|
|
### Restart IOM
|
|
|
|
Sends a graceful restart to a selected IOM via network or serial connection.
|
|
|
|
## Workflows
|
|
|
|
### Configure Network Settings — Serial
|
|
|
|
1. Connect the serial cable from the ES24N IOM console port to the controller's USB port
|
|
2. Run the tool, select **Configure Network Settings**, then **Serial Connection**
|
|
3. The tool detects the serial device, opens the connection, and auto-detects the root password from the IOM hostname
|
|
4. Select which IOM the cable is connected to (IOM1 or IOM2)
|
|
5. Current network settings are displayed
|
|
6. Choose Static IP or DHCP, or leave settings unchanged
|
|
7. Changes are applied via Redfish PATCH over the serial loopback (`127.0.0.1`)
|
|
8. Verify the expander appears in TrueNAS under **System Settings > Enclosure > NVMe-oF Expansion Shelves** before disconnecting the serial cable
|
|
|
|
### Configure Network Settings — Network
|
|
|
|
1. Ensure this system has network access to the IOM management interface
|
|
2. Run the tool, select **Configure Network Settings**, then **Network Connection**
|
|
3. Enter the Admin password and the IOM's current IP address
|
|
4. Select which IOM to configure (IOM1 or IOM2)
|
|
5. Current network settings are displayed
|
|
6. Choose Static IP or DHCP, or leave settings unchanged
|
|
7. Changes are applied via Redfish PATCH directly to the IOM
|
|
|
|
> **Note:** If changing to a static IP, the IOM will immediately move to the new address. The connection to the old IP will stop working after the change is applied.
|
|
|
|
### Update Firmware
|
|
|
|
1. Ensure this system has network access to the IOM management interfaces
|
|
2. Run the tool and select **Update IOM / Fabric Card Firmware**
|
|
3. Select which IOM(s) to update
|
|
4. Enter the Admin password and IP address for each shelf
|
|
5. Select what to update (IOM firmware, Fabric Card firmware, or both)
|
|
6. Select a firmware file from the auto-detected list or enter a custom path
|
|
7. The tool uploads, applies, and monitors each update, then restarts the affected components
|
|
|
|
> **HA Systems:** Update the passive IOM first. After updating both IOMs on one controller, initiate a TrueNAS failover and re-run the tool for the other controller.
|
|
|
|
## File Structure
|
|
|
|
```
|
|
es24n_conf.py ← Entry point — run this
|
|
firmware/ ← Place firmware files here (.bin, .img, .fw, .fwc, etc.)
|
|
modules/
|
|
ui.py ← Display helpers and input prompts
|
|
serial_port.py ← Serial port driver (no pyserial required)
|
|
models.py ← IOMConfig and ShelfConfig data classes
|
|
redfish.py ← Redfish API client (shared by all workflows)
|
|
workflow_serial.py ← Serial-based network configuration workflow
|
|
workflow_network.py ← Network-based network configuration workflow
|
|
workflow_firmware.py ← Firmware update workflow
|
|
workflow_check.py ← Read-only system check workflow
|
|
workflow_restart.py ← IOM restart workflow
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Setting a static IP requires two sequential Redfish PATCH requests due to a known ES24N firmware bug. The tool handles this automatically for both serial and network configuration.
|
|
- Firmware uploads are performed over the network — uploading over the 115200-baud serial connection would be impractically slow.
|
|
- The firmware file must be re-uploaded between the IOM firmware and Fabric Card firmware steps as it does not persist after the first update.
|