# Powerman PDU Management

Centralized power management for the Cyclades AlterPath PM10i PDU via
[Powerman](https://github.com/chaos/powerman), running on pfv-tsys1.

## Hardware

| Component | Details |
|-----------|---------|
| **PDU** | Cyclades AlterPath PM10i (10 controllable AC outlets) |
| **Firmware** | v1.9.0 (Aug 4, 2006) |
| **Connection** | USB-to-DB9 adapter (Prolific pl2303, serial BJAAb144J07) |
| **Host** | pfv-tsys1 (OptiPlex 9020, Proxmox) |
| **Serial** | 9600 baud, 8N1, raw mode |
| **Credentials** | Factory defaults: `admin` / `pm8` (in cyclades-pm10.dev) |
| **Network access** | powermand listens on `127.0.0.1:10101` (local) + `100.121.189.98:10101` (Tailscale) |

## Device mapping

```
USB adapter (067b:23a3, serial BJAAb144J07)
  └─ pl2303 driver → /dev/ttyUSB1
       └─ udev symlink → /dev/cyclades-pm10 (stable across reboots)
            └─ powermand reads/writes serial → Cyclades PM10i
                 └─ 10 outlets (factory default names: 1-10)
```

The udev rule (`/etc/udev/rules.d/99-cyclades-pdu.rules`) pins the adapter
by its USB serial number, so the symlink survives replugs and reboots.

## Scripts

All scripts run on the target host (pfv-tsys1) via `tests/remote.sh`:

```bash
# Setup (idempotent — safe to re-run):
PROX_HOST=pfv-tsys1 bash tests/remote.sh prox-file powerman/setup.sh

# Validate PDU control (cycles outlet 10 off → on):
PROX_HOST=pfv-tsys1 bash tests/remote.sh prox-file powerman/test-pdu.sh

# Status check:
PROX_HOST=pfv-tsys1 bash tests/remote.sh prox-file powerman/status.sh
```

### Customizing for other hosts/PDUs

The setup script accepts environment overrides:

```bash
PDU_SERIAL=XXXX PDU_VENDOR=067b PDU_OUTLETS=20 PDU_TYPE=pm20 \
  PROX_HOST=other-host bash tests/remote.sh prox-file powerman/setup.sh
```

## Usage (daily operations)

From pfv-tsys1 (or any host with network access to port 10101):

```bash
# List all outlets
powerman -l

# Query status (all outlets)
powerman -q

# Turn outlet off
powerman -0 outlet-10

# Turn outlet on
powerman -1 outlet-10

# Cycle outlet (off → 4s delay → on)
powerman -c outlet-10

# Query a specific outlet
powerman -q outlet-10
```

### Remote access from other hosts

powermand listens on `0.0.0.0:10101`. From another tailnet host:

```bash
powerman --server-host pfv-tsys1 --server-port 10101 -q
```

Or set `POWERMAN_SERVER=pfv-tsys1:10101` in the environment.

## Configuration files on pfv-tsys1

| File | Purpose |
|------|---------|
| `/etc/udev/rules.d/99-cyclades-pdu.rules` | Stable symlink for USB-DB9 adapter |
| `/etc/powerman/powerman.conf` | Device definition + 10 outlet nodes |
| `/etc/powerman/cyclades-pm10.dev` | Cyclades PM10 protocol spec (shipped with powerman) |

## Validation results

2026-07-28: All 8 checks passed.
Outlet 10 turned OFF (confirmed), turned ON (confirmed), then cycled.

## TODO (Friday onsite)

- [ ] **Rename outlets** in `/etc/powerman/powerman.conf` to match the
      physical devices plugged into each outlet (e.g., `node "tsys4-psu"
      "cyclades-pm10" "3"`). Currently all outlets are generically named
      `outlet-1` through `outlet-10`.
- [ ] **Change PDU admin password** from factory default (`pm8`) if
      security-sensitive. Update `/etc/powerman/cyclades-pm10.dev` login
      script to match.
- [ ] **Verify all 10 outlets** individually once device mapping is known.