v0.1.7

Lifecycle Endpoints

Last updated


This page covers the five endpoints that start, reboot, shut down, force-stop, and destroy a VM.

Overview


Endpointqm commandRequired VM stateResponse
POST /api/vm/:id/startqm startstoppedSSE, waits until SSH accepts logins
POST /api/vm/:id/rebootqm rebootrunningSSE, waits until SSH accepts logins
POST /api/vm/:id/shutdownqm shutdownrunningtext ok
POST /api/vm/:id/stopqm stoprunningtext ok
POST /api/vm/:id/destroyqm destroystoppedtext ok

All are subject to ALLOW_IPS and the disabled list, and run on the VM's node via Multi-Node Dispatch.

start / reboot


  1. curl -N -X POST http://192.168.0.11:8080/api/vm/120/start

  1. data: {"step":"starting VM","status":"success","message":"[+] VM starting (1.12s)"}
  2. data: {"step":"waiting for SSH","status":"success","message":"[+] VM is ready (24.37s)"}
  3. data: {"step":"finalizing","status":"info","message":"[+] VM started successfully"}
  4. event: close
  5. data: {}

StepBehavior
Run qm start / qm rebootOn failure, sends an error message and stops
waiting for SSHPicks the login user from the VM's OS tag (debian / ubuntu / rocky), tries every 5 seconds, up to 60 times
finalizingWaits 5 seconds, then sends an info event

A VM without an OS tag (not created by this service) fails waiting for SSH with OS user not found; the start command itself has already completed.

shutdown / stop


  1. curl -X POST http://192.168.0.11:8080/api/vm/120/shutdown
  2. # ok

shutdown sends an ACPI power-off and waits for qm shutdown to return; stop cuts power immediately.

destroy


  1. curl -X POST http://192.168.0.11:8080/api/vm/120/destroy
  2. # ok

Accepts only stopped VMs and runs qm destroy <vmid> (without --purge). The VMID and IP become available to automatic allocation again.

Error Responses


CaseSync endpointsSSE endpoints
Client IP not in ALLOW_IPS403single data: error
Wrong VM state or on the disabled list400single data: error
qm fails500 failed to ... VM: <output>data: error, then stop
中文