ProxMaid

Go backend for managing NonRAID arrays via REST API and WebSocket. Part of the ProxMaid project combining NonRAID storage with Proxmox VE.

Clone

git clone --recursive ssh://git@jelly.hedgehog-bortle.ts.net:2222/chuck/proxmaid.git

Build

make build

Run

./bin/nmdapid
# or
make run

Configuration

ProxMaid supports two configuration methods:

YAML Config File (Recommended)

Create /etc/proxmaid/config.yaml:

addr: ":8080"
superblock: "/nonraid.dat"
keyfile: "/etc/nonraid/luks-keyfile"
nmdctl: "/usr/local/bin/nmdctl"
poll_seconds: 2

Environment Variables

Variable	Default	Description
NMDAPI_ADDR	:8080	Listen address
NMDAPI_SUPERBLOCK	/nonraid.dat	Superblock file path
NMDAPI_KEYFILE	/etc/nonraid/luks-keyfile	LUKS keyfile path
NMDAPI_NMDCTL	/usr/local/bin/nmdctl	Path to nmdctl binary
NMDAPI_POLL_SECONDS	2	WebSocket status poll interval

API Endpoints

Array Operations

Method	Endpoint	Description
GET	/api/v1/array	Get array status
POST	/api/v1/array/start	Start array
POST	/api/v1/array/stop	Stop array
POST	/api/v1/array/check	Start parity check
POST	/api/v1/array/mount	Mount all disks
POST	/api/v1/array/unmount	Unmount all disks
POST	/api/v1/array/reload	Reload array
POST	/api/v1/array/create	Create new array
DELETE	/api/v1/array	Delete array

Disk Operations

Method	Endpoint	Description
GET	/api/v1/disks	List all disks
POST	/api/v1/disks	Add disk
PUT	/api/v1/disks/{slot}	Replace disk
DELETE	/api/v1/disks/{slot}	Unassign disk
GET	/api/v1/disks/{slot}/smart	Get SMART data for disk

System

Method	Endpoint	Description
GET	/api/v1/system/disks	List physical disks
GET	/api/v1/config	Get masked configuration

Real-time

Method	Endpoint	Description
GET	/ws	WebSocket for real-time status
GET	/health	Health check

WebSocket Events

Connect to /ws for real-time updates. Events are sent as JSON messages.

Event Types

Event	Description
status	Array status updates (polled)
parity_progress	Parity check progress updates

Example: Parity Progress

{
  "type": "parity_progress",
  "data": {
    "percent": 42.5,
    "speed": "150 MB/s",
    "elapsed": "2h 15m",
    "remaining": "3h 10m"
  }
}

Install as Service

ProxMaid uses systemd's Type=notify for proper service readiness notification.

sudo make install
sudo systemctl daemon-reload
sudo systemctl enable --now nmdapi

The service will notify systemd when it's ready to accept connections, ensuring proper startup ordering for dependent services.