Invoke-OPNSenseVMDeployment/docs/New-OPNSenseVirtualMachine.md

New-OPNSenseVirtualMachine

Function index | Repository readme | Source

Idempotently creates and configures the OPNsense virtual machine.

Description

The virtual machine is created as a generation two virtual machine with secure boot disabled, which is a requirement of the FreeBSD based appliance.

Every setting is applied on each execution rather than only at creation time, so an existing virtual machine is reconciled with the requested configuration instead of being recreated.

• The processor count is derived from a percentage of the logical processors that the host exposes.
• The boot virtual hard disk and the configuration virtual hard disk are attached to the storage controller.
• The installation media is attached to a virtual disc drive.
• The local area network adapter is added first so that the appliance enumerates it as its first network interface device, and it is placed into trunk mode so that every planned virtual local area network is carried to it.
• The boot order is set to the boot virtual hard disk, followed by the disc drive, followed by the local area network adapter. The firmware falls through a disk that carries no boot loader, so the installation media boots while the disk is empty and the disk takes precedence by itself once the appliance has been installed onto it.

Parameters

Name	Type	Required	Aliases	Description
Name	String	Yes	N	The name of the virtual machine.
VirtualMachineDirectory	IO.DirectoryInfo	Yes	VMD	A valid folder path that the virtual machine definition is stored within.
VirtualHardDiskDirectory	IO.DirectoryInfo	Yes	VHDD	A valid folder path that the virtual hard disks are stored within.
InstallationMediaPath	IO.FileInfo	No	IMP	A valid file path to the installation disc image.
ConfigurationDiskPath	IO.FileInfo	No	CDP	A valid file path to the virtual hard disk that carries the configuration document.
WANSwitchName	String	Yes	WSN	The name of the virtual switch that the wide area network adapter is connected to.
LANSwitchName	String	Yes	LSN	The name of the virtual switch that the local area network adapter is connected to.
VlanIdList	Int32[]	No	VIL	Every virtual local area network identifier that the network plan defines. This is reported for reference and is not used to restrict the trunk.
AllowedVlanIdList	String	No	AVIL	The virtual local area network identifiers that the trunk carries. The entire range is carried by default, so a downstream lab virtual machine can be placed onto any tag without the trunk having to be reconfigured first.
ProcessorCountPercentage	Int32	No	PCP	The percentage of the logical processors of the host that is assigned to the virtual machine.
MinimumProcessorCount	Int32	No	MINPC	The lowest processor count that may be assigned.
MaximumProcessorCount	Int32	No	MAXPC	The highest processor count that may be assigned.
MemoryStartupBytes	Int64	No	MSB	The amount of memory that is assigned to the virtual machine. The OPNsense live image runs from memory before it is installed and refuses to start with less than roughly 3 GB available, so the default is set above that threshold.
MemoryMinimumBytes	Int64	No	MINMB	The lowest amount of memory that may be assigned when dynamic memory is enabled.
MemoryMaximumBytes	Int64	No	MAXMB	The highest amount of memory that may be assigned when dynamic memory is enabled.
EnableDynamicMemory	Switch	No	EDM	Enable dynamic memory. A firewall appliance is normally assigned a fixed amount of memory, so dynamic memory is disabled by default.
SystemDiskSizeBytes	Int64	No	SDSB	The size of the boot virtual hard disk.
DeploymentMarker	String	No	DM	The value that is written into the notes property of the virtual machine.
StartVirtualMachine	Switch	No	SVM	Start the virtual machine once the configuration has been applied.
ContinueOnError	Switch	No	COE	Ignore failures.

Examples

Example 1

$NewOPNSenseVirtualMachineParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary'
  $NewOPNSenseVirtualMachineParameters.Name = 'vFW-HQ-00001'
  $NewOPNSenseVirtualMachineParameters.VirtualMachineDirectory = 'D:\Virtualization\Hyper-V\Virtual Machines'
  $NewOPNSenseVirtualMachineParameters.VirtualHardDiskDirectory = 'D:\Virtualization\Hyper-V\Virtual Hard Disks'
  $NewOPNSenseVirtualMachineParameters.InstallationMediaPath = "$($ContentDirectory.FullName)\ISOs\OPNsense-26.1.6-dvd-amd64.iso"
  $NewOPNSenseVirtualMachineParameters.WANSwitchName = 'vSwitch-WAN-00001'
  $NewOPNSenseVirtualMachineParameters.LANSwitchName = 'vSwitch-LAN-00001'
  $NewOPNSenseVirtualMachineParameters.VlanIdList = @(97, 98, 99)
  $NewOPNSenseVirtualMachineParameters.Verbose = $True
$NewOPNSenseVirtualMachineResult = New-OPNSenseVirtualMachine @NewOPNSenseVirtualMachineParameters

Write-Output -InputObject ($NewOPNSenseVirtualMachineResult)

Notes

The boot virtual hard disk is named "-Boot.vhdx" and the configuration virtual hard disk is named "-Data.vhdx".

Reference

• https://learn.microsoft.com/en-us/powershell/module/hyper-v/new-vm