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
- func BuildCIDATAISOScript(p CIDATAISOParams) (string, error)
- func BuildCleanupLinuxVMStageScript(p LinuxVMOwnershipParams) (string, error)
- func BuildCleanupOwnedLinuxVMArtifactsScript(p CleanupOwnedLinuxVMArtifactsParams) (string, error)
- func BuildConfigureExistingLinuxVMScript(p ConfigureExistingLinuxVMParams) (string, error)
- func BuildCreateLinuxVMScript(p CreateLinuxVMParams) (string, error)
- func BuildCreateVMScript(p CreateVMParams) (string, error)
- func BuildCreateVSwitchScript(p CreateVSwitchParams) (string, error)
- func BuildDeleteVMScript(p DeleteVMParams) (string, error)
- func BuildInspectLinuxImageBuilderScript(name string, expected LinuxImageBuilderMetadata) (string, error)
- func BuildInspectVMManagementScript(name string) (string, error)
- func BuildLinuxImageAcquireLockScript(p LinuxImageLockParams) (string, error)
- func BuildLinuxImageBuilderAcquireLockScript(p LinuxImageBuilderLockParams) (string, error)
- func BuildLinuxImageBuilderAttachScript(p LinuxImageBuilderAttachParams) (string, error)
- func BuildLinuxImageBuilderDetachScript(p LinuxImageBuilderDetachParams) (string, error)
- func BuildLinuxImageBuilderInventoryScript(statePath string) (string, error)
- func BuildLinuxImageBuilderReleaseLockScript(p LinuxImageBuilderLockParams) (string, error)
- func BuildLinuxImageBuilderSetupScript(statePath string) (string, error)
- func BuildLinuxImageBuilderSourcePreflightScript(baseVHD, vmRoot, vswitch string) (string, error)
- func BuildLinuxImageBuilderStartScript(name string) (string, error)
- func BuildLinuxImageBuilderTransformScript(p LinuxImageBuilderTransformParams) (string, error)
- func BuildLinuxImageBuilderUserTaskScript(payload string, timeoutSeconds int) (string, error)
- func BuildLinuxImageConvertScript(p LinuxImageConvertParams) (string, error)
- func BuildLinuxImageDownloadScript(p LinuxImageDownloadParams) (string, error)
- func BuildLinuxImageHashScript(path string) (string, error)
- func BuildLinuxImagePrerequisiteProbeScript() (string, error)
- func BuildLinuxImagePublishScript(p LinuxImagePublishParams) (string, error)
- func BuildLinuxImageRecordBuilderScript(statePath, profile, vmName, nodeName string) (string, error)
- func BuildLinuxImageReleaseLockScript(p LinuxImageLockParams) (string, error)
- func BuildLinuxImageStatusScript(cacheRoot string, diskSizeGB int) (string, error)
- func BuildLinuxImageVerifyScript(p LinuxImageVerifyParams) (string, error)
- func BuildLinuxVMAcquireLockScript(p LinuxVMLockParams) (string, error)
- func BuildLinuxVMCIDATACleanupScript(name, isoPath string) (string, error)
- func BuildLinuxVMReleaseLockScript(p LinuxVMLockParams) (string, error)
- func BuildLinuxVMStartAndDiscoverScript(name string) (string, error)
- func BuildListNicsScript(includeVirtual bool, mgmtIP string) string
- func BuildListVSwitchesScript() string
- func BuildPersistLinuxVMOwnershipScript(p LinuxVMOwnershipParams) (string, error)
- func BuildPrepareLinuxVMStageScript(p LinuxVMOwnershipParams) (string, error)
- func BuildReadLinuxVMMetadataScript(name string) (string, error)
- func BuildReconcileLinuxVMArtifactsScript(p ReconcileLinuxVMArtifactsParams) (string, error)
- func BuildResourceSafetyScript(p ResourceSafetyParams) (string, error)
- func BuildSetLinuxVMRegistrationScript(name string, registered bool) (string, error)
- func BuildValidateExistingLinuxVMStorageScript(name string, expected LinuxVMMetadata) (string, error)
- func EscapePS(s string) string
- func LinuxImageBuilderManagedMetadata(m LinuxImageBuilderMetadata) (string, error)
- func MarshalLinuxVMMetadata(metadata LinuxVMMetadata) (string, error)
- func PSBool(b bool) string
- func PSLit(s string) string
- func PreflightScript() string
- func ResourceSafetyScript(p ResourceSafetyParams) (string, error)
- func WrapTagged(body string) string
- type CIDATAISOParams
- type CleanupOwnedLinuxVMArtifactsParams
- type ConfigureExistingLinuxVMParams
- type CreateLinuxVMParams
- type CreateVMParams
- type CreateVSwitchParams
- type DeleteVMParams
- type LinuxImageBuilderAttachParams
- type LinuxImageBuilderDetachParams
- type LinuxImageBuilderLockParams
- type LinuxImageBuilderMetadata
- type LinuxImageBuilderTransformParams
- type LinuxImageConvertParams
- type LinuxImageDownloadParams
- type LinuxImageLockParams
- type LinuxImagePublishParams
- type LinuxImageVerifyParams
- type LinuxVMLockParams
- type LinuxVMMetadata
- type LinuxVMOwnership
- type LinuxVMOwnershipParams
- type NIC
- type ReconcileLinuxVMArtifactsParams
- type ResourceSafetyParams
- type VSwitch
Constants ¶
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 )
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 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 BuildLinuxImageBuilderReleaseLockScript ¶ added in v0.7.0
func BuildLinuxImageBuilderReleaseLockScript(p LinuxImageBuilderLockParams) (string, error)
func BuildLinuxImageBuilderSetupScript ¶ added in v0.7.0
func BuildLinuxImageBuilderSourcePreflightScript ¶ added in v0.7.0
func BuildLinuxImageBuilderStartScript ¶ added in v0.7.0
func BuildLinuxImageBuilderTransformScript ¶ added in v0.7.0
func BuildLinuxImageBuilderTransformScript(p LinuxImageBuilderTransformParams) (string, error)
func BuildLinuxImageBuilderUserTaskScript ¶ added in v0.7.0
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 BuildLinuxImagePrerequisiteProbeScript ¶ added in v0.7.0
func BuildLinuxImagePublishScript ¶ added in v0.7.0
func BuildLinuxImagePublishScript(p LinuxImagePublishParams) (string, error)
func BuildLinuxImageRecordBuilderScript ¶ added in v0.7.0
func BuildLinuxImageReleaseLockScript ¶ added in v0.7.0
func BuildLinuxImageReleaseLockScript(p LinuxImageLockParams) (string, error)
func BuildLinuxImageStatusScript ¶ added in v0.7.0
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 BuildLinuxVMReleaseLockScript ¶ added in v0.7.0
func BuildLinuxVMReleaseLockScript(p LinuxVMLockParams) (string, error)
func BuildLinuxVMStartAndDiscoverScript ¶ added in v0.7.0
func BuildListNicsScript ¶
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 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 BuildValidateExistingLinuxVMStorageScript ¶ added in v0.7.0
func BuildValidateExistingLinuxVMStorageScript(name string, expected LinuxVMMetadata) (string, error)
func EscapePS ¶
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 PSLit ¶
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 ¶
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 CleanupOwnedLinuxVMArtifactsParams ¶ added in v0.7.0
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 LinuxImageBuilderAttachParams ¶ added in v0.7.0
type LinuxImageBuilderDetachParams ¶ added in v0.7.0
type LinuxImageBuilderLockParams ¶ added in v0.7.0
type LinuxImageBuilderMetadata ¶ added in v0.7.0
type LinuxImageBuilderTransformParams ¶ added in v0.7.0
type LinuxImageConvertParams ¶ added in v0.7.0
type LinuxImageDownloadParams ¶ added in v0.7.0
type LinuxImageLockParams ¶ added in v0.7.0
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 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 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.
type ReconcileLinuxVMArtifactsParams ¶ added in v0.7.0
type ReconcileLinuxVMArtifactsParams struct {
Name string
Ownership LinuxVMOwnership
}
type ResourceSafetyParams ¶ added in v0.6.2
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 ¶
ParseVSwitches parses the JSON emitted by BuildListVSwitchesScript.