fix: isolate libvirt domain names

go
codex 1 month ago
parent 80b893a666
commit ef87b456b6

@ -219,6 +219,11 @@ func (s *Server) routeVMs(w http.ResponseWriter, r *http.Request, segments []str
if request.UUID == "" {
request.UUID = operationUUID(resolvedOperationID)
}
request.DomainName, err = hypervisor.LibvirtDomainName(actor.UserID, request.UUID)
if err != nil {
writePreDispatchMappedError(w, err)
return
}
if err := hypervisor.ValidateCreateVM(request); err != nil {
writePreDispatchMappedError(w, err)
return

@ -26,6 +26,7 @@ type fakeHypervisor struct {
hypervisor.Unsupported
mu sync.Mutex
creates int
lastCreate hypervisor.CreateVMRequest
reconciles int
lastReconcile operation.Record
reconcileTo operation.Resolution
@ -63,6 +64,7 @@ func (f *fakeHypervisor) Capabilities(context.Context) (hypervisor.Capabilities,
func (f *fakeHypervisor) CreateVM(_ context.Context, request hypervisor.CreateVMRequest) (hypervisor.VMMetadata, error) {
f.mu.Lock()
f.creates++
f.lastCreate = request
f.mu.Unlock()
return hypervisor.VMMetadata{
UUID: request.UUID, Name: request.Name, VCPUs: request.VCPUs,
@ -434,7 +436,7 @@ func assertRetryableNotDispatched(t *testing.T, response *httptest.ResponseRecor
func TestCreateVMOperationIsDurablyIdempotentAndConflictsOnPayloadChange(t *testing.T) {
api := newTestAPI(t)
actor := auth.Actor{UserID: 1, CanManage: true, OperationID: "operation-create-one"}
actor := auth.Actor{UserID: 3, CanManage: true, OperationID: "operation-create-one"}
body := validCreateBody(actor.OperationID, "vm-one")
first := api.request(t, http.MethodPost, "/v1/vms", body, actor)
if first.Code != http.StatusCreated {
@ -450,10 +452,14 @@ func TestCreateVMOperationIsDurablyIdempotentAndConflictsOnPayloadChange(t *test
}
api.hv.mu.Lock()
creates := api.hv.creates
lastCreate := api.hv.lastCreate
api.hv.mu.Unlock()
if creates != 1 {
t.Fatalf("backend create calls = %d, want 1", creates)
}
if lastCreate.DomainName != "3:vm-123e4567e89b" || lastCreate.Name != "vm-one" {
t.Fatalf("create names = internal %q display %q", lastCreate.DomainName, lastCreate.Name)
}
conflict := api.request(t, http.MethodPost, "/v1/vms", validCreateBody(actor.OperationID, "vm-different"), actor)
if conflict.Code != http.StatusConflict ||
@ -463,6 +469,18 @@ func TestCreateVMOperationIsDurablyIdempotentAndConflictsOnPayloadChange(t *test
}
}
func TestCreateVMRejectsClientSuppliedInternalDomainName(t *testing.T) {
api := newTestAPI(t)
body := validCreateBody("operation-create-injected-name", "vm-one")
body = bytes.Replace(body, []byte(`"source":"cloud"`), []byte(`"source":"cloud","domain_name":"9:vm-123e4567e89b"`), 1)
response := api.request(t, http.MethodPost, "/v1/vms", body, auth.Actor{
UserID: 3, CanManage: true, OperationID: "operation-create-injected-name",
})
if response.Code != http.StatusBadRequest || !strings.Contains(response.Body.String(), "invalid_json") {
t.Fatalf("injected domain name response = %d %s", response.Code, response.Body.String())
}
}
func TestFailedCreateRouteUsesReadOnlyReconciliationWithoutReplay(t *testing.T) {
api := newTestAPI(t)
operationID := "operation-create-api-failed"

@ -11,6 +11,7 @@ import (
"net/netip"
"path/filepath"
"regexp"
"strconv"
"strings"
"unicode/utf8"
@ -183,6 +184,7 @@ const domainMetadataNamespace = "https://virt.example/schema/domain/1"
type domainMetadataXML struct {
XMLName xml.Name `xml:"virt-cloud"`
XMLNS string `xml:"xmlns,attr"`
DisplayName string `xml:"display-name,omitempty"`
DiskGiB uint64 `xml:"disk-gib"`
BandwidthMbps uint64 `xml:"bandwidth-mbps"`
Hostname string `xml:"hostname,omitempty"`
@ -241,7 +243,7 @@ func marshalDomainMetadata(definition DomainDefinition) (string, error) {
return "", fmt.Errorf("marshal platform network policy metadata: %w", err)
}
encoded, err := xml.Marshal(domainMetadataXML{
XMLNS: domainMetadataNamespace, DiskGiB: definition.DiskGiB,
XMLNS: domainMetadataNamespace, DisplayName: definition.DisplayName, DiskGiB: definition.DiskGiB,
BandwidthMbps: definition.BandwidthMbps, Hostname: definition.Hostname,
PublicIPCIDR: definition.PublicIPCIDR, PublicPoolKey: definition.PublicPoolKey,
PublicPoolCIDR: definition.PublicPoolCIDR, Gateway: definition.Gateway,
@ -259,6 +261,9 @@ func ValidateCreateVM(request CreateVMRequest) error {
if request.UUID != "" && !uuidPattern.MatchString(request.UUID) {
return NewError(ErrInvalid, "invalid_uuid", "uuid must be a canonical RFC 4122 value", nil)
}
if err := validateLibvirtDomainName(request.DomainName, request.UUID); err != nil {
return err
}
if request.Source != "cloud" {
return NewError(ErrInvalid, "invalid_source", "source must be cloud", nil)
}
@ -394,8 +399,11 @@ func ValidateDomainDefinition(definition DomainDefinition) error {
if !uuidPattern.MatchString(definition.UUID) {
return NewError(ErrInvalid, "invalid_uuid", "uuid must be a canonical RFC 4122 value", nil)
}
if !namePattern.MatchString(definition.Name) {
return NewError(ErrInvalid, "invalid_name", "name must contain 1-80 safe characters", nil)
if err := validateLibvirtDomainName(definition.Name, definition.UUID); err != nil {
return err
}
if !namePattern.MatchString(definition.DisplayName) {
return NewError(ErrInvalid, "invalid_name", "display name must contain 1-80 safe characters", nil)
}
if definition.VCPUs == 0 || definition.VCPUs > 512 || definition.MemoryMiB < 128 || definition.MemoryMiB > 16*1024*1024 {
return NewError(ErrInvalid, "invalid_resources", "domain CPU or memory is invalid", nil)
@ -452,6 +460,32 @@ func ValidateDomainDefinition(definition DomainDefinition) error {
return nil
}
// LibvirtDomainName derives the host-local libvirt identity from authenticated
// ownership and the canonical VM UUID. It is never accepted from request JSON.
func LibvirtDomainName(userID int64, uuid string) (string, error) {
if userID <= 0 {
return "", NewError(ErrInvalid, "invalid_owner_id", "authenticated owner id must be positive", nil)
}
if !uuidPattern.MatchString(uuid) {
return "", NewError(ErrInvalid, "invalid_uuid", "uuid must be a canonical RFC 4122 value", nil)
}
compactUUID := strings.ReplaceAll(strings.ToLower(uuid), "-", "")
return strconv.FormatInt(userID, 10) + ":vm-" + compactUUID[:12], nil
}
func validateLibvirtDomainName(name, uuid string) error {
if !uuidPattern.MatchString(uuid) {
return NewError(ErrInvalid, "invalid_uuid", "uuid must be a canonical RFC 4122 value", nil)
}
owner, suffix, found := strings.Cut(name, ":")
ownerID, err := strconv.ParseInt(owner, 10, 64)
compactUUID := strings.ReplaceAll(strings.ToLower(uuid), "-", "")
if !found || err != nil || ownerID <= 0 || owner != strconv.FormatInt(ownerID, 10) || suffix != "vm-"+compactUUID[:12] {
return NewError(ErrInvalid, "invalid_domain_name", "libvirt domain name must match the authenticated owner and VM UUID", err)
}
return nil
}
func ValidatePlatformNetworkPolicy(policy PlatformNetworkPolicySnapshot) error {
if policy.SchemaVersion != 1 || policy.BasePolicyVersion == 0 || len(policy.Rules) == 0 || len(policy.Rules) > 70 || !digestPattern.MatchString(policy.Digest) {
return NewError(ErrInvalid, "invalid_platform_network_policy", "platform network policy snapshot is invalid", nil)
@ -601,6 +635,9 @@ func metadataFromXML(document string) (VMMetadata, error) {
if err := xml.Unmarshal([]byte(domain.Metadata.XML), &stored); err != nil {
return VMMetadata{}, fmt.Errorf("parse virt-cloud domain metadata: %w", err)
}
if stored.DisplayName != "" {
metadata.Name = stored.DisplayName
}
metadata.DiskGiB = stored.DiskGiB
metadata.BandwidthMbps = stored.BandwidthMbps
metadata.Hostname = stored.Hostname

@ -12,7 +12,7 @@ import (
func validDomainDefinition() DomainDefinition {
return DomainDefinition{
UUID: "123e4567-e89b-42d3-a456-426614174000", Name: "vm-test",
UUID: "123e4567-e89b-42d3-a456-426614174000", Name: "3:vm-123e4567e89b", DisplayName: "vm-test",
Description: "escaped <description> & safe", VCPUs: 2, MemoryMiB: 2048,
DiskGiB: 40, BandwidthMbps: 100, Hostname: "vm-test.example",
PublicIPCIDR: "8.8.8.10/24", PublicPoolKey: "0123456789abcdef0123456789abcdef",
@ -58,6 +58,9 @@ func TestBuildDomainXMLUsesQ35UEFIWithSecureBootDisabled(t *testing.T) {
if err := domain.Unmarshal(document); err != nil {
t.Fatal(err)
}
if domain.Name != "3:vm-123e4567e89b" {
t.Fatalf("libvirt domain name = %q, want authenticated internal name", domain.Name)
}
if domain.OS == nil || domain.OS.Type == nil || domain.OS.Type.Machine != "q35" {
t.Fatalf("machine is not q35: %#v", domain.OS)
}
@ -153,7 +156,7 @@ func TestMetadataRoundTrip(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if metadata.UUID != "123e4567-e89b-42d3-a456-426614174000" || metadata.Firmware != "uefi" || metadata.SecureBoot || metadata.MemoryMiB != 2048 ||
if metadata.UUID != "123e4567-e89b-42d3-a456-426614174000" || metadata.Name != "vm-test" || metadata.Firmware != "uefi" || metadata.SecureBoot || metadata.MemoryMiB != 2048 ||
metadata.DiskGiB != 40 || metadata.BandwidthMbps != 100 || metadata.Hostname != "vm-test.example" || metadata.TemplateID != "debian-12" ||
metadata.PublicIPCIDR != "8.8.8.10/24" || metadata.PublicPoolKey != "0123456789abcdef0123456789abcdef" ||
metadata.PublicPoolCIDR != "8.8.8.0/24" || metadata.Gateway != "8.8.8.1" || metadata.NetworkSelector != "public" ||
@ -162,6 +165,55 @@ func TestMetadataRoundTrip(t *testing.T) {
}
}
func TestMetadataFallsBackToLegacyDomainName(t *testing.T) {
document, err := BuildDomainXML(validDomainDefinition())
if err != nil {
t.Fatal(err)
}
document = strings.Replace(document, "<name>3:vm-123e4567e89b</name>", "<name>legacy-vm</name>", 1)
document = strings.Replace(document, "<display-name>vm-test</display-name>", "", 1)
metadata, err := metadataFromXML(document)
if err != nil {
t.Fatal(err)
}
if metadata.Name != "legacy-vm" {
t.Fatalf("legacy display name = %q, want legacy-vm", metadata.Name)
}
}
func TestLibvirtDomainNameUsesOwnerAndCompactUUIDPrefix(t *testing.T) {
const uuid = "83472897-3274-4abc-8def-0123456789ab"
name, err := LibvirtDomainName(3, uuid)
if err != nil {
t.Fatal(err)
}
if name != "3:vm-834728973274" {
t.Fatalf("domain name = %q, want 3:vm-834728973274", name)
}
upper, err := LibvirtDomainName(3, strings.ToUpper(uuid))
if err != nil || upper != name {
t.Fatalf("uppercase UUID name = %q err=%v, want %q", upper, err, name)
}
if _, err := LibvirtDomainName(0, uuid); err == nil {
t.Fatal("zero owner id was accepted")
}
if _, err := LibvirtDomainName(3, "not-a-uuid"); err == nil {
t.Fatal("invalid UUID was accepted")
}
other, err := LibvirtDomainName(3, "93472897-3274-4abc-8def-0123456789ab")
if err != nil || other == name {
t.Fatalf("different UUID domain name = %q err=%v, must differ from %q", other, err, name)
}
}
func TestValidateDomainDefinitionRejectsMismatchedInternalName(t *testing.T) {
definition := validDomainDefinition()
definition.Name = "3:vm-834728973274"
if err := ValidateDomainDefinition(definition); err == nil || !strings.Contains(err.Error(), "authenticated owner") {
t.Fatalf("mismatched domain name error = %v", err)
}
}
func TestValidateCreateVMUsesPanelIntentWithoutHostPaths(t *testing.T) {
request := validIntentCreateRequest(t)
if err := ValidateCreateVM(request); err != nil {
@ -191,6 +243,7 @@ func validIntentCreateRequest(t *testing.T) CreateVMRequest {
}
digest := sha256.Sum256(encoded)
return CreateVMRequest{
UUID: "123e4567-e89b-42d3-a456-426614174000", DomainName: "3:vm-123e4567e89b",
Source: "cloud", Name: "vm-test", VCPUs: 2, MemoryMiB: 2048, DiskGiB: 40,
BandwidthMbps: 100, NetworkSelector: "public", TemplateID: "debian-12",
TemplateRevision: 1, TemplateGenerationToken: "0123456789abcdef0123456789abcdef",

@ -351,7 +351,7 @@ func (l *Libvirt) CreateVM(ctx context.Context, request CreateVMRequest) (_ VMMe
}()
document, err := BuildDomainXML(DomainDefinition{
UUID: request.UUID, Name: request.Name, Description: request.Description,
UUID: request.UUID, Name: request.DomainName, DisplayName: request.Name, Description: request.Description,
VCPUs: request.VCPUs, MemoryMiB: request.MemoryMiB, DiskGiB: request.DiskGiB,
BandwidthMbps: request.BandwidthMbps, Hostname: request.Hostname,
PublicIPCIDR: request.PublicIPCIDR, PublicPoolKey: request.PublicPoolKey,
@ -672,7 +672,7 @@ func (l *Libvirt) verifyCreatedDomain(domain *libvirt.Domain, request CreateVMRe
if err != nil {
return err
}
if !strings.EqualFold(definition.UUID, request.UUID) || metadata.PublicPoolKey != request.PublicPoolKey || metadata.PublicIPCIDR != request.PublicIPCIDR || definition.Devices == nil || len(definition.Devices.Interfaces) != 1 {
if !strings.EqualFold(definition.UUID, request.UUID) || definition.Name != request.DomainName || metadata.DisplayName != request.Name || metadata.PublicPoolKey != request.PublicPoolKey || metadata.PublicIPCIDR != request.PublicIPCIDR || definition.Devices == nil || len(definition.Devices.Interfaces) != 1 {
return NewError(ErrConflict, "create_observation_mismatch", "new domain identity or network metadata did not match the requested intent", nil)
}
var storedPolicy PlatformNetworkPolicySnapshot

@ -1208,6 +1208,9 @@ func inspectManagedDomain(document string) (*libvirtxml.Domain, *domainMetadataX
if !uuidPattern.MatchString(definition.UUID) || !templateIDPattern.MatchString(metadata.TemplateID) || !isVMOwnedRootVolumeName(definition.UUID, metadata.RootVolumeName) {
return nil, nil, true, NewError(ErrConflict, "managed_metadata_invalid", "Virt Cloud domain ownership metadata is incomplete", nil)
}
if metadata.DisplayName != "" && !namePattern.MatchString(metadata.DisplayName) {
return nil, nil, true, NewError(ErrConflict, "managed_metadata_invalid", "Virt Cloud display name metadata is invalid", nil)
}
var platformPolicy PlatformNetworkPolicySnapshot
if err := json.Unmarshal([]byte(metadata.PlatformPolicyJSON), &platformPolicy); err != nil || ValidatePlatformNetworkPolicy(platformPolicy) != nil {
return nil, nil, true, NewError(ErrConflict, "managed_metadata_invalid", "Virt Cloud platform policy metadata is invalid", err)

@ -251,9 +251,8 @@ func (l *Libvirt) Reinstall(ctx context.Context, uuid string, request ReinstallR
}
func metadataName(document string) string {
var definition libvirtxml.Domain
if definition.Unmarshal(document) == nil {
return definition.Name
if metadata, err := metadataFromXML(document); err == nil && metadata.Name != "" {
return metadata.Name
}
return "vm"
}

@ -1251,3 +1251,19 @@ func TestDomainCapabilitiesRequireConfiguredQ35UEFISecureBootOffCombination(t *t
t.Fatal("missing live backup capability was accepted")
}
}
func TestReinstallMetadataNameKeepsDisplayNameForInternalDomain(t *testing.T) {
document, err := BuildDomainXML(validDomainDefinition())
if err != nil {
t.Fatal(err)
}
if got := metadataName(document); got != "vm-test" {
t.Fatalf("reinstall cloud-init name = %q, want vm-test", got)
}
legacy := strings.Replace(document, "<name>3:vm-123e4567e89b</name>", "<name>legacy-vm</name>", 1)
legacy = strings.Replace(legacy, "<display-name>vm-test</display-name>", "", 1)
if got := metadataName(legacy); got != "legacy-vm" {
t.Fatalf("legacy reinstall cloud-init name = %q, want legacy-vm", got)
}
}

@ -167,10 +167,13 @@ type NetworkAttachment struct {
}
type CreateVMRequest struct {
OperationID string `json:"operation_id,omitempty"`
UUID string `json:"uuid,omitempty"`
Source string `json:"source"`
Name string `json:"name"`
OperationID string `json:"operation_id,omitempty"`
UUID string `json:"uuid,omitempty"`
Source string `json:"source"`
Name string `json:"name"`
// DomainName is derived from the authenticated actor and UUID by the API.
// It is process-internal and must never be accepted from request JSON.
DomainName string `json:"-"`
Description string `json:"description,omitempty"`
VCPUs uint `json:"vcpu"`
MemoryMiB uint64 `json:"memory_mib"`
@ -197,6 +200,7 @@ type CreateVMRequest struct {
type DomainDefinition struct {
UUID string
Name string
DisplayName string
Description string
VCPUs uint
MemoryMiB uint64

@ -140,6 +140,12 @@ RAW_X_VIRT_ACTOR
| GET/POST | `/v1/user-isos?owner_id=...` | 列出/导入用户 ISO |
| DELETE | `/v1/user-isos/{id}?owner_id=...` | 删除指定用户 ISO |
### VM 名称边界
`POST /v1/vms` 请求中的 `name` 仍是面板显示名称,也是首次生成 Guest 配置时使用的名称输入;它不再直接写入 libvirt 域的 `<name>`。Agent 在得到最终 VM UUID 后,只能使用已验签 `X-Virt-Actor` 中的 `user_id` 与该 UUID 派生宿主机内部名称:`<user_id>:vm-<UUID 去掉连字符并转为小写后的前 12 位>`,例如用户 `3` 与 UUID `83472897-3274-...` 得到 `3:vm-834728973274`。内部名称字段不是请求正文契约,客户端提交 `domain_name` 或其他自定义 libvirt 名称必须按未知字段拒绝;后续查询、变更和对账仍以完整 UUID 定位,不能依赖名称。
Agent 把原始 `name` 保存为 Virt Cloud 的 `display-name` 域 metadata,并在 VM 元数据响应中优先返回它。既有 VM 若没有 `display-name` metadata,则只在读取时回退到原有 libvirt domain name,不能因此自动重命名、重定义或迁移旧域。该内部命名规则仅用于规则启用后新建的 VM。
创建快照请求的 `consistency_mode=filesystem` 表示“优先文件系统一致”:Agent 会先用只读 `guest-ping` 检查 QEMU Guest Agent;当 libvirt 明确报告 Guest Agent 未配置、不支持、未响应或探测超时时,自动改用 `crash`。显式请求 `crash` 时不探测也不冻结 Guest。若 QGA 探测成功但后续冻结、解冻或 libvirt 通信失败,不得伪装成安全降级;结果不明确时仍必须保留 `uncertain`。成功响应的 `consistency` 以及宿主机和面板快照元数据必须记录实际采用的模式,协调时只允许 `filesystem` 请求单向降级为 `crash`,绝不允许反向提升。
本表只描述已注册的 HTTP 路由;对应 libvirt 实现未落地或本机依赖不支持时,`features.*` 必须为 false 并返回 501,不得假成功。公网池的销售库存仍只在 PHP;Agent 仅在 VM 创建/换网时验证签名的 pool key、CIDR、IP、gateway、DNS 和本机 network selector。

@ -74,7 +74,7 @@ Unix 时间戳
## 虚拟机、镜像与启动脚本
- 域 XML 使用结构化类型生成并验证输入,所有变更按 UUID 定位。部署每台宿主机时先查询 domain capabilities,把该机支持且不启用 Secure Boot 的 Q35/EFI loader 与 NVRAM template 写入本机 Agent 配置;创建请求不能传入任意固件路径。Agent 使用手工 loader/NVRAM XML 并保持 `secure="no"`、`SMM=off`,不混入只适用于固件自动选择的 feature 列表,也不在 PHP 中硬编码单一发行版 OVMF 路径。
- 域 XML 使用结构化类型生成并验证输入,所有变更按 UUID 定位。创建请求的 `name` 保留为面板/Guest 显示输入并写入 `display-name` metadata;libvirt 内部名称只能由已验签 actor 的 `user_id` 与最终 UUID 派生为 `<user_id>:vm-<前 12 位小写无连字符 UUID>`,不接受请求正文覆盖。读取没有 `display-name` metadata 的既有 VM 时回退其旧 domain name,但不自动重命名旧域。部署每台宿主机时先查询 domain capabilities,把该机支持且不启用 Secure Boot 的 Q35/EFI loader 与 NVRAM template 写入本机 Agent 配置;创建请求不能传入任意固件路径。Agent 使用手工 loader/NVRAM XML 并保持 `secure="no"`、`SMM=off`,不混入只适用于固件自动选择的 feature 列表,也不在 PHP 中硬编码单一发行版 OVMF 路径。
- Agent 配置使用 `revision`/`tested_revision` 就绪门闩。保存密钥、启用状态或宿主机 `default_network` 会推进 revision 并将 `tested_revision` 清零;只有同一 revision 经已认证出站会话完成 `/v1/health` 与 `/v1/capabilities`,且 `default_network` 精确存在于 Agent 上报的可用 `network_selectors`,才记录为就绪。调度、Agent 客户端以及控制台路径均要求 `enabled=1`、`last_test_status=healthy` 且 `tested_revision=revision`。
- 云镜像由 PHP 保存目录元数据和启动脚本。创建任务快照镜像 generation、revision 和脚本正文后签名发送给目标 Agent;删除后重新导入的同名镜像不能继承旧脚本。
- 启动脚本仅用于新云镜像实例的首次安装,不用于普通重启、网络设置、重装、救援或用户 ISO。脚本限制 32 KiB UTF-8,拒绝 NUL,CRLF 规范化为 LF,空值表示禁用。

@ -457,7 +457,7 @@ namespace {
$history = [];
$createdVm = [
'uuid' => '11111111-1111-4111-8111-111111111111',
'name' => 'vm-one',
'name' => '1:vm-111111111111',
'vcpu' => 2,
'memory_mib' => 2048,
'disk_gib' => 20,
@ -570,7 +570,8 @@ namespace {
$instance = CloudInstance::first();
$instanceSpec = json_decode((string) $instance->spec_json, true,
flags: JSON_THROW_ON_ERROR);
$assert(($instanceSpec['public_ip_cidr'] ?? null) === '203.0.113.18/28'
$assert($instance->name === 'vm-one'
&& ($instanceSpec['public_ip_cidr'] ?? null) === '203.0.113.18/28'
&& ($instanceSpec['os_source'] ?? null) === 'cloud_template'
&& ($instanceSpec['os_name'] ?? null) === 'AlmaLinux 10'
&& ($instanceSpec['login_name'] ?? null) === 'root'

Loading…
Cancel
Save