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:
Origin | Response |
|---|---|
A private IP (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) in the server's own /24 | Access-Control-Allow-Origin echoes that origin |
| Any other origin | No 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_IPS | Behavior |
|---|---|
0.0.0.0 | Allow all |
192.168.0.10,192.168.0.20 | Allow only the listed IPs |
| unset or empty | Deny 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 type | Response |
|---|---|
| Sync endpoints | 403 this IP is not allowed to perform this action |
| SSE endpoints | 200 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