v0.1.7

Access Control

Last updated


This page describes QemuRun-pve's three guards: origin-scoped CORS, the ALLOW_IPS whitelist, and per-VM state and lock checks.

Layer 1: CORS


Every request passes the CORS middleware:
OriginResponse
A private IP (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) in the server's own /24Access-Control-Allow-Origin echoes that origin
Any other originNo Access-Control-Allow-Origin
No Origin (curl, server-side callers)Access-Control-Allow-Origin is set to the subnet pattern (e.g. 192.168.0.*); non-browser callers ignore it

The server subnet comes from the first non-loopback private IPv4 interface, falling back to 192.168.0.*. Allowed methods are GET, POST, OPTIONS; OPTIONS preflights get 204 directly.
Once an SSE endpoint (install, start, reboot, set/node) passes its pre-checks and starts streaming, it overwrites Access-Control-Allow-Origin with the request's Origin as is and sets Access-Control-Allow-Headers: Cache-Control, so the subnet rule above does not apply to those streams.
CORS only constrains browsers; it is not authentication.

Layer 2: ALLOW_IPS


Every mutating endpoint (install, start, stop, shutdown, reboot, destroy, set/*) first matches the client IP:
ALLOW_IPSBehavior
0.0.0.0Allow all
192.168.0.10,192.168.0.20Allow only the listed IPs
unset or emptyDeny all

The client IP comes from Gin's c.ClientIP(). The service sets no trusted proxies, so Gin honors X-Forwarded-For / X-Real-IP by default, and a client talking to the API directly can spoof its IP; expose the service only inside a controlled network.
Rejections look like this:
Endpoint typeResponse
Sync endpoints403 this IP is not allowed to perform this action
SSE endpoints200 with a single data: {"message": "...this IP is not allowed to perform this action"} line

Query endpoints (health, list, status) do not check ALLOW_IPS.

Layer 3: VM State and the Disabled List


Mutating endpoints that target a VM check it against pvesh get /cluster/resources and 1:
CheckFailure response
VM is on the disabled list400 this IP is not allowed to be controlled
Requires running, VM is stopped400 VM is not running
Requires stopped, VM is running400 VM is running
Cluster data or disabled list unreadable500 failed to get VM list: ...

Requires a running VMRequires a stopped VM
stop, shutdown, rebootstart, destroy, set/cpu, set/memory, set/disk, set/node

SSE endpoints report check failures as a single data: line as well.
中文