hyperv

package
v0.8.0-beta.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package hyperv contains pure PowerShell/XML builders and parsers for the LabLink VM-management tools. It deliberately has NO dependency on mcp-go, gRPC, or the rest of the server so the script/XML construction can be unit tested in isolation (Heimdall review §3 layering requirement).

Every script emitted here is "argument safe": caller-supplied values are emitted as single-quoted PowerShell literals via PSLit / PSBool, never interpolated directly into a command line. This matches the existing escapePSString convention in internal/mcptools/deploy.go and the network reviewer's "argument-safe construction" requirement.

Index

Constants

View Source
const (
	HyperVVMGroupSID          = "S-1-5-83-0"
	HyperVWorkerCapabilitySID = "S-1-15-3-1024-2268835264-3721307629-241982045-173645152-1490879176-104643441-2915960892-1612460704"
	LinuxVMMetadataPrefix     = "LABLINK_MANAGED_VM:"
	LinuxVMOwnershipFile      = ".lablink-linux-vm-ownership.json"
	LinuxVMOwnershipSchema    = 2
	LinuxVMCleanupAttached    = "cidata_attached"
	LinuxVMCleanupDetached    = "cidata_detached"
	LinuxVMCleanupComplete    = "complete"
	LinuxVMMetadataSchema     = 2
)
View Source
const LinuxImageBuilderMetadataPrefix = "LABLINK_LINUX_IMAGE_BUILDER_V1:"

Variables

This section is empty.

Functions

func BuildCIDATAISOScript added in v0.7.0

func BuildCIDATAISOScript(p CIDATAISOParams) (string, error)

BuildCIDATAISOScript creates a standard NoCloud seed ISO with Windows IMAPI2FS. Every seed and payload file remains at the ISO root.

func BuildCleanupLinuxVMStageScript added in v0.7.0

func BuildCleanupLinuxVMStageScript(p LinuxVMOwnershipParams) (string, error)

func BuildCleanupOwnedLinuxVMArtifactsScript added in v0.7.0

func BuildCleanupOwnedLinuxVMArtifactsScript(p CleanupOwnedLinuxVMArtifactsParams) (string, error)

func BuildConfigureExistingLinuxVMScript added in v0.7.0

func BuildConfigureExistingLinuxVMScript(p ConfigureExistingLinuxVMParams) (string, error)

func BuildCreateLinuxVMScript added in v0.7.0

func BuildCreateLinuxVMScript(p CreateLinuxVMParams) (string, error)

func BuildCreateVMScript

func BuildCreateVMScript(p CreateVMParams) (string, error)

BuildCreateVMScript builds the create_vm mutation script with the network reviewer's completeness items: Gen2 secure boot template, deterministic DVD selection by ISO path, dynamic-memory min/max/buffer, path + free-space validation, VM-off and VHD-not-in-use checks.

func BuildCreateVSwitchScript

func BuildCreateVSwitchScript(p CreateVSwitchParams) (string, error)

BuildCreateVSwitchScript builds the create_vswitch mutation script with the management-NIC severance safeguard baked in. Returns an error for invalid param combinations that can be detected statically.

func BuildDeleteVMScript added in v0.6.1

func BuildDeleteVMScript(p DeleteVMParams) (string, error)

BuildDeleteVMScript builds a dry-run-first VM deletion script. Storage deletion is restricted to the VM's own configuration directory beneath the approved managed root. Differencing parent paths are reported but never deleted.

func BuildInspectLinuxImageBuilderScript added in v0.7.0

func BuildInspectLinuxImageBuilderScript(name string, expected LinuxImageBuilderMetadata) (string, error)

func BuildInspectVMManagementScript added in v0.7.0

func BuildInspectVMManagementScript(name string) (string, error)

func BuildLinuxImageAcquireLockScript added in v0.7.0

func BuildLinuxImageAcquireLockScript(p LinuxImageLockParams) (string, error)

func BuildLinuxImageBuilderAcquireLockScript added in v0.7.0

func BuildLinuxImageBuilderAcquireLockScript(p LinuxImageBuilderLockParams) (string, error)

func BuildLinuxImageBuilderAttachScript added in v0.7.0

func BuildLinuxImageBuilderAttachScript(p LinuxImageBuilderAttachParams) (string, error)

func BuildLinuxImageBuilderDetachScript added in v0.7.0

func BuildLinuxImageBuilderDetachScript(p LinuxImageBuilderDetachParams) (string, error)

func BuildLinuxImageBuilderInventoryScript added in v0.7.0

func BuildLinuxImageBuilderInventoryScript(statePath string) (string, error)

func BuildLinuxImageBuilderReleaseLockScript added in v0.7.0

func BuildLinuxImageBuilderReleaseLockScript(p LinuxImageBuilderLockParams) (string, error)

func BuildLinuxImageBuilderSetupScript added in v0.7.0

func BuildLinuxImageBuilderSetupScript(statePath string) (string, error)

func BuildLinuxImageBuilderSourcePreflightScript added in v0.7.0

func BuildLinuxImageBuilderSourcePreflightScript(baseVHD, vmRoot, vswitch string) (string, error)

func BuildLinuxImageBuilderStartScript added in v0.7.0

func BuildLinuxImageBuilderStartScript(name string) (string, error)

func BuildLinuxImageBuilderTransformScript added in v0.7.0

func BuildLinuxImageBuilderTransformScript(p LinuxImageBuilderTransformParams) (string, error)

func BuildLinuxImageBuilderUserTaskScript added in v0.7.0

func BuildLinuxImageBuilderUserTaskScript(payload string, timeoutSeconds int) (string, error)

func BuildLinuxImageConvertScript added in v0.7.0

func BuildLinuxImageConvertScript(p LinuxImageConvertParams) (string, error)

func BuildLinuxImageDownloadScript added in v0.7.0

func BuildLinuxImageDownloadScript(p LinuxImageDownloadParams) (string, error)

func BuildLinuxImageHashScript added in v0.7.0

func BuildLinuxImageHashScript(path string) (string, error)

func BuildLinuxImagePrerequisiteProbeScript added in v0.7.0

func BuildLinuxImagePrerequisiteProbeScript() (string, error)

func BuildLinuxImagePublishScript added in v0.7.0

func BuildLinuxImagePublishScript(p LinuxImagePublishParams) (string, error)

func BuildLinuxImageRecordBuilderScript added in v0.7.0

func BuildLinuxImageRecordBuilderScript(statePath, profile, vmName, nodeName string) (string, error)

func BuildLinuxImageReleaseLockScript added in v0.7.0

func BuildLinuxImageReleaseLockScript(p LinuxImageLockParams) (string, error)

func BuildLinuxImageStatusScript added in v0.7.0

func BuildLinuxImageStatusScript(cacheRoot string, diskSizeGB int) (string, error)

func BuildLinuxImageVerifyScript added in v0.7.0

func BuildLinuxImageVerifyScript(p LinuxImageVerifyParams) (string, error)

func BuildLinuxVMAcquireLockScript added in v0.7.0

func BuildLinuxVMAcquireLockScript(p LinuxVMLockParams) (string, error)

func BuildLinuxVMCIDATACleanupScript added in v0.7.0

func BuildLinuxVMCIDATACleanupScript(name, isoPath string) (string, error)

func BuildLinuxVMReleaseLockScript added in v0.7.0

func BuildLinuxVMReleaseLockScript(p LinuxVMLockParams) (string, error)

func BuildLinuxVMStartAndDiscoverScript added in v0.7.0

func BuildLinuxVMStartAndDiscoverScript(name string) (string, error)

func BuildListNicsScript

func BuildListNicsScript(includeVirtual bool, mgmtIP string) string

BuildListNicsScript builds the discovery script for physical NICs.

mgmtIP is the target-side IP address that the LabLink server uses to reach this host (the host part of the registry node Address). The NIC that owns that IP — or, failing an exact match, the NIC carrying the active default route — is flagged is_management_nic / management_risk so callers and the create_vswitch safeguard can avoid severing the agent connection. For a localhost target mgmtIP is empty and only the default-route NIC is flagged (lower risk: you own your own host).

func BuildListVSwitchesScript

func BuildListVSwitchesScript() string

BuildListVSwitchesScript builds the discovery script for vSwitches.

func BuildPersistLinuxVMOwnershipScript added in v0.7.0

func BuildPersistLinuxVMOwnershipScript(p LinuxVMOwnershipParams) (string, error)

func BuildPrepareLinuxVMStageScript added in v0.7.0

func BuildPrepareLinuxVMStageScript(p LinuxVMOwnershipParams) (string, error)

func BuildReadLinuxVMMetadataScript added in v0.7.0

func BuildReadLinuxVMMetadataScript(name string) (string, error)

func BuildReconcileLinuxVMArtifactsScript added in v0.7.0

func BuildReconcileLinuxVMArtifactsScript(p ReconcileLinuxVMArtifactsParams) (string, error)

func BuildResourceSafetyScript added in v0.6.2

func BuildResourceSafetyScript(p ResourceSafetyParams) (string, error)

func BuildSetLinuxVMRegistrationScript added in v0.7.0

func BuildSetLinuxVMRegistrationScript(name string, registered bool) (string, error)

func BuildValidateExistingLinuxVMStorageScript added in v0.7.0

func BuildValidateExistingLinuxVMStorageScript(name string, expected LinuxVMMetadata) (string, error)

func EscapePS

func EscapePS(s string) string

EscapePS escapes a string for inclusion inside a PowerShell single-quoted literal by doubling embedded single quotes.

func LinuxImageBuilderManagedMetadata added in v0.7.0

func LinuxImageBuilderManagedMetadata(m LinuxImageBuilderMetadata) (string, error)

func MarshalLinuxVMMetadata added in v0.7.0

func MarshalLinuxVMMetadata(metadata LinuxVMMetadata) (string, error)

func PSBool

func PSBool(b bool) string

PSBool renders a Go bool as a PowerShell boolean literal.

func PSLit

func PSLit(s string) string

PSLit renders s as a complete single-quoted PowerShell string literal, doubling any embedded single quotes (the standard PowerShell escape).

func PreflightScript

func PreflightScript() string

PreflightScript returns the shared Test-LabLinkHyperV preamble that every mutating Hyper-V tool runs first. It verifies the Hyper-V PowerShell module is present and the caller is elevated, emitting a tagged error otherwise.

Enabling the Hyper-V role itself (Enable-WindowsOptionalFeature) requires a reboot and is out of scope for Phase 1 — we only detect-and-report.

func ResourceSafetyScript added in v0.6.2

func ResourceSafetyScript(p ResourceSafetyParams) (string, error)

ResourceSafetyScript returns a PowerShell fragment that populates $resourceSafety and throws before mutation when projected free memory or target-volume capacity would fall below the configured reserve.

func WrapTagged

func WrapTagged(body string) string

WrapTagged is the exported form of wrapTagged for sibling packages (e.g. internal/hyperv/unattend) that build their own script bodies but want the same single-tagged-line failure convention.

Types

type CIDATAISOParams added in v0.7.0

type CIDATAISOParams struct {
	SourceDir     string
	ISOPath       string
	OwnershipPath string
}

type CleanupOwnedLinuxVMArtifactsParams added in v0.7.0

type CleanupOwnedLinuxVMArtifactsParams struct {
	ISOPath   string
	ChildVHDX string
	DeleteISO bool
	DeleteVHD bool
}

type ConfigureExistingLinuxVMParams added in v0.7.0

type ConfigureExistingLinuxVMParams struct {
	Name             string
	Metadata         LinuxVMMetadata
	Ownership        LinuxVMOwnership
	MemoryMB         float64
	CPUCount         float64
	DynamicMemory    bool
	DynamicMinMB     float64
	DynamicMaxMB     float64
	DynamicBufferPct float64
}

type CreateLinuxVMParams added in v0.7.0

type CreateLinuxVMParams struct {
	Name                      string
	VMLocation                string
	ParentVHDX                string
	ChildVHDX                 string
	ISOPath                   string
	VSwitch                   string
	MemoryMB                  float64
	CPUCount                  float64
	DynamicMemory             bool
	DynamicMinMB              float64
	DynamicMaxMB              float64
	DynamicBufferPct          float64
	DiskSizeGB                float64
	MinHostReservePct         float64
	AllowHostResourcePressure bool
	ManagedMetadata           string
}

type CreateVMParams

type CreateVMParams struct {
	Name       string
	VMLocation string // -Path for VM config; empty unless UseHostDefaults

	// Exactly one of VHDPath (attach existing) or NewVHDPath (+NewVHDSizeGB).
	VHDPath      string
	NewVHDPath   string
	NewVHDSizeGB float64

	MemoryMB float64 // startup memory (default applied by caller)

	// Dynamic-memory policy. When DynamicMemory is true, Min/Max/Buffer apply.
	DynamicMemory                     bool
	DynamicMinMB                      float64
	DynamicMaxMB                      float64
	DynamicBufferPct                  float64
	CPUCount                          float64
	VSwitch                           string
	ISOPath                           string
	SecureBoot                        bool
	SecureBootTemplate                string // default MicrosoftWindows
	UseHostDefaults                   bool   // permit Hyper-V default VM location when VMLocation empty
	RequiredFreeSpaceGB               float64
	MinHostReservePct                 float64
	AllowHostResourcePressure         bool
	ExposeVirtualizationExtensions    bool
	VirtualizationBasedSecurityOptOut bool
	CreationOwnershipMarker           string
	ManagedMetadata                   string
}

CreateVMParams configures BuildCreateVMScript for a Gen2 Windows VM.

type CreateVSwitchParams

type CreateVSwitchParams struct {
	Name              string
	Type              string // "external" | "internal" | "private"
	NetAdapter        string // required when Type == external
	AllowManagementOS bool   // default true (caller sets)
	IfExists          string // "reuse" (default) | "fail" | "replace"

	// IsRemote is true when the target is a registered node (not localhost).
	// On a remote target an external switch on the management NIC is BLOCKED
	// unless AllowMgmtDisruption is true (network reviewer finding #1).
	IsRemote bool
	// AllowMgmtDisruption overrides the management-NIC safeguard.
	AllowMgmtDisruption bool
	// MgmtIP is the target-side IP the server uses to reach this host; used to
	// identify the management NIC at runtime on the target.
	MgmtIP string
}

CreateVSwitchParams configures BuildCreateVSwitchScript.

type DeleteVMParams added in v0.6.1

type DeleteVMParams struct {
	Name               string
	ManagedRoot        string
	DryRun             bool
	ForceStop          bool
	DeleteStorage      bool
	ExpectedParentVHDX string
}

type LinuxImageBuilderAttachParams added in v0.7.0

type LinuxImageBuilderAttachParams struct {
	VMName     string
	VHDXPath   string
	StatePath  string
	DiskSizeGB int
}

type LinuxImageBuilderDetachParams added in v0.7.0

type LinuxImageBuilderDetachParams struct {
	VMName    string
	VHDXPath  string
	StatePath string
	Retain    bool
	Reason    string
}

type LinuxImageBuilderLockParams added in v0.7.0

type LinuxImageBuilderLockParams struct {
	Key        string
	Owner      string
	StaleAfter int
}

type LinuxImageBuilderMetadata added in v0.7.0

type LinuxImageBuilderMetadata struct {
	SchemaVersion      int    `json:"schema_version"`
	Target             string `json:"target"`
	Profile            string `json:"profile"`
	ProfileFingerprint string `json:"profile_fingerprint"`
	VMName             string `json:"vm_name"`
	NodeName           string `json:"node_name"`
}

type LinuxImageBuilderTransformParams added in v0.7.0

type LinuxImageBuilderTransformParams struct {
	StatePath              string
	ExpectedSizeBytes      int64
	ExpectedTargetLocation int
}

type LinuxImageConvertParams added in v0.7.0

type LinuxImageConvertParams struct {
	SourceArchive   string
	DestinationVHDX string
	StatePath       string
	StageDir        string
	DiskSizeGB      int
}

type LinuxImageDownloadParams added in v0.7.0

type LinuxImageDownloadParams struct {
	CacheRoot  string
	StagingID  string
	DiskSizeGB int
}

type LinuxImageLockParams added in v0.7.0

type LinuxImageLockParams struct {
	CacheRoot string
	CacheKey  string
	Owner     string
}

type LinuxImagePublishParams added in v0.7.0

type LinuxImagePublishParams struct {
	StagedVHDX   string
	FinalVHDX    string
	MetadataPath string
	StatePath    string
	Metadata     linuximage.ImageMetadata
}

type LinuxImageVerifyParams added in v0.7.0

type LinuxImageVerifyParams struct {
	CacheRoot         string
	ExpectedImageHash string
	CacheKey          string
	DiskSizeGB        int
	Verification      linuximage.VerificationState
}

type LinuxVMLockParams added in v0.7.0

type LinuxVMLockParams struct {
	Key        string
	Owner      string
	StaleAfter int
}

type LinuxVMMetadata added in v0.7.0

type LinuxVMMetadata struct {
	SchemaVersion     int    `json:"schema_version"`
	GuestOS           string `json:"guest_os"`
	VMName            string `json:"vm_name"`
	NodeName          string `json:"node_name"`
	ManagedRoot       string `json:"managed_root"`
	ParentVHDX        string `json:"parent_vhdx"`
	ChildVHDX         string `json:"child_vhdx"`
	ExpectedCIDATAISO string `json:"expected_cidata_iso"`
	CleanupPhase      string `json:"cleanup_phase"`
	Registered        bool   `json:"registered"`
}

type LinuxVMOwnership added in v0.7.0

type LinuxVMOwnership struct {
	SchemaVersion int    `json:"schema_version"`
	VMName        string `json:"vm_name"`
	ManagedRoot   string `json:"managed_root"`
	VMLocation    string `json:"vm_location"`
	ChildVHDX     string `json:"child_vhdx"`
	ISOPath       string `json:"iso_path"`
	StageDir      string `json:"stage_dir"`
}

type LinuxVMOwnershipParams added in v0.7.0

type LinuxVMOwnershipParams struct {
	Ownership LinuxVMOwnership
}

type NIC

type NIC struct {
	Name                 string `json:"name"`
	InterfaceDescription string `json:"interface_description"`
	MAC                  string `json:"mac"`
	Status               string `json:"status"`
	LinkSpeed            string `json:"link_speed"`
	BoundVSwitch         string `json:"bound_vswitch"`
	IsManagementNIC      bool   `json:"is_management_nic"`
	ManagementRisk       bool   `json:"management_risk"`
	RecommendedExternal  bool   `json:"recommended_for_external"`
}

NIC is a parsed physical network adapter row from list_physical_nics.

func ParseNICs

func ParseNICs(jsonText string) ([]NIC, error)

ParseNICs parses the JSON array emitted by BuildListNicsScript. PowerShell emits a bare object (not an array) for a single row; ParseNICs handles both.

type ReconcileLinuxVMArtifactsParams added in v0.7.0

type ReconcileLinuxVMArtifactsParams struct {
	Name      string
	Ownership LinuxVMOwnership
}

type ResourceSafetyParams added in v0.6.2

type ResourceSafetyParams struct {
	MemoryMB                  float64
	StoragePath               string
	ReserveVHDPath            string
	ReserveRemainingGrowth    bool
	StorageReserveBytes       int64
	MinHostReservePct         float64
	AllowHostResourcePressure bool
}

type VSwitch

type VSwitch struct {
	Name              string `json:"name"`
	Type              string `json:"type"`
	NetAdapter        string `json:"net_adapter"`
	AllowManagementOS bool   `json:"allow_management_os"`
}

VSwitch is a parsed Hyper-V virtual switch row.

func ParseVSwitches

func ParseVSwitches(jsonText string) ([]VSwitch, error)

ParseVSwitches parses the JSON emitted by BuildListVSwitchesScript.

Directories

Path Synopsis
Package unattend renders Windows answer files (unattend.xml / Autounattend.xml) and builds the PowerShell injection scripts.
Package unattend renders Windows answer files (unattend.xml / Autounattend.xml) and builds the PowerShell injection scripts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL