gsadmin
a98967ebc4
The route into the lab is needed because the host has no adapter behind the appliance, and that is decided by the local area network switch rather than the wide area network one. Gating the offer on the wide area network switch was gating on the wrong thing. That switch is external in almost every deployment, because it is what gives the machines behind the appliance a path to the internet, so the gate passed nearly always and the summary printed a route for the shipped internal topology where the host already has a path and the route is redundant. When it did decline, it declined for a reason about reachability rather than the reason that matters. The two questions are now separated. Whether the route is needed is answered by the local area network switch, through the count of management operating system adapters attached to it, which is zero on a private switch and one on an internal one. Whether the route can work is answered by the wide area network switch as before. That yields three outcomes rather than two, and the third is the one worth reporting: a route that is required and cannot presently be created, along with the reason and the remedy. Reusing an existing local area network switch also rejected a private one. The candidate filter required the type to be internal, so a private switch under the expected name fell through to the name resolver and an internal switch was built beside it under a generated name, quietly producing the opposite of the topology the operator had built by hand. Both types are accepted now, and the requested type no longer filters the candidates at all, since the type is the whole difference between the two topologies. A mismatch is reported as a warning and the existing switch is reused as it is, because changing the type of a switch would detach every virtual machine already connected to it. A LANSwitchType parameter makes the transition a flag rather than a switch built by hand, which also means the deployment marker is applied and the removal path can clean it up afterwards. It defaults to internal, so the shipped behaviour is unchanged. The host adapter rename needed no change, since it already skips a switch for which no virtual adapter is found. Verified by creating a throwaway private switch, which reported its type as private, matched the widened filter, and yielded no management operating system adapter and no virtual adapter before being removed. All three route outcomes were exercised, and the wide area network reachability test still passes for the external switch and declines for both internal ones. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.6 KiB
Initialize-OPNSenseVirtualSwitch
Function index | Repository readme | Source
Idempotently resolves or creates the virtual switches that the virtual firewall is attached to.
Description
An existing external virtual switch is always preferred for the wide area network because it already provides upstream connectivity, and the default switch that the operating system creates is never selected because its addressing is not deterministic. An existing internal or private virtual switch is preferred for the local area network, but only when it was created by this tooling or when it already carries the requested name. This keeps an unrelated switch that the operator created for another purpose out of the deployment. Both types are accepted because the type is what decides whether the host receives a virtual network adapter behind the virtual firewall, so an operator who has already built one of them has expressed which topology they want. A type that differs from the requested one is reported as a warning and the existing switch is reused as it is, because changing the type of a switch would detach every virtual machine that is already connected to it.
Any switch that is created is annotated with the supplied deployment marker so that the removal path can identify exactly what may be removed.
When a switch name is already in use by a switch of an unsuitable type that this tooling did not create, the trailing numeric portion of the requested name is incremented rather than mutating a switch that the operator owns.
The virtual network adapter that the host receives from each managed switch is renamed from its generated name to the name of the switch so that it can be identified at a glance.
Parameters
| Name | Type | Required | Aliases | Description |
|---|---|---|---|---|
WANSwitchName |
String |
No | WSN | The name of the wide area network virtual switch to create when a suitable external switch does not already exist. |
LANSwitchName |
String |
No | LSN | The name of the local area network virtual switch to create when a suitable internal switch does not already exist. |
LANSwitchType |
String |
No | LST | The type of local area network virtual switch to create. An internal switch gives the host a virtual network adapter behind the virtual firewall, which is the default. A private switch does not, which leaves the host to reach the networks behind the virtual firewall by way of a route towards the wide area network address instead. An existing switch of either type is reused regardless of this value. |
DeploymentMarker |
String |
No | DM | The value that is written into the notes property of every object that is created. |
PreferredWANSwitchName |
String |
No | PWSN | The name of a specific existing switch to use for the wide area network. |
PreferredNetAdapterName |
String |
No | PNAN | The name or the interface description of a specific physical network adapter to bind the external virtual switch to. When this parameter is not specified, the adapter is selected automatically. |
NetworkInterruptionWarningDelay |
TimeSpan |
No | NIWD | The amount of time to wait after the interruption warning has been written and before the external virtual switch is created, which gives an operator the opportunity to interrupt the script. Specify a zero duration to proceed immediately. |
ConnectivitySettleTimeout |
TimeSpan |
No | CST | The maximum amount of time to wait for the host to regain an address on the new external virtual switch. |
SkipConnectivityWait |
Switch |
No | SCW | Do not wait for the host to regain an address after the external virtual switch has been created. |
SkipHostNetworkAdapterRename |
Switch |
No | SHNAR | Do not rename the virtual network adapter that the host receives from each managed switch. |
ContinueOnError |
Switch |
No | COE | Ignore failures. |
Examples
Example 1
$InitializeOPNSenseVirtualSwitchParameters = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary'
$InitializeOPNSenseVirtualSwitchParameters.WANSwitchName = 'vSwitch-WAN-00001'
$InitializeOPNSenseVirtualSwitchParameters.LANSwitchName = 'vSwitch-LAN-00001'
$InitializeOPNSenseVirtualSwitchParameters.DeploymentMarker = 'Created by Invoke-OPNSenseVMDeployment'
$InitializeOPNSenseVirtualSwitchParameters.Verbose = $True
$InitializeOPNSenseVirtualSwitchResult = Initialize-OPNSenseVirtualSwitch @InitializeOPNSenseVirtualSwitchParameters
Write-Output -InputObject ($InitializeOPNSenseVirtualSwitchResult)
Notes
The physical network adapter for a new external switch is selected automatically out of the adapters that are operational, report an ethernet or wireless media type, and are not already bound to another virtual switch. An ethernet adapter is always preferred over a wireless adapter, and within each of those an adapter that already carries a default gateway is preferred because it is the one providing upstream connectivity today.
Binding a physical adapter to an external virtual switch tears down and recreates its protocol bindings, so the host loses connectivity for several seconds and a remote session running over that adapter can drop. The function therefore warns before it acts, pauses so that an operator can interrupt it, and then waits for the host to regain an address on the new switch.
Embedded teaming is only enabled on a server operating system, and only across ethernet adapters. A wireless adapter is attached through a bridge and can never participate in a team.