//go:build libvirt package hypervisor import ( "bytes" "context" "crypto/sha256" "encoding/binary" "encoding/hex" "encoding/json" "encoding/xml" "errors" "fmt" "io" "net/http" "strconv" "strings" "time" "git.luoli.live/root/virt/agent/operation" "libvirt.org/go/libvirt" ) const catalogMetadataLimit = 64 << 10 type catalogDeleteEvidence struct { label string notFoundCode string inconsistentCode string } func validateCatalogDeletePresence(imageExists, metadataExists bool, evidence catalogDeleteEvidence) error { if !imageExists && !metadataExists { return NewError(ErrNotFound, evidence.notFoundCode, evidence.label+" was not found", nil) } if imageExists != metadataExists { return NewError(ErrConflict, evidence.inconsistentCode, evidence.label+" image and managed metadata are inconsistent", nil) } return nil } func catalogDeleteEvidenceChanged(err error, evidence catalogDeleteEvidence) error { if err == nil || !errors.Is(err, ErrNotFound) { return err } // Do not retain ErrNotFound in the unwrap chain: the HTTP layer checks that // kind before ErrConflict, and PHP deliberately treats only a proven // double-absence tombstone as a successful delete. return NewError(ErrConflict, evidence.inconsistentCode, evidence.label+" managed artifacts changed during deletion", nil) } func (l *Libvirt) ListTemplates(ctx context.Context) ([]ImageTemplate, error) { if err := ctx.Err(); err != nil { return nil, err } pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleTemplate)) if err != nil { return nil, translateLibvirtError("lookup template catalog pool", err) } defer pool.Free() names, err := pool.ListStorageVolumes() if err != nil { return nil, translateLibvirtError("list template catalog", err) } result := make([]ImageTemplate, 0) for _, name := range names { if !strings.HasPrefix(name, "virt-template-") || !strings.HasSuffix(name, ".json") { continue } volume, lookupErr := pool.LookupStorageVolByName(name) if lookupErr != nil { return nil, translateLibvirtError("lookup template catalog entry", lookupErr) } contents, readErr := l.downloadSmallVolume(ctx, volume, catalogMetadataLimit) volume.Free() if readErr != nil { return nil, readErr } var item ImageTemplate if err := json.Unmarshal(contents, &item); err != nil || !templateIDPattern.MatchString(item.ID) || item.SizeBytes < uint64(minImportBytes) || item.VirtualSizeBytes == 0 { return nil, NewError(ErrConflict, "template_catalog_invalid", "template catalog metadata is invalid", err) } image, lookupErr := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleTemplate), templateVolumeName(item.ID)) if lookupErr != nil { return nil, lookupErr } if image == nil { return nil, NewError(ErrConflict, "template_volume_missing", "template catalog references a missing image volume", nil) } info, infoErr := image.GetInfo() image.Free() if infoErr != nil { return nil, translateLibvirtError("read template volume info", infoErr) } if info.Capacity != item.VirtualSizeBytes { return nil, NewError(ErrConflict, "template_capacity_changed", "template volume capacity does not match catalog metadata", nil) } result = append(result, item) } sortTemplates(result) return result, nil } func (l *Libvirt) ImportTemplate(ctx context.Context, request ImportTemplateRequest) (_ ImageTemplate, resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if err := ValidateTemplateSnapshot(request.ID, request.Revision, request.GenerationToken); err != nil { return ImageTemplate{}, err } if !displayNamePattern.MatchString(request.Name) || !displayNamePattern.MatchString(request.OSFamily) || !displayNamePattern.MatchString(request.Version) || !namePattern.MatchString(request.Architecture) || (request.SHA256 != "" && !sha256Pattern.MatchString(request.SHA256)) || !validSourceToken(request.SourceToken) { return ImageTemplate{}, NewError(ErrInvalid, "invalid_template", "template metadata is invalid", nil) } if err := validateExpectedImportSourceSize(request.SourceSizeBytes, maxTemplateBytes); err != nil { return ImageTemplate{}, err } if _, err := validateRemoteSource(request.SourceURL); err != nil { return ImageTemplate{}, err } existing, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleTemplate), templateVolumeName(request.ID)) if err != nil { return ImageTemplate{}, err } if existing != nil { existing.Free() return ImageTemplate{}, NewError(ErrConflict, "template_exists", "template already exists on this host", nil) } pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleTemplate)) if err != nil { return ImageTemplate{}, translateLibvirtError("lookup template storage pool", err) } defer pool.Free() mutationStarted = true volume, size, digest, err := l.downloadVolume(ctx, pool, templateVolumeName(request.ID), "qcow2", request.SourceURL, request.SourceToken, request.SourceSizeBytes, maxTemplateBytes, request.SHA256) if err != nil { return ImageTemplate{}, err } defer volume.Free() info, err := volume.GetInfo() if err != nil { return ImageTemplate{}, l.rollbackImportedVolume(volume, translateLibvirtError("read imported template volume info", err), "template image") } item := ImageTemplate{ID: request.ID, Name: request.Name, OSFamily: request.OSFamily, Version: request.Version, Architecture: request.Architecture, SizeBytes: uint64(size), VirtualSizeBytes: info.Capacity, SHA256: digest, Revision: request.Revision, GenerationToken: request.GenerationToken, CreatedAt: time.Now().UTC()} if err := l.writeCatalogEntry(ctx, l.storagePoolName(StorageRoleTemplate), templateMetadataVolumeName(request.ID), item, false); err != nil { cleanupErr := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL) if cleanupErr != nil { return ImageTemplate{}, operation.MarkUncertain(errors.Join(err, mutationLibvirtError("roll back template image", cleanupErr))) } return ImageTemplate{}, err } return item, nil } func (l *Libvirt) UpdateTemplate(ctx context.Context, id string, request UpdateTemplateRequest) (_ ImageTemplate, resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if err := ctx.Err(); err != nil { return ImageTemplate{}, err } if !templateIDPattern.MatchString(id) || !displayNamePattern.MatchString(request.Name) || (request.GenerationToken != "" && !generationTokenPattern.MatchString(request.GenerationToken)) { return ImageTemplate{}, NewError(ErrInvalid, "invalid_template", "template id or name is invalid", nil) } if (request.Revision == 0) != (request.GenerationToken == "") { return ImageTemplate{}, NewError(ErrInvalid, "invalid_template_snapshot", "revision and generation_token must be provided together", nil) } item, err := l.loadImageTemplate(ctx, id) if err != nil { return ImageTemplate{}, err } if request.GenerationToken != "" && item.GenerationToken != request.GenerationToken { return ImageTemplate{}, NewError(ErrConflict, "template_generation_changed", "template generation token no longer matches", nil) } if request.Revision != 0 && (request.Revision < item.Revision || (request.Revision == item.Revision && request.Name != item.Name)) { return ImageTemplate{}, NewError(ErrConflict, "template_revision_changed", "template revision no longer matches", nil) } if request.Revision != 0 && request.Revision == item.Revision { return item, nil } item.Name = request.Name if request.Revision != 0 { item.Revision = request.Revision } mutationStarted = true if err := l.writeCatalogEntry(ctx, l.storagePoolName(StorageRoleTemplate), templateMetadataVolumeName(id), item, true); err != nil { return ImageTemplate{}, operation.MarkUncertain(err) } return item, nil } func (l *Libvirt) DeleteTemplate(ctx context.Context, id string) (resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if err := ctx.Err(); err != nil { return err } if !templateIDPattern.MatchString(id) { return NewError(ErrInvalid, "invalid_template_id", "template id is invalid", nil) } imageExists, metadataExists, err := l.catalogArtifactPresence(l.storagePoolName(StorageRoleTemplate), templateVolumeName(id), templateMetadataVolumeName(id)) if err != nil { return err } evidence := catalogDeleteEvidence{ label: "template", notFoundCode: "template_not_found", inconsistentCode: "template_artifacts_inconsistent", } if err := validateCatalogDeletePresence(imageExists, metadataExists, evidence); err != nil { return err } if _, err := l.loadImageTemplate(ctx, id); err != nil { return catalogDeleteEvidenceChanged(err, evidence) } pool, volume, err := l.templateVolume(id) if err != nil { return catalogDeleteEvidenceChanged(err, evidence) } defer pool.Free() defer volume.Free() used, err := l.volumeReferenced(volume) if err != nil { return err } if used { return NewError(ErrConflict, "template_in_use", "template volume is referenced by a VM", nil) } mutationStarted = true if err := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL); err != nil { return operation.MarkUncertain(mutationLibvirtError("delete template volume", err)) } if err := l.deleteCatalogEntry(l.storagePoolName(StorageRoleTemplate), templateMetadataVolumeName(id)); err != nil { return operation.MarkUncertain(err) } return l.confirmCatalogArtifactsAbsent(l.storagePoolName(StorageRoleTemplate), templateVolumeName(id), templateMetadataVolumeName(id), "template") } func (l *Libvirt) ListRescueTemplates(ctx context.Context) ([]RescueTemplate, error) { if err := ctx.Err(); err != nil { return nil, err } pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleRescue)) if err != nil { return nil, translateLibvirtError("lookup rescue template catalog pool", err) } defer pool.Free() names, err := pool.ListStorageVolumes() if err != nil { return nil, translateLibvirtError("list rescue template catalog", err) } result := make([]RescueTemplate, 0) for _, name := range names { if !strings.HasPrefix(name, "virt-rescue-") || !strings.HasSuffix(name, ".json") { continue } volume, lookupErr := pool.LookupStorageVolByName(name) if lookupErr != nil { return nil, translateLibvirtError("lookup rescue template catalog entry", lookupErr) } contents, readErr := l.downloadSmallVolume(ctx, volume, catalogMetadataLimit) volume.Free() if readErr != nil { return nil, readErr } var item RescueTemplate if err := json.Unmarshal(contents, &item); err != nil || validateRescueTemplateIdentity(item) != nil { return nil, NewError(ErrConflict, "rescue_catalog_invalid", "rescue template catalog metadata is invalid", err) } image, lookupErr := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleRescue), rescueImageVolumeName(item.ID)) if lookupErr != nil { return nil, lookupErr } if image == nil { return nil, NewError(ErrConflict, "rescue_volume_missing", "rescue template catalog references a missing ISO volume", nil) } info, infoErr := image.GetInfo() image.Free() if infoErr != nil { return nil, translateLibvirtError("read rescue template volume info", infoErr) } if info.Capacity != item.SizeBytes { return nil, NewError(ErrConflict, "rescue_capacity_changed", "rescue template volume capacity does not match catalog metadata", nil) } result = append(result, item) } sortRescueTemplates(result) return result, nil } func (l *Libvirt) ImportRescueTemplate(ctx context.Context, request ImportRescueTemplateRequest) (_ RescueTemplate, resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if err := validateImportRescueTemplateRequest(request); err != nil { return RescueTemplate{}, err } if !validSourceToken(request.SourceToken) { return RescueTemplate{}, NewError(ErrInvalid, "invalid_rescue_template", "rescue template metadata is invalid", nil) } if request.SHA256 != "" && !sha256Pattern.MatchString(request.SHA256) { return RescueTemplate{}, NewError(ErrInvalid, "invalid_sha256", "sha256 must contain 64 lowercase hexadecimal characters", nil) } if err := validateExpectedImportSourceSize(request.SourceSizeBytes, maxRescueISOBytes); err != nil { return RescueTemplate{}, err } if _, err := validateRemoteSource(request.SourceURL); err != nil { return RescueTemplate{}, err } id := request.ID existing, err := l.ListRescueTemplates(ctx) if err != nil { return RescueTemplate{}, err } for _, item := range existing { if item.ID == id { return RescueTemplate{}, NewError(ErrConflict, "rescue_template_exists", "rescue template already exists on this host", nil) } if strings.EqualFold(item.Name, request.Name) { return RescueTemplate{}, NewError(ErrConflict, "rescue_template_name_exists", "a rescue template with this name already exists on this host", nil) } } existingImage, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleRescue), rescueImageVolumeName(id)) if err != nil { return RescueTemplate{}, err } if existingImage != nil { existingImage.Free() return RescueTemplate{}, NewError(ErrConflict, "rescue_template_exists", "rescue template already exists on this host", nil) } pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleRescue)) if err != nil { return RescueTemplate{}, translateLibvirtError("lookup rescue template storage pool", err) } defer pool.Free() mutationStarted = true volume, size, digest, err := l.downloadVolume(ctx, pool, rescueImageVolumeName(id), "raw", request.SourceURL, request.SourceToken, request.SourceSizeBytes, maxRescueISOBytes, request.SHA256) if err != nil { return RescueTemplate{}, err } defer volume.Free() if err := l.verifyBootableISO(ctx, volume, size); err != nil { return RescueTemplate{}, l.rollbackImportedVolume(volume, err, "rescue template") } item := RescueTemplate{ ID: id, Name: request.Name, SizeBytes: uint64(size), SHA256: digest, Revision: request.Revision, GenerationToken: request.GenerationToken, CreatedAt: time.Now().UTC(), } if err := l.writeCatalogEntry(ctx, l.storagePoolName(StorageRoleRescue), rescueMetadataVolumeName(id), item, false); err != nil { cleanupErr := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL) if cleanupErr != nil { return RescueTemplate{}, operation.MarkUncertain(errors.Join(err, mutationLibvirtError("roll back rescue template ISO", cleanupErr))) } return RescueTemplate{}, err } return item, nil } func (l *Libvirt) DeleteRescueTemplate(ctx context.Context, id string) (resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if err := ctx.Err(); err != nil { return err } if !catalogIDPattern.MatchString(id) { return NewError(ErrInvalid, "invalid_rescue_template_id", "rescue template id is invalid", nil) } imageExists, metadataExists, err := l.catalogArtifactPresence(l.storagePoolName(StorageRoleRescue), rescueImageVolumeName(id), rescueMetadataVolumeName(id)) if err != nil { return err } evidence := catalogDeleteEvidence{ label: "rescue template", notFoundCode: "rescue_template_not_found", inconsistentCode: "rescue_template_artifacts_inconsistent", } if err := validateCatalogDeletePresence(imageExists, metadataExists, evidence); err != nil { return err } if _, err := l.loadRescueTemplate(ctx, id); err != nil { return catalogDeleteEvidenceChanged(err, evidence) } volume, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleRescue), rescueImageVolumeName(id)) if err != nil { return err } if volume == nil { return NewError(ErrConflict, evidence.inconsistentCode, "rescue template image disappeared during deletion", nil) } defer volume.Free() used, err := l.volumeReferenced(volume) if err != nil { return err } if used { return NewError(ErrConflict, "rescue_template_in_use", "rescue template is attached to a VM", nil) } mutationStarted = true if err := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL); err != nil { return operation.MarkUncertain(mutationLibvirtError("delete rescue template volume", err)) } if err := l.deleteCatalogEntry(l.storagePoolName(StorageRoleRescue), rescueMetadataVolumeName(id)); err != nil { return operation.MarkUncertain(err) } return l.confirmCatalogArtifactsAbsent(l.storagePoolName(StorageRoleRescue), rescueImageVolumeName(id), rescueMetadataVolumeName(id), "rescue template") } func (l *Libvirt) ListUserISOs(ctx context.Context, ownerID int64) ([]UserISO, error) { if err := ctx.Err(); err != nil { return nil, err } if ownerID <= 0 { return nil, NewError(ErrInvalid, "invalid_owner_id", "owner_id must be positive", nil) } pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleUserISO)) if err != nil { return nil, translateLibvirtError("lookup user ISO pool", err) } defer pool.Free() prefix := "virt-useriso-" + strconv.FormatInt(ownerID, 10) + "-" names, err := pool.ListStorageVolumes() if err != nil { return nil, translateLibvirtError("list user ISO catalog", err) } result := make([]UserISO, 0) for _, name := range names { if !strings.HasPrefix(name, prefix) || !strings.HasSuffix(name, ".json") { continue } volume, lookupErr := pool.LookupStorageVolByName(name) if lookupErr != nil { return nil, translateLibvirtError("lookup user ISO catalog entry", lookupErr) } contents, readErr := l.downloadSmallVolume(ctx, volume, catalogMetadataLimit) volume.Free() if readErr != nil { return nil, readErr } var item UserISO if err := json.Unmarshal(contents, &item); err != nil || item.OwnerID != ownerID || !catalogIDPattern.MatchString(item.ID) || !sha256Pattern.MatchString(item.SHA256) { return nil, NewError(ErrConflict, "user_iso_catalog_invalid", "user ISO catalog metadata is invalid", err) } image, lookupErr := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleUserISO), userISOImageVolumeName(ownerID, item.ID)) if lookupErr != nil { return nil, lookupErr } if image == nil { return nil, NewError(ErrConflict, "user_iso_volume_missing", "user ISO catalog references a missing volume", nil) } info, infoErr := image.GetInfo() image.Free() if infoErr != nil { return nil, translateLibvirtError("read user ISO volume info", infoErr) } item.SizeBytes = info.Capacity result = append(result, item) } sortUserISOs(result) return result, nil } func (l *Libvirt) ImportUserISO(ctx context.Context, request ImportUserISORequest) (_ UserISO, resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if request.OwnerID <= 0 || !displayNamePattern.MatchString(request.Name) || !validSourceToken(request.SourceToken) { return UserISO{}, NewError(ErrInvalid, "invalid_user_iso", "owner_id or ISO name is invalid", nil) } if request.ID != "" && !catalogIDPattern.MatchString(request.ID) { return UserISO{}, NewError(ErrInvalid, "invalid_user_iso_id", "user ISO id must contain 32 lowercase hexadecimal characters", nil) } if request.SHA256 != "" && !sha256Pattern.MatchString(request.SHA256) { return UserISO{}, NewError(ErrInvalid, "invalid_sha256", "sha256 must contain 64 lowercase hexadecimal characters", nil) } if _, err := validateRemoteSource(request.SourceURL); err != nil { return UserISO{}, err } id := request.ID if id == "" { var err error id, err = newRandomID() if err != nil { return UserISO{}, NewError(ErrUnavailable, "entropy_unavailable", "user ISO identity could not be generated", err) } } items, err := l.ListUserISOs(ctx, request.OwnerID) if err != nil { return UserISO{}, err } for _, item := range items { if item.ID == id { return UserISO{}, NewError(ErrConflict, "user_iso_exists", "user ISO already exists on this host", nil) } if strings.EqualFold(item.Name, request.Name) { return UserISO{}, NewError(ErrConflict, "user_iso_name_exists", "a user ISO with this name already exists", nil) } } existing, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleUserISO), userISOImageVolumeName(request.OwnerID, id)) if err != nil { return UserISO{}, err } if existing != nil { existing.Free() return UserISO{}, NewError(ErrConflict, "user_iso_exists", "user ISO already exists on this host", nil) } pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleUserISO)) if err != nil { return UserISO{}, translateLibvirtError("lookup user ISO pool", err) } defer pool.Free() mutationStarted = true volume, size, digest, err := l.downloadVolume(ctx, pool, userISOImageVolumeName(request.OwnerID, id), "raw", request.SourceURL, request.SourceToken, 0, maxUserISOBytes, request.SHA256) if err != nil { return UserISO{}, err } defer volume.Free() if err := l.verifyBootableISO(ctx, volume, size); err != nil { return UserISO{}, l.rollbackImportedVolume(volume, err, "user ISO") } item := UserISO{ID: id, OwnerID: request.OwnerID, Name: request.Name, SizeBytes: uint64(size), SHA256: digest, CreatedAt: time.Now().UTC()} if err := l.writeCatalogEntry(ctx, l.storagePoolName(StorageRoleUserISO), userISOMetadataVolumeName(request.OwnerID, id), item, false); err != nil { cleanupErr := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL) if cleanupErr != nil { return UserISO{}, operation.MarkUncertain(errors.Join(err, mutationLibvirtError("roll back user ISO", cleanupErr))) } return UserISO{}, err } return item, nil } func (l *Libvirt) DeleteUserISO(ctx context.Context, id string, ownerID int64) (resultErr error) { mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() if err := ctx.Err(); err != nil { return err } if ownerID <= 0 || !catalogIDPattern.MatchString(id) { return NewError(ErrInvalid, "invalid_user_iso", "owner_id or ISO id is invalid", nil) } imageExists, metadataExists, err := l.catalogArtifactPresence(l.storagePoolName(StorageRoleUserISO), userISOImageVolumeName(ownerID, id), userISOMetadataVolumeName(ownerID, id)) if err != nil { return err } evidence := catalogDeleteEvidence{ label: "user ISO", notFoundCode: "user_iso_not_found", inconsistentCode: "user_iso_artifacts_inconsistent", } if err := validateCatalogDeletePresence(imageExists, metadataExists, evidence); err != nil { return err } item, err := l.loadUserISO(ctx, ownerID, id) if err != nil { return catalogDeleteEvidenceChanged(err, evidence) } if item.OwnerID != ownerID { return NewError(ErrConflict, evidence.inconsistentCode, "user ISO managed metadata ownership is inconsistent", nil) } volume, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleUserISO), userISOImageVolumeName(ownerID, id)) if err != nil { return err } if volume == nil { return NewError(ErrConflict, evidence.inconsistentCode, "user ISO image disappeared during deletion", nil) } defer volume.Free() used, err := l.volumeReferenced(volume) if err != nil { return err } if used { return NewError(ErrConflict, "user_iso_in_use", "user ISO is attached to a VM", nil) } mutationStarted = true if err := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL); err != nil { return operation.MarkUncertain(mutationLibvirtError("delete user ISO volume", err)) } if err := l.deleteCatalogEntry(l.storagePoolName(StorageRoleUserISO), userISOMetadataVolumeName(ownerID, id)); err != nil { return operation.MarkUncertain(err) } return l.confirmCatalogArtifactsAbsent(l.storagePoolName(StorageRoleUserISO), userISOImageVolumeName(ownerID, id), userISOMetadataVolumeName(ownerID, id), "user ISO") } func (l *Libvirt) confirmCatalogArtifactsAbsent(poolName, imageName, metadataName, label string) error { imageExists, metadataExists, err := l.catalogArtifactPresence(poolName, imageName, metadataName) if err != nil { return operation.MarkUncertain(err) } if imageExists || metadataExists { return operation.MarkUncertain(NewError(ErrConflict, "catalog_cleanup_pending", label+" managed artifacts remain after deletion", nil)) } return nil } func (l *Libvirt) loadImageTemplate(ctx context.Context, id string) (ImageTemplate, error) { if !templateIDPattern.MatchString(id) { return ImageTemplate{}, NewError(ErrInvalid, "invalid_template_id", "template id is invalid", nil) } var item ImageTemplate if err := l.readCatalogEntry(ctx, l.storagePoolName(StorageRoleTemplate), templateMetadataVolumeName(id), &item); err != nil { return ImageTemplate{}, err } if item.ID != id || item.Revision == 0 || !generationTokenPattern.MatchString(item.GenerationToken) || !sha256Pattern.MatchString(item.SHA256) || item.SizeBytes < uint64(minImportBytes) || item.VirtualSizeBytes == 0 { return ImageTemplate{}, NewError(ErrConflict, "template_catalog_invalid", "template catalog metadata is invalid", nil) } volume, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleTemplate), templateVolumeName(id)) if err != nil { return ImageTemplate{}, err } if volume == nil { return ImageTemplate{}, NewError(ErrConflict, "template_volume_missing", "template catalog references a missing image volume", nil) } info, err := volume.GetInfo() volume.Free() if err != nil { return ImageTemplate{}, translateLibvirtError("read template volume info", err) } if info.Capacity != item.VirtualSizeBytes { return ImageTemplate{}, NewError(ErrConflict, "template_capacity_changed", "template volume capacity does not match catalog metadata", nil) } return item, nil } func (l *Libvirt) loadRescueTemplate(ctx context.Context, id string) (RescueTemplate, error) { if !catalogIDPattern.MatchString(id) { return RescueTemplate{}, NewError(ErrInvalid, "invalid_rescue_template_id", "rescue template id is invalid", nil) } var item RescueTemplate if err := l.readCatalogEntry(ctx, l.storagePoolName(StorageRoleRescue), rescueMetadataVolumeName(id), &item); err != nil { return RescueTemplate{}, err } if item.ID != id || validateRescueTemplateIdentity(item) != nil { return RescueTemplate{}, NewError(ErrConflict, "rescue_catalog_invalid", "rescue template catalog metadata is invalid", nil) } volume, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleRescue), rescueImageVolumeName(id)) if err != nil { return RescueTemplate{}, err } if volume == nil { return RescueTemplate{}, NewError(ErrConflict, "rescue_volume_missing", "rescue template catalog references a missing ISO volume", nil) } info, err := volume.GetInfo() volume.Free() if err != nil { return RescueTemplate{}, translateLibvirtError("read rescue template volume info", err) } if info.Capacity != item.SizeBytes { return RescueTemplate{}, NewError(ErrConflict, "rescue_capacity_changed", "rescue template volume capacity does not match catalog metadata", nil) } return item, nil } func (l *Libvirt) loadUserISO(ctx context.Context, ownerID int64, id string) (UserISO, error) { var item UserISO if err := l.readCatalogEntry(ctx, l.storagePoolName(StorageRoleUserISO), userISOMetadataVolumeName(ownerID, id), &item); err != nil { return UserISO{}, err } if item.OwnerID != ownerID || item.ID != id || !catalogIDPattern.MatchString(item.ID) || !sha256Pattern.MatchString(item.SHA256) { return UserISO{}, NewError(ErrConflict, "user_iso_catalog_invalid", "user ISO catalog metadata is invalid", nil) } return item, nil } func (l *Libvirt) readCatalogEntry(ctx context.Context, poolName, name string, destination any) error { volume, err := l.lookupOptionalManagedVolume(poolName, name) if err != nil { return err } if volume == nil { return NewError(ErrNotFound, "catalog_entry_not_found", "catalog entry was not found", nil) } defer volume.Free() contents, err := l.downloadSmallVolume(ctx, volume, catalogMetadataLimit) if err != nil { return err } if err := json.Unmarshal(contents, destination); err != nil { return NewError(ErrConflict, "catalog_entry_invalid", "catalog entry is invalid", err) } return nil } func (l *Libvirt) writeCatalogEntry(ctx context.Context, poolName, name string, value any, replace bool) error { encoded, err := json.Marshal(value) if err != nil { return err } if len(encoded) == 0 || len(encoded) > catalogMetadataLimit { return NewError(ErrInvalid, "catalog_entry_too_large", "catalog entry exceeds its size limit", nil) } pool, err := l.conn.LookupStoragePoolByName(poolName) if err != nil { return translateLibvirtError("lookup catalog storage pool", err) } defer pool.Free() existing, lookupErr := pool.LookupStorageVolByName(name) if lookupErr == nil { if !replace { existing.Free() return NewError(ErrConflict, "catalog_entry_exists", "catalog entry already exists", nil) } if err := existing.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL); err != nil { existing.Free() return mutationLibvirtError("replace catalog entry", err) } existing.Free() } else if !isNoStorageVolume(lookupErr) { return translateLibvirtError("lookup catalog entry", lookupErr) } document, err := storageVolumeXML(name, uint64(len(encoded)), "raw") if err != nil { return err } volume, err := pool.StorageVolCreateXML(document, 0) if err != nil { return operation.MarkUncertain(mutationLibvirtError("create catalog entry", err)) } defer volume.Free() if err := l.uploadVolume(ctx, volume, encoded); err != nil { if operation.IsUncertain(err) { return operation.MarkUncertain(err) } cleanupErr := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL) if cleanupErr != nil { return operation.MarkUncertain(errors.Join(err, mutationLibvirtError("roll back catalog entry", cleanupErr))) } return err } return nil } func (l *Libvirt) deleteCatalogEntry(poolName, name string) error { volume, err := l.lookupOptionalManagedVolume(poolName, name) if err != nil { return err } if volume == nil { return NewError(ErrNotFound, "catalog_entry_not_found", "catalog entry was not found", nil) } defer volume.Free() if err := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL); err != nil { return mutationLibvirtError("delete catalog entry", err) } return nil } func (l *Libvirt) templateVolume(id string) (*libvirt.StoragePool, *libvirt.StorageVol, error) { pool, err := l.conn.LookupStoragePoolByName(l.storagePoolName(StorageRoleTemplate)) if err != nil { return nil, nil, translateLibvirtError("lookup template storage pool", err) } volume, err := pool.LookupStorageVolByName(templateVolumeName(id)) if err != nil { pool.Free() if isNoStorageVolume(err) { return nil, nil, NewError(ErrConflict, "template_volume_missing", "template catalog references a missing image volume", err) } return nil, nil, translateLibvirtError("lookup template volume", err) } return pool, volume, nil } func (l *Libvirt) downloadVolume(ctx context.Context, pool *libvirt.StoragePool, name, format, sourceURL, sourceToken string, expectedSize, maximum int64, expectedSHA string) (_ *libvirt.StorageVol, _ int64, _ string, resultErr error) { // Download/format checks precede the first host mutation. Callers may already // have entered this mutating helper, so preserve this narrower no-effect proof. mutationStarted := false defer func() { if !mutationStarted { resultErr = operation.MarkNotApplied(resultErr) } }() parsed, err := validateRemoteSource(sourceURL) if err != nil { return nil, 0, "", err } if !validSourceToken(sourceToken) { return nil, 0, "", NewError(ErrInvalid, "invalid_source_token", "source_token must contain 32-512 URL-safe characters", nil) } request, err := http.NewRequestWithContext(ctx, http.MethodGet, parsed.String(), nil) if err != nil { return nil, 0, "", NewError(ErrInvalid, "invalid_source_url", "source URL request is invalid", err) } if sourceToken != "" { request.Header.Set("Authorization", "Bearer "+sourceToken) } client := remoteHTTPClient(sourceToken == "") defer client.CloseIdleConnections() response, err := client.Do(request) if err != nil { return nil, 0, "", NewError(ErrUnavailable, "source_download_failed", "source image could not be downloaded", err) } defer response.Body.Close() if response.StatusCode != http.StatusOK { return nil, 0, "", NewError(ErrUnavailable, "source_download_failed", "source image server returned a non-200 status", nil) } if encoding := strings.TrimSpace(strings.ToLower(response.Header.Get("Content-Encoding"))); encoding != "" && encoding != "identity" { return nil, 0, "", NewError(ErrInvalid, "invalid_source_encoding", "source image must use identity content encoding", nil) } sourceSize, err := resolveImportSourceSize(response.ContentLength, expectedSize, maximum) if err != nil { return nil, 0, "", err } source := io.Reader(response.Body) capacity := uint64(sourceSize) if format == "qcow2" { header := make([]byte, qcow2HeaderBytes) if _, err := io.ReadFull(response.Body, header); err != nil { return nil, 0, "", NewError(ErrInvalid, "invalid_qcow2", "QCOW2 header is incomplete", err) } capacity, err = validateQCOW2Header(header) if err != nil { return nil, 0, "", err } source = io.MultiReader(bytes.NewReader(header), response.Body) } document, err := storageVolumeXML(name, capacity, format) if err != nil { return nil, 0, "", err } mutationStarted = true volume, err := pool.StorageVolCreateXML(document, 0) if err != nil { return nil, 0, "", operation.MarkUncertain(mutationLibvirtError("create imported image volume", err)) } stream, err := l.conn.NewStream(libvirt.STREAM_NONBLOCK) if err != nil { failure := translateLibvirtError("create image upload stream", err) failure = l.rollbackImportedVolume(volume, failure, "imported image") volume.Free() return nil, 0, "", failure } transfer := &storageStreamTransfer{stream: stream} if err := volume.Upload(stream, 0, uint64(sourceSize), 0); err != nil { failure := mutationLibvirtError("open imported image upload", transfer.abort(err)) failure = l.rollbackImportedVolume(volume, failure, "imported image") volume.Free() return nil, 0, "", failure } hash := sha256.New() hashedSource := io.TeeReader(source, hash) written, copyErr := io.CopyN(&storageStreamWriter{ctx: ctx, transfer: transfer}, hashedSource, sourceSize) if errors.Is(copyErr, io.EOF) { copyErr = io.ErrUnexpectedEOF } if copyErr == nil { var extra [1]byte count, readErr := hashedSource.Read(extra[:]) switch { case count > 0: copyErr = errors.New("source image exceeds declared size") case readErr == nil: copyErr = io.ErrNoProgress case !errors.Is(readErr, io.EOF): copyErr = readErr } } digest := hex.EncodeToString(hash.Sum(nil)) if copyErr == nil && expectedSHA != "" && digest != expectedSHA { copyErr = errors.New("source image SHA-256 mismatch") } if copyErr == nil { copyErr = transfer.finish(ctx) } else { copyErr = transfer.abort(copyErr) } if copyErr != nil { failure := NewError(ErrUnavailable, "image_import_failed", "image import did not complete", copyErr) if strings.Contains(copyErr.Error(), "SHA-256") { failure = NewError(ErrInvalid, "sha256_mismatch", "source image SHA-256 does not match", copyErr) } if operation.IsUncertain(copyErr) { volume.Free() return nil, 0, "", operation.MarkUncertain(failure) } cleanupErr := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL) volume.Free() if cleanupErr != nil { return nil, 0, "", operation.MarkUncertain(errors.Join(failure, mutationLibvirtError("roll back imported image", cleanupErr))) } return nil, 0, "", failure } return volume, written, digest, nil } func (l *Libvirt) rollbackImportedVolume(volume *libvirt.StorageVol, cause error, label string) error { if operation.IsUncertain(cause) { return cause } if cleanupErr := volume.Delete(libvirt.STORAGE_VOL_DELETE_NORMAL); cleanupErr != nil { return operation.MarkUncertain(errors.Join(cause, mutationLibvirtError("roll back "+label+" volume", cleanupErr))) } return cause } func (l *Libvirt) verifyBootableISO(ctx context.Context, volume *libvirt.StorageVol, size int64) error { if size < minImportBytes { return NewError(ErrInvalid, "invalid_iso", "ISO image must be at least 1 MiB", nil) } const ( sectorSize = uint64(2048) firstDescriptor = uint64(16) lastDescriptor = uint64(80) ) length := (lastDescriptor - firstDescriptor) * sectorSize contents, err := l.downloadStorageVolume(ctx, volume, firstDescriptor*sectorSize, length) if err != nil { if errors.Is(err, io.ErrUnexpectedEOF) { return NewError(ErrInvalid, "invalid_iso", "ISO image descriptor region is incomplete", err) } return translateLibvirtError("read ISO verification stream", err) } if uint64(len(contents)) != length { return NewError(ErrInvalid, "invalid_iso", "ISO image descriptor region is incomplete", nil) } bootable := false for offset := 0; offset+int(sectorSize) <= len(contents); offset += int(sectorSize) { descriptor := contents[offset : offset+int(sectorSize)] if string(descriptor[1:6]) != "CD001" { return NewError(ErrInvalid, "invalid_iso", "image is not a valid ISO 9660 filesystem", nil) } if descriptor[0] == 0 && strings.TrimRight(string(descriptor[7:30]), " ") == "EL TORITO SPECIFICATION" && binary.LittleEndian.Uint32(descriptor[71:75]) > 0 { bootable = true } if descriptor[0] == 255 { break } } if !bootable { return NewError(ErrInvalid, "iso_not_bootable", "ISO image does not contain an El Torito boot record", nil) } return nil } func (l *Libvirt) volumeReferenced(volume *libvirt.StorageVol) (bool, error) { path, err := volume.GetPath() if err != nil { return false, translateLibvirtError("read storage volume path", err) } domains, err := l.conn.ListAllDomains(0) if err != nil { return false, translateLibvirtError("list domains for volume reference check", err) } for index := range domains { domain := &domains[index] document, xmlErr := domain.GetXMLDesc(libvirt.DOMAIN_XML_INACTIVE) domain.Free() if xmlErr != nil { return false, translateLibvirtError("read domain XML for volume reference check", xmlErr) } var definition struct { Devices struct { Disks []struct { Source struct { File string `xml:"file,attr"` Dev string `xml:"dev,attr"` } `xml:"source"` } `xml:"disk"` } `xml:"devices"` } if err := xml.Unmarshal([]byte(document), &definition); err != nil { return false, fmt.Errorf("parse domain volume references: %w", err) } for _, disk := range definition.Devices.Disks { if disk.Source.File == path || disk.Source.Dev == path { return true, nil } } } return false, nil } func (l *Libvirt) reconcileCatalogOperation(ctx context.Context, record operation.Record) (operation.Resolution, bool, error) { type target struct { poolName string imageName string metaName string resourceType string id string ownerID int64 load func() (any, error) } var current target switch record.Action { case "update-template": id, ok := strings.CutPrefix(record.ResourceID, "template:") if !ok || !templateIDPattern.MatchString(id) { return operation.Resolution{}, true, NewError(ErrInvalid, "invalid_operation_resource", "template operation resource is invalid", nil) } // The Journal intentionally does not retain the raw update request. // A current name or revision therefore cannot prove that this exact // operation applied; only its immutable terminal result is bound to the // operation fingerprint. Keep an uncertain failure inconclusive. return operation.Resolution{}, true, nil case "import-template", "delete-template": id, ok := strings.CutPrefix(record.ResourceID, "template:") if !ok || !templateIDPattern.MatchString(id) { return operation.Resolution{}, true, NewError(ErrInvalid, "invalid_operation_resource", "template operation resource is invalid", nil) } current = target{ poolName: l.storagePoolName(StorageRoleTemplate), imageName: templateVolumeName(id), metaName: templateMetadataVolumeName(id), resourceType: "template", id: id, load: func() (any, error) { return l.loadImageTemplate(ctx, id) }, } case "import-rescue-template", "delete-rescue-template": id, ok := strings.CutPrefix(record.ResourceID, "rescue-template:") if !ok || !catalogIDPattern.MatchString(id) { return operation.Resolution{}, true, NewError(ErrInvalid, "invalid_operation_resource", "rescue template operation resource is invalid", nil) } current = target{ poolName: l.storagePoolName(StorageRoleRescue), imageName: rescueImageVolumeName(id), metaName: rescueMetadataVolumeName(id), resourceType: "rescue_template", id: id, load: func() (any, error) { return l.loadRescueTemplate(ctx, id) }, } case "import-user-iso", "delete-user-iso": value, ok := strings.CutPrefix(record.ResourceID, "user-iso:") if !ok { return operation.Resolution{}, true, NewError(ErrInvalid, "invalid_operation_resource", "user ISO operation resource is invalid", nil) } ownerText, id, ok := strings.Cut(value, ":") ownerID, parseErr := strconv.ParseInt(ownerText, 10, 64) if !ok || parseErr != nil || ownerID <= 0 || !catalogIDPattern.MatchString(id) { return operation.Resolution{}, true, NewError(ErrInvalid, "invalid_operation_resource", "user ISO operation resource is invalid", parseErr) } current = target{ poolName: l.storagePoolName(StorageRoleUserISO), imageName: userISOImageVolumeName(ownerID, id), metaName: userISOMetadataVolumeName(ownerID, id), resourceType: "user_iso", id: id, ownerID: ownerID, load: func() (any, error) { return l.loadUserISO(ctx, ownerID, id) }, } default: return operation.Resolution{}, false, nil } imageExists, metadataExists, err := l.catalogArtifactPresence(current.poolName, current.imageName, current.metaName) if err != nil { return operation.Resolution{}, true, err } if imageExists != metadataExists { return operation.Resolution{}, true, nil } deleting := strings.HasPrefix(record.Action, "delete-") if !imageExists { if deleting { result, marshalErr := json.Marshal(CatalogDeleteResult{ ResourceType: current.resourceType, ID: current.id, OwnerID: current.ownerID, Deleted: true, ManagedImageAbsent: true, ManagedMetadataAbsent: true, ManagedArtifactsAbsent: true, }) if marshalErr != nil { return operation.Resolution{}, true, marshalErr } return operation.Resolution{Resolved: true, Succeeded: true, Result: result}, true, nil } return operation.Resolution{Resolved: true, ErrorCode: "import_not_completed", ErrorMessage: "catalog import left no host artifacts"}, true, nil } if deleting { return operation.Resolution{Resolved: true, ErrorCode: "delete_not_completed", ErrorMessage: "catalog entry and image are still present"}, true, nil } item, err := current.load() if err != nil { return operation.Resolution{}, true, err } encoded, err := json.Marshal(item) if err != nil { return operation.Resolution{}, true, err } return operation.Resolution{Resolved: true, Succeeded: true, Result: encoded}, true, nil } func (l *Libvirt) catalogArtifactPresence(poolName, imageName, metadataName string) (bool, bool, error) { image, err := l.lookupOptionalManagedVolume(poolName, imageName) if err != nil { return false, false, err } imageExists := image != nil if image != nil { image.Free() } metadata, err := l.lookupOptionalManagedVolume(poolName, metadataName) if err != nil { return false, false, err } metadataExists := metadata != nil if metadata != nil { metadata.Free() } return imageExists, metadataExists, nil } func isNoStorageVolume(err error) bool { var libvirtErr libvirt.Error return errors.As(err, &libvirtErr) && libvirtErr.Code == libvirt.ERR_NO_STORAGE_VOL }