Files
gsadmin de49257c8d feat: Separate authorised resolvers from what they may forward towards
Modelled on the operator's production configuration, which was supplied as a
sample. Name resolution was one permit and one blanket deny, which said who may
be queried but had nothing to say about what a resolver is then allowed to do,
and pinned the appliance to whatever name server the machine generating the
document happened to be using.

Two aliases now carry the policy. The internal alias holds the resolvers a client
may query, which is the appliance itself by default, and the upstream alias holds
what an authorised resolver may forward towards. Eight rules follow, four per
transport, because each transport carries a different set of ports.

The deny inverts its destination rather than being a blanket deny placed after
the permits. That states the policy as it is actually meant, which is that name
resolution towards anything unauthorised is refused, and it stays true as the
alias is edited instead of depending upon the deny sitting at a later sequence
than every permit.

The rule permitting an authorised resolver to forward upstream changes nothing
while the internal alias holds only the appliance, because traffic the appliance
originates is not evaluated by an inbound rule. It is not redundant for that
reason. It is what makes the alias worth having: adding a real resolver to the
internal alias gives it both directions at once, reached by clients through one
rule and forwarding upstream through the other, with nothing further to write.

Nothing about name resolution is read from the machine that generates the
document any more. A resolver that machine uses is a fact about that machine
rather than about the network the appliance joins, and seeding it wrote a site
specific address into every document produced. The upstream alias defaults to
public resolvers and is overridable, and the host inspection that remains is only
for the networks it is attached to, which the parent network selection excludes.

The appliance resolves through its own resolver, which is what allows a local
record to be defined and answered authoritatively for the networks behind it, and
takes its upstream from the wide area network lease. Three settings carry that:
no static name server address is written, the lease is permitted to populate the
system list, and the local host is preferred so the appliance asks itself first.

The resolver is also switched to forwarding. Left recursing it would query the
root servers directly and the upstream the joined network expects would never be
consulted, so the appliance would resolve correctly while ignoring its own
network's resolver, which is not what taking the upstream from the lease is meant
to mean. The local zone stays transparent, so a local record is still answered
before anything is forwarded.

Verified that the document carries the eight rules in the intended order with the
deny inverted, that the aliases hold the appliance address on every planned
network and the public upstreams, that an explicit upstream list is honoured, that
no address belonging to this host appears anywhere in the output, and that every
alias named by any rule still resolves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 12:29:42 -04:00
..

Documentation

Repository readme

Every page below is generated from the comment based help of the file it documents, so it cannot drift away from the code.

Entry point

Page Purpose
Invoke-OPNSenseVMDeployment Idempotently deploys a fully preconfigured OPNsense virtual firewall into a Hyper-V lab environment.

Toolkit functions

Page Purpose
Expand-CompressedFile Expands a compressed file or archive using the first available extraction provider.
Get-HostUpstreamDNSConfiguration Determines the upstream name resolution configuration of the device that hosts the hypervisor.
Get-HyperVNextAvailableMACAddress Retrieves the next media access control address that the hypervisor will hand to a virtual machine.
Get-HyperVStorageLocation Dynamically determines where virtual machines and virtual hard disks should be stored on the hypervisor.
Get-OPNSenseInstallationMedia Idempotently acquires the OPNsense installation media.
Initialize-OPNSenseVirtualSwitch Idempotently resolves or creates the virtual switches that the virtual firewall is attached to.
Install-HyperVPlatform Idempotently detects and installs the Microsoft Hyper-V platform and its powershell management module.
New-OPNSenseConfigurationDisk Creates or refreshes the virtual hard disk that carries the OPNsense configuration document.
New-OPNSenseConfigurationDocument Generates the OPNsense configuration document from a network plan.
New-OPNSenseNetworkPlan Produces the lab network plan that the OPNsense configuration document is generated from.
New-OPNSensePasswordHash Generates a password hash in the format that OPNsense stores within its configuration document.
New-OPNSenseVirtualMachine Idempotently creates and configures the OPNsense virtual machine.
New-RandomPassword Generates a random password using a cryptographically secure random number generator.
Remove-OPNSenseDeployment Removes everything that a previous execution of the deployment created.
Save-OPNSenseConfigurationDocument Writes an OPNsense configuration document to disk.
Save-ToolkitModule Idempotently saves one or more powershell modules into the toolkit module directory.
Start-ProcessWithOutput Allows for the execution of processes with the ability to return their output without first dumping the content to a file. It can all be kept in memory.
Test-PendingReboot Determines whether the operating system is currently waiting for a restart.