Grace-Solutions/Invoke-OPNSenseVMDeployment
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Separate authorised resolvers from what they may forward towards #5

Merged
gsadmin merged 1 commits from development into main 2026-08-25 16:40:19 +00:00
Conversation 0 Commits 1 Files Changed 6
+236 -63
6 changed files with 236 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ai/specification/OPNSense-VM-Deployment-Design-Specification.md
+67 -8
View File
@@ -302,7 +302,11 @@ for UTF-8 **without BOM**, two-space indentation and `NewLineChars = "`n"`.
| `/opnsense/vlans/vlan` | One per VLAN: `if=hn0`, `tag`, `pcp=0`, `descr`, `vlanif=vlan0.<tag>` |
| `/opnsense/nat/outbound/mode` | `hybrid`, so manual rules can be added alongside the automatic ones. None are emitted |
| `/opnsense/unbound/enable` | `1` |
| `/opnsense/OPNsense/unboundplus/general/enabled` | `1`, `dnssec=1`, active interfaces = every internal interface |
| `/opnsense/OPNsense/unboundplus/general/enabled` | `1`, `dnssec=1`, `local_zone_type=transparent`, active interfaces = every internal interface |
| `/opnsense/OPNsense/unboundplus/forwarding/enabled` | `1` - forward rather than recurse, so the WAN-supplied upstream is actually used (§5.6) |
| `/opnsense/system/dnsserver` | **absent** - nothing static is written (§5.6) |
| `/opnsense/system/dnsallowoverride` | `1` - the WAN lease populates the system resolver list |
| `/opnsense/system/dnslocalhost` | `1` - the appliance asks its own resolver first |
| `/opnsense/OPNsense/Firewall/Alias/aliases/alias` | The aliases the rules are written against (§5.3) |
| `/opnsense/OPNsense/Firewall/Filter/rules/rule` | The ordered rule set (§5.3) |
| `/opnsense/OPNsense/Kea/dhcp4` | DHCP scopes and PXE options (§5.2) |
@@ -413,9 +417,10 @@ options are omitted entirely when `-SkipPXEConfiguration` is supplied.
| `RFC1918` | `network` | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` |
| `CGNAT` | `network` | `100.64.0.0/10` |
| `PARENT_NETWORK_001` | `network` | The resolved parent network, e.g. `10.130.240.0/20` |
| `DNS_SERVERS_001` | `host` | `-DNSServerAddressList`, defaulting to the firewall address on every planned network |
| `DNS_PORTS_TCP_001` | `port` | `-DNSTCPPortList`, default `53`, `853` |
| `DNS_PORTS_UDP_001` | `port` | `-DNSUDPPortList`, default `53`, `853`, `5353` |
| `AUTHORIZED_DNS_SERVERS_INTERNAL` | `host` | `-DNSServerAddressList`, defaulting to the firewall address on every planned network |
| `AUTHORIZED_DNS_SERVERS_UPSTREAM` | `host` | `-UpstreamDNSServerAddressList`, default `1.1.1.1`, `1.0.0.1`. Never read from the generating host |
| `AUTHORIZED_DNS_PORTS_TCP` | `port` | `-DNSTCPPortList`, default `53`, `853` |
| `AUTHORIZED_DNS_PORTS_UDP` | `port` | `-DNSUDPPortList`, default `53`, `853`, `5353` |
| `PXE_SERVERS_001` | `host` | The reserved PXE server address (§5.2.2). Omitted with `-SkipPXEConfiguration` |
| `INBOUND_<speed>` (x10) | `network` | Empty. Populated by the operator to impose inbound shaping (§5.4) |
| `OUTBOUND_<speed>` (x10) | `network` | Empty. Populated by the operator to impose outbound shaping (§5.4) |
@@ -437,10 +442,14 @@ Everything that would otherwise be duplicated per interface is emitted that way,
| 20 | floating | `pass` | `TCP` | `BASTION_SERVERS_001` | `any` | `BASTION_PORTS_001` |
| 30 | floating | `pass` | `any` | `RFC1918` | `PXE_SERVERS_001` | - |
| 40 | `wan`, `disablereplyto=1` | `pass` | `any` | `RFC1918` | `PARENT_NETWORK_001` | - |
| 100 | floating | `pass` | `TCP` | `RFC1918` | `DNS_SERVERS_001` | `DNS_PORTS_TCP_001` |
| 101 | floating | `pass` | `UDP` | `RFC1918` | `DNS_SERVERS_001` | `DNS_PORTS_UDP_001` |
| 200 | floating | `block` | `TCP` | `any` | `any` | `DNS_PORTS_TCP_001` |
| 201 | floating | `block` | `UDP` | `any` | `any` | `DNS_PORTS_UDP_001` |
| 100 | floating | `pass` | `TCP` | `AUTHORIZED_DNS_SERVERS_INTERNAL` | `AUTHORIZED_DNS_SERVERS_UPSTREAM` | `AUTHORIZED_DNS_PORTS_TCP` |
| 101 | floating | `pass` | `UDP` | `AUTHORIZED_DNS_SERVERS_INTERNAL` | `AUTHORIZED_DNS_SERVERS_UPSTREAM` | `AUTHORIZED_DNS_PORTS_UDP` |
| 110 | floating | `pass` | `TCP` | `RFC1918` | `AUTHORIZED_DNS_SERVERS_INTERNAL` | `AUTHORIZED_DNS_PORTS_TCP` |
| 111 | floating | `pass` | `UDP` | `RFC1918` | `AUTHORIZED_DNS_SERVERS_INTERNAL` | `AUTHORIZED_DNS_PORTS_UDP` |
| 120 | floating | `pass` | `TCP` | `RFC1918` | `(self)` | `AUTHORIZED_DNS_PORTS_TCP` |
| 121 | floating | `pass` | `UDP` | `RFC1918` | `(self)` | `AUTHORIZED_DNS_PORTS_UDP` |
| 200 | floating | `block` | `TCP` | `RFC1918` | `AUTHORIZED_DNS_SERVERS_INTERNAL`, `destination_not=1` | `AUTHORIZED_DNS_PORTS_TCP` |
| 201 | floating | `block` | `UDP` | `RFC1918` | `AUTHORIZED_DNS_SERVERS_INTERNAL`, `destination_not=1` | `AUTHORIZED_DNS_PORTS_UDP` |
| 300+ | per interface | `pass` | `any` | client zone net | paired server zone net | - |
| 500, 502, … | floating, direction `in` | `pass` | `any` | `OUTBOUND_<speed>` | `any` | - |
| 501, 503, … | floating, direction `out` | `pass` | `any` | `any` | `INBOUND_<speed>` | - |
@@ -562,6 +571,56 @@ The rule shape matches what OPNsense itself ships in `config.xml.sample` for its
descriptions are restricted to characters that OPNsense's `DescriptionField` mask accepts - notably,
no double quotes.
#### 5.3.1 Name resolution
Modelled on the operator's production configuration (`scratch/config-GSPA-HQ-FW-…-v2-…xml`), which
separates *who may be queried* from *what those resolvers may forward to*:
| Alias | Holds |
| --- | --- |
| `AUTHORIZED_DNS_SERVERS_INTERNAL` | resolvers clients may query - the appliance itself by default |
| `AUTHORIZED_DNS_SERVERS_UPSTREAM` | what an authorised resolver may forward towards |
Eight rules, four per transport (§5.3 table). Two properties are worth stating:
**The deny inverts the destination** (`destination_not=1`) rather than being a blanket deny placed
after the permits. It states the policy directly - name resolution towards anything not authorised is
refused - and remains correct as the alias is edited, instead of depending on it sitting at a higher
sequence than every permit.
**Rules 100/101 are inert while the internal alias holds only the appliance**, because traffic the
appliance originates is not evaluated by an inbound rule. They are not redundant: they are what makes
the alias extensible. Adding a real resolver (Technitium, AdGuard, Pi-hole) to the internal alias
immediately gives it both directions - clients reach it via 110/111, and it forwards upstream via
100/101 - with no rule changes.
Rules 120/121 name `(self)` explicitly. The internal alias already holds the appliance address on
every planned network, so this is ordinarily covered, but an interface address is not the only
address an appliance answers on, and stating it makes the intent explicit rather than incidental.
#### 5.3.2 How the appliance itself resolves
Deliberately **nothing** is carried across from the machine that generates the document:
| Setting | Value | Why |
| --- | --- | --- |
| `system/dnsserver` | absent | A resolver the generating host uses is a fact about that host, not about the network the appliance joins. Writing it would bake a site-specific address into every document |
| `system/dnsallowoverride` | `1` | The WAN lease populates the system resolver list at boot |
| `system/dnslocalhost` | `1` | The appliance asks its own resolver first |
| `unboundplus/general/enabled` | `1` | The resolver that answers |
| `unboundplus/general/local_zone_type` | `transparent` | A local record is answered locally before anything is forwarded |
| `unboundplus/forwarding/enabled` | `1` | Forward to the system resolver list rather than recursing |
Forwarding is what makes the lease meaningful. Left to recurse, Unbound would query the root servers
directly and the upstream the joined network expects would never be consulted - the appliance would
resolve correctly while ignoring its own network's resolver.
The consequence intended by the operator: **local records can be defined on the appliance** and are
answered authoritatively for every network behind it, while everything else follows the WAN.
`Get-HostUpstreamDNSConfiguration` is still called, but only for `HostNetworkList`, which feeds the
parent-network exclusions (§4.1). Its `RecommendedDNSServerList` is no longer consumed.
### 5.4 Traffic Shaping
Shaping is imposed at layer 3 by the packet filter, not at the hypervisor switch. Same-VLAN traffic
Invoke-OPNSenseVMDeployment.ps1
+16 -14
View File
@@ -128,7 +128,9 @@
A valid folder path that overrides the automatic determination of where the virtual machine and its virtual hard disks are stored.
.PARAMETER UpstreamDNSServerList
One or more upstream name server addresses. When this parameter is not specified, the default gateway of the host is used, followed by every name server address that the host is configured with.
The addresses that populate the "AUTHORIZED_DNS_SERVERS_UPSTREAM" alias, which an authorised internal name server is permitted to forward towards. When this parameter is not specified, the public resolver addresses of "1.1.1.1" and "1.0.0.1" are used.
These are not written into the system section of the appliance, and nothing is read from this host to populate them. The appliance resolves through the resolver that it runs itself, which is what allows a local record to be defined for it, and it takes its own upstream name server addresses from the wide area network lease. This list therefore describes what an internal name server is permitted to forward towards rather than what the appliance is configured to use.
.PARAMETER RootPassword
The password to assign to the "root" account of the appliance. When this parameter is not specified, the stock appliance password of "opnsense" is retained.
@@ -782,26 +784,26 @@ Switch (Test-ProcessElevationStatus)
}
#endregion
#region Determine the upstream name resolution configuration of the host
#region Determine the network configuration of the host
# The host is inspected for the networks it is attached to, which are excluded from the parent network selection so that the lab
# cannot collide with the machine building it. Its name server addresses are deliberately not read.
#
# A name server that this machine happens to use is a fact about this machine rather than about the network the appliance ends up
# on, and seeding it would bake a site specific address into every document this script produces. The appliance resolves through
# its own resolver and takes its upstream from the wide area network lease instead, so nothing about the generating machine needs
# to be carried across.
$GetHostUpstreamDNSConfigurationResult = Get-HostUpstreamDNSConfiguration -Verbose:$False
Switch (($Null -ieq $UpstreamDNSServerList) -or ($UpstreamDNSServerList.Count -eq 0))
{
{($_ -eq $True)}
{
[System.String[]]$UpstreamDNSServerList = $GetHostUpstreamDNSConfigurationResult.RecommendedDNSServerList.ToArray()
[System.String[]]$UpstreamDNSServerList = @('1.1.1.1', '1.0.0.1')
}
}
Switch (($Null -ieq $UpstreamDNSServerList) -or ($UpstreamDNSServerList.Count -eq 0))
{
{($_ -eq $True)}
{
$WriteLogMessage.Invoke(2, @("An upstream name server address could not be determined from the host. The public resolver addresses will be configured instead."))
[System.String[]]$UpstreamDNSServerList = @('1.1.1.1', '9.9.9.9')
}
}
$WriteLogMessage.Invoke(0, @("Authorised Upstream Name Server List: $($UpstreamDNSServerList -Join '; ')"))
#endregion
#region Generate the network plan
@@ -907,7 +909,7 @@ Switch (Test-ProcessElevationStatus)
$NewOPNSenseConfigurationDocumentParameters.NetworkPlan = $NetworkPlan
$NewOPNSenseConfigurationDocumentParameters.HostName = $HostName
$NewOPNSenseConfigurationDocumentParameters.DomainName = $DomainName
$NewOPNSenseConfigurationDocumentParameters.DNSServerList = $UpstreamDNSServerList
$NewOPNSenseConfigurationDocumentParameters.UpstreamDNSServerAddressList = $UpstreamDNSServerList
$NewOPNSenseConfigurationDocumentParameters.RootPasswordHash = $RootPasswordHash
$NewOPNSenseConfigurationDocumentParameters.SkipPXEConfiguration = $SkipPXEConfiguration.IsPresent
$NewOPNSenseConfigurationDocumentParameters.EnableIPv6 = $EnableIPv6.IsPresent
@@ -1088,7 +1090,7 @@ Switch (Test-ProcessElevationStatus)
}
}
#endregion
$DeploymentSummaryList.Add("Upstream Name Server List: $($UpstreamDNSServerList -Join '; ')")
$DeploymentSummaryList.Add("Authorised Upstream Name Server List: $($UpstreamDNSServerList -Join '; ') [The appliance itself resolves through its own resolver and takes its upstream from the wide area network lease.]")
For ($NetworkListIndex = 0; $NetworkListIndex -lt $NetworkPlan.NetworkList.Count; $NetworkListIndex++)
{
README.md
+50 -5
View File
@@ -166,9 +166,10 @@ access to `Servers_Zone_003`. Change the layout with `-NetworkRoleList`; any rol
| `RFC1918` | network | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` |
| `CGNAT` | network | `100.64.0.0/10` |
| `PARENT_NETWORK_001` | network | The parent network the lab was subnetted out of, e.g. `10.130.240.0/20` |
| `DNS_SERVERS_001` | host | The address of the firewall on every planned network |
| `DNS_PORTS_TCP_001` | port | `53`, `853` |
| `DNS_PORTS_UDP_001` | port | `53`, `853`, `5353` |
| `AUTHORIZED_DNS_SERVERS_INTERNAL` | host | The address of the firewall on every planned network. **Add your own resolver here to authorise it** |
| `AUTHORIZED_DNS_SERVERS_UPSTREAM` | host | What an authorised resolver may forward to. `1.1.1.1`, `1.0.0.1` by default |
| `AUTHORIZED_DNS_PORTS_TCP` | port | `53`, `853` |
| `AUTHORIZED_DNS_PORTS_UDP` | port | `53`, `853`, `5353` |
| `BASTION_SERVERS_001` | host | The administrative jump hosts. Set with `-BastionServerAddressList` |
| `BASTION_PORTS_001` | port | `22`, `80`, `443`, `3389`, `5985`, `5986` |
| `PXE_SERVERS_001` | host | The reserved address of the PXE server (§ below) |
@@ -187,8 +188,10 @@ rule applied to all interfaces rather than sixteen copies.
| 20 | floating | pass | `BASTION_SERVERS_001` reaches everything over `BASTION_PORTS_001` |
| 30 | floating | pass | `RFC1918` reaches `PXE_SERVERS_001` |
| 40 | WAN | pass | `RFC1918` reaches `PARENT_NETWORK_001`, so a private source upstream can reach the lab (§ [Reaching the lab from the host](#reaching-the-lab-from-the-host)) |
| 100-101 | floating | pass | `RFC1918` may resolve against `DNS_SERVERS_001`, one rule per transport |
| 200-201 | floating | block | Name resolution towards any other resolver is dropped |
| 100-101 | floating | pass | `AUTHORIZED_DNS_SERVERS_INTERNAL` may forward to `AUTHORIZED_DNS_SERVERS_UPSTREAM` |
| 110-111 | floating | pass | `RFC1918` may resolve against `AUTHORIZED_DNS_SERVERS_INTERNAL` |
| 120-121 | floating | pass | `RFC1918` may resolve against `(self)`, the firewall's own resolver |
| 200-201 | floating | block | `RFC1918` to **`NOT`** `AUTHORIZED_DNS_SERVERS_INTERNAL` - leak prevention |
| 300+ | per interface | pass | Each client zone reaches the server zone carrying the same index |
| 500-519 | floating | pass | One pair per shaping profile, each through its own pipe |
| 900+ | per interface | pass | Everything else originating from that network |
@@ -199,6 +202,48 @@ bound to an interface. Descriptions are generic, so a rule reads the same wherev
The 900 series is what makes the lab permissive by default. Supply `-EnableZoneIsolation` to omit
it, and the management, jump host, name resolution, and zone pairing rules become the entire policy.
### Name resolution
Two aliases, one for resolvers clients may use and one for what those resolvers may forward to:
```
clients ──► AUTHORIZED_DNS_SERVERS_INTERNAL ──► AUTHORIZED_DNS_SERVERS_UPSTREAM
(the firewall, by default) (1.1.1.1, 1.0.0.1 by default)
```
| Seq | Action | Rule |
| --- | --- | --- |
| 100-101 | pass | An authorised resolver may forward upstream |
| 110-111 | pass | Anything in `RFC1918` may query an authorised resolver |
| 120-121 | pass | Anything in `RFC1918` may query `(self)` |
| 200-201 | block | `RFC1918` → **NOT** an authorised resolver |
The block uses an **inverted destination** rather than a blanket deny sitting after the permits. It
states the policy directly - *DNS to anything that is not authorised is refused* - and stays true as
you edit the alias, instead of depending on sequence ordering.
**To authorise your own resolver**, add its address to `AUTHORIZED_DNS_SERVERS_INTERNAL`. Rules
110/111 then let clients reach it and 100/101 already let it forward upstream - no new rules needed.
#### How the firewall itself resolves
| | |
| --- | --- |
| `system/dnsserver` | **empty** - nothing is baked in |
| `dnsallowoverride` | `1` - the WAN lease supplies the upstream |
| `dnslocalhost` | `1` - the firewall asks its own resolver first |
| Unbound | enabled, **forwarding mode**, `local_zone_type: transparent` |
The firewall resolves through Unbound, so you can define **local records** and have them answered
authoritatively; anything Unbound can't answer is forwarded to whatever the WAN lease handed over.
Forwarding mode is what makes that lease matter - left recursing, Unbound would query the root
servers directly and the upstream your network expects would never be consulted.
**Nothing is read from the machine that generates the config.** A resolver that host happens to use
is a fact about that host, not about the network the appliance lands on, so seeding it would bake a
site-specific address into every deployment. Override with `-UpstreamDNSServerList` if you want
specific upstreams in the alias.
### Reaching the lab from the host
**The LAN switch type decides this, and the shipped default makes it a non-issue.** Two topologies
Toolkit/Functions/New-OPNSenseConfigurationDocument.ps1
+97 -30
View File
@@ -34,8 +34,10 @@ Function New-OPNSenseConfigurationDocument
.PARAMETER WANInterfaceName
The description that is assigned to the wide area network interface.
.PARAMETER DNSServerList
One or more upstream name server addresses.
.PARAMETER UpstreamDNSServerAddressList
The addresses that populate the "AUTHORIZED_DNS_SERVERS_UPSTREAM" alias, which an authorised internal name server is permitted to forward towards.
These are not written into the system section of the appliance. The appliance resolves through the resolver that it runs itself and takes its own upstream name server addresses from the wide area network lease, so this list describes what an internal resolver is allowed to forward towards rather than what the appliance is configured to use.
.PARAMETER TimeZone
The time zone of the appliance.
@@ -62,16 +64,16 @@ Function New-OPNSenseConfigurationDocument
Do not emit any preboot execution environment option.
.PARAMETER DNSServerAddressList
The addresses that populate the "DNS_SERVERS_001" alias. When this parameter is not specified, the address of the firewall on every planned network is used, because that is the resolver that each network is handed.
The addresses that populate the "AUTHORIZED_DNS_SERVERS_INTERNAL" alias. When this parameter is not specified, the address of the firewall on every planned network is used, because the appliance is the resolver that each network is handed. Add the address of an internal name server of your own to authorise it.
.PARAMETER BastionServerAddressList
The addresses that populate the "BASTION_SERVERS_001" alias. When this parameter is not specified, the address of the firewall on the management network is used as a placeholder.
.PARAMETER DNSTCPPortList
The ports that populate the "DNS_PORTS_TCP_001" alias.
The ports that populate the "AUTHORIZED_DNS_PORTS_TCP" alias.
.PARAMETER DNSUDPPortList
The ports that populate the "DNS_PORTS_UDP_001" alias.
The ports that populate the "AUTHORIZED_DNS_PORTS_UDP" alias.
.PARAMETER BastionPortList
The ports that populate the "BASTION_PORTS_001" alias.
@@ -99,7 +101,7 @@ Function New-OPNSenseConfigurationDocument
$NewOPNSenseConfigurationDocumentParameters.NetworkPlan = $NewOPNSenseNetworkPlanResult
$NewOPNSenseConfigurationDocumentParameters.HostName = 'vFW-HQ-00001'
$NewOPNSenseConfigurationDocumentParameters.DomainName = 'lab.prv'
$NewOPNSenseConfigurationDocumentParameters.DNSServerList = @('192.168.1.1')
$NewOPNSenseConfigurationDocumentParameters.UpstreamDNSServerAddressList = @('192.168.1.1')
$NewOPNSenseConfigurationDocumentParameters.Verbose = $True
$ConfigurationDocument = New-OPNSenseConfigurationDocument @NewOPNSenseConfigurationDocumentParameters
@@ -144,8 +146,8 @@ Function New-OPNSenseConfigurationDocument
[Parameter(Mandatory=$False)]
[AllowEmptyCollection()]
[AllowNull()]
[Alias('DSL')]
[System.String[]]$DNSServerList,
[Alias('UDSAL')]
[System.String[]]$UpstreamDNSServerAddressList,
[Parameter(Mandatory=$False)]
[ValidateNotNullOrEmpty()]
@@ -492,6 +494,20 @@ Function New-OPNSenseConfigurationDocument
[System.String[]]$BastionPortList = @('22', '80', '443', '3389', '5985', '5986')
}
{($Null -ieq $UpstreamDNSServerAddressList) -or ($UpstreamDNSServerAddressList.Count -eq 0)}
{
# Public resolvers, deliberately, rather than anything read from the machine that generated the document.
# A name server that the generating machine happens to use is a fact about that machine and not about the
# network the appliance ends up on, and seeding it here would quietly bake a site specific address into
# every deployment.
$DefaultUpstreamDNSServerAddressList = New-Object -TypeName 'System.Collections.Generic.List[System.String]'
$DefaultUpstreamDNSServerAddressList.Add('1.1.1.1')
$DefaultUpstreamDNSServerAddressList.Add('1.0.0.1')
[System.String[]]$UpstreamDNSServerAddressList = $DefaultUpstreamDNSServerAddressList.ToArray()
}
{($Null -ieq $DNSServerAddressList) -or ($DNSServerAddressList.Count -eq 0)}
{
# Every network resolves through the address of the firewall on its own network, so every one of those
@@ -670,7 +686,7 @@ Function New-OPNSenseConfigurationDocument
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'timezone', $TimeZone)
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'timeservers', ($TimeServerList -Join ' '))
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'language', 'en_US')
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'dnsallowoverride', '0')
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'dnsallowoverride', '1')
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'dnslocalhost', '1')
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'prefer_ipv4', '1')
$Null = $SetElementValue.InvokeReturnAsIs($SystemNode, 'usevirtualterminal', '1')
@@ -698,16 +714,18 @@ Function New-OPNSenseConfigurationDocument
$Null = $SetElementValue.InvokeReturnAsIs($BogonsNode, 'interval', 'monthly')
#region Populate the name server address(es)
# No name server address is written here, and that is the point. The appliance resolves through the resolver that it runs itself, which
# is what allows a local record to be defined and to be answered authoritatively for the networks behind it, and the resolver forwards
# towards whatever the wide area network lease hands over. Writing an address here instead would pin the appliance to a name server that
# was true of the machine that generated the document rather than of the network the appliance ends up on.
#
# Two settings carry that. The private override is permitted, so the lease populates the system resolver list at boot, and the local
# host is preferred, so the appliance asks its own resolver first and only what that resolver forwards leaves the appliance.
$Null = $RemoveChildElement.InvokeReturnAsIs($SystemNode, './dnsserver')
[System.Int32]$DNSServerListCount = ($DNSServerList | Measure-Object).Count
For ($DNSServerListIndex = 0; $DNSServerListIndex -lt [System.Math]::Min($DNSServerListCount, 8); $DNSServerListIndex++)
{
$Null = $AddElement.InvokeReturnAsIs($SystemNode, 'dnsserver', $DNSServerList[$DNSServerListIndex])
}
$WriteLogMessage.Invoke(0, @("Upstream Name Server List: $($DNSServerList -Join '; ')"))
$WriteLogMessage.Invoke(0, @("No static name server address was written into the system section. The appliance will resolve through its own resolver and take its upstream name server(s) from the wide area network lease."))
$WriteLogMessage.Invoke(0, @("Authorised Upstream Name Server List: $($UpstreamDNSServerAddressList -Join '; ')"))
#endregion
#region Populate the web interface and secure shell configuration
@@ -927,9 +945,10 @@ Function New-OPNSenseConfigurationDocument
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'RFC1918'; Type = 'network'; Content = @('10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'); Description = 'Every private address range that is defined by RFC 1918.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'CGNAT'; Type = 'network'; Content = @('100.64.0.0/10'); Description = 'The carrier grade network address translation range that is defined by RFC 6598.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'PARENT_NETWORK_001'; Type = 'network'; Content = @($NetworkPlan.ParentNetwork); Description = 'The parent network that every network behind this appliance was subnetted out of.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'DNS_SERVERS_001'; Type = 'host'; Content = $DNSServerAddressList; Description = 'The name servers that internal networks are permitted to resolve against.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'DNS_PORTS_TCP_001'; Type = 'port'; Content = $DNSTCPPortList; Description = 'Every port that carries name resolution traffic over TCP.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'DNS_PORTS_UDP_001'; Type = 'port'; Content = $DNSUDPPortList; Description = 'Every port that carries name resolution traffic over UDP.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'AUTHORIZED_DNS_SERVERS_INTERNAL'; Type = 'host'; Content = $DNSServerAddressList; Description = 'The name servers that internal networks are permitted to resolve against. Add an internal resolver of your own to authorise it.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'AUTHORIZED_DNS_SERVERS_UPSTREAM'; Type = 'host'; Content = $UpstreamDNSServerAddressList; Description = 'The name servers that an authorised internal name server is permitted to forward towards.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'AUTHORIZED_DNS_PORTS_TCP'; Type = 'port'; Content = $DNSTCPPortList; Description = 'Every port that carries name resolution traffic over TCP.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'AUTHORIZED_DNS_PORTS_UDP'; Type = 'port'; Content = $DNSUDPPortList; Description = 'Every port that carries name resolution traffic over UDP.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'BASTION_SERVERS_001'; Type = 'host'; Content = $BastionServerAddressList; Description = 'The administrative jump hosts that may reach every network on the management ports.'}))
$AliasDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Name = 'BASTION_PORTS_001'; Type = 'port'; Content = $BastionPortList; Description = 'The well known management ports that the jump hosts connect over.'}))
@@ -1101,7 +1120,8 @@ Function New-OPNSenseConfigurationDocument
[System.String]$Direction,
[System.String]$ShaperTarget,
[System.String]$Enabled,
[System.String]$DisableReplyTo
[System.String]$DisableReplyTo,
[System.String]$DestinationNot
)
Switch ([System.String]::IsNullOrEmpty($Direction))
@@ -1128,6 +1148,14 @@ Function New-OPNSenseConfigurationDocument
}
}
Switch ([System.String]::IsNullOrEmpty($DestinationNot))
{
{($_ -eq $True)}
{
[System.String]$DestinationNot = '0'
}
}
$RuleDefinitionProperties = New-Object -TypeName 'System.Collections.Specialized.OrderedDictionary'
$RuleDefinitionProperties.Sequence = $Sequence
$RuleDefinitionProperties.Action = $Action
@@ -1141,6 +1169,7 @@ Function New-OPNSenseConfigurationDocument
$RuleDefinitionProperties.ShaperTarget = $ShaperTarget
$RuleDefinitionProperties.Enabled = $Enabled
$RuleDefinitionProperties.DisableReplyTo = $DisableReplyTo
$RuleDefinitionProperties.DestinationNot = $DestinationNot
$RuleDefinitionList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property ($RuleDefinitionProperties)))
}
@@ -1211,23 +1240,47 @@ Function New-OPNSenseConfigurationDocument
#endregion
#region Name resolution
# The transport protocols are handled separately because each one carries a different set of ports. Both the permit and
# the deny are floating, so the policy is four rules rather than four per interface.
# Four rules per transport, and the order of them is the policy. The transports are handled separately because each one carries
# a different set of ports, and every rule is floating, so this is eight rules rather than eight per interface.
#
# 1. An authorised name server may forward towards an authorised upstream name server. This is what lets a resolver answer
# anything it does not already hold. While the internal alias holds only this appliance the rule changes nothing on its own,
# because traffic that the appliance originates is not evaluated by an inbound rule, but it is what makes the alias useful:
# add a real resolver of your own to the internal alias and this rule already permits it to forward.
#
# 2. Any internal network may query an authorised name server.
#
# 3. Any internal network may query this appliance directly. The internal alias holds the address of this appliance on every
# planned network, so this is ordinarily covered by the rule above, but the interface address is not the only address an
# appliance can answer on and this makes the intent explicit rather than incidental.
#
# 4. Everything else is blocked, expressed as a destination that is inverted rather than as a separate deny of all name
# resolution. Inverting the destination states the policy directly, which is that name resolution towards anything other
# than an authorised name server is refused, and it keeps that true as the alias is edited rather than depending upon this
# rule sitting at a later sequence than every permit.
$ResolverProtocolList = New-Object -TypeName 'System.Collections.Generic.List[System.Management.Automation.PSObject]'
$ResolverProtocolList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Protocol = 'TCP'; PortAlias = 'DNS_PORTS_TCP_001'}))
$ResolverProtocolList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Protocol = 'UDP'; PortAlias = 'DNS_PORTS_UDP_001'}))
$ResolverProtocolList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Protocol = 'TCP'; PortAlias = 'AUTHORIZED_DNS_PORTS_TCP'}))
$ResolverProtocolList.Add((New-Object -TypeName 'System.Management.Automation.PSObject' -Property @{Protocol = 'UDP'; PortAlias = 'AUTHORIZED_DNS_PORTS_UDP'}))
[System.Int32]$AllowedResolverSequence = 100
[System.Int32]$UpstreamResolverSequence = 100
[System.Int32]$AuthorizedResolverSequence = 110
[System.Int32]$ApplianceResolverSequence = 120
[System.Int32]$DeniedResolverSequence = 200
ForEach ($ResolverProtocol In $ResolverProtocolList)
{
$Null = $AddRuleDefinition.InvokeReturnAsIs($AllowedResolverSequence, 'pass', $Null, $ResolverProtocol.Protocol, 'RFC1918', 'DNS_SERVERS_001', $ResolverProtocol.PortAlias, "Allow name resolution over $($ResolverProtocol.Protocol) towards an approved name server.")
$Null = $AddRuleDefinition.InvokeReturnAsIs($UpstreamResolverSequence, 'pass', $Null, $ResolverProtocol.Protocol, 'AUTHORIZED_DNS_SERVERS_INTERNAL', 'AUTHORIZED_DNS_SERVERS_UPSTREAM', $ResolverProtocol.PortAlias, "Allow an authorised name server to forward name resolution over $($ResolverProtocol.Protocol) towards an authorised upstream name server.")
$Null = $AddRuleDefinition.InvokeReturnAsIs($DeniedResolverSequence, 'block', $Null, $ResolverProtocol.Protocol, 'any', 'any', $ResolverProtocol.PortAlias, "Block name resolution over $($ResolverProtocol.Protocol) towards any other name server.")
$Null = $AddRuleDefinition.InvokeReturnAsIs($AuthorizedResolverSequence, 'pass', $Null, $ResolverProtocol.Protocol, 'RFC1918', 'AUTHORIZED_DNS_SERVERS_INTERNAL', $ResolverProtocol.PortAlias, "Allow name resolution over $($ResolverProtocol.Protocol) towards an authorised name server.")
[System.Int32]$AllowedResolverSequence = $AllowedResolverSequence + 1
$Null = $AddRuleDefinition.InvokeReturnAsIs($ApplianceResolverSequence, 'pass', $Null, $ResolverProtocol.Protocol, 'RFC1918', '(self)', $ResolverProtocol.PortAlias, "Allow name resolution over $($ResolverProtocol.Protocol) towards the resolver that this appliance runs.")
$Null = $AddRuleDefinition.InvokeReturnAsIs($DeniedResolverSequence, 'block', $Null, $ResolverProtocol.Protocol, 'RFC1918', 'AUTHORIZED_DNS_SERVERS_INTERNAL', $ResolverProtocol.PortAlias, "Block name resolution over $($ResolverProtocol.Protocol) towards any name server that is not authorised.", $Null, $Null, $Null, $Null, '1')
[System.Int32]$UpstreamResolverSequence = $UpstreamResolverSequence + 1
[System.Int32]$AuthorizedResolverSequence = $AuthorizedResolverSequence + 1
[System.Int32]$ApplianceResolverSequence = $ApplianceResolverSequence + 1
[System.Int32]$DeniedResolverSequence = $DeniedResolverSequence + 1
}
#endregion
@@ -1349,7 +1402,7 @@ Function New-OPNSenseConfigurationDocument
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'source_not', '0')
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'source_port', $Null)
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'destination_net', $RuleDefinition.DestinationNetwork)
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'destination_not', '0')
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'destination_not', $RuleDefinition.DestinationNot)
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'destination_port', $RuleDefinition.DestinationPort)
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'disablereplyto', $RuleDefinition.DisableReplyTo)
$Null = $AddElement.InvokeReturnAsIs($RuleNode, 'log', '0')
@@ -1398,6 +1451,20 @@ Function New-OPNSenseConfigurationDocument
$Null = $SetElementValue.InvokeReturnAsIs($UnboundPlusGeneralNode, 'regdhcpstatic', '1')
$Null = $SetElementValue.InvokeReturnAsIs($UnboundPlusGeneralNode, 'regdhcpdomain', $DomainName)
$Null = $SetElementValue.InvokeReturnAsIs($UnboundPlusGeneralNode, 'local_zone_type', 'transparent')
#region Forward towards the upstream name server(s) rather than recursing
# Forwarding is what makes the wide area network lease meaningful. Left to recurse, the resolver would query the root servers
# directly and the upstream name server that the lease supplies would never be consulted, so the appliance would resolve correctly
# but would ignore the upstream that the network it joined is expecting it to use. Forwarding sends everything the resolver cannot
# answer itself to the system name server list, which the lease populates.
#
# A local record is still answered locally, because the local zone is transparent and the resolver answers what it knows before it
# forwards anything.
$UnboundPlusForwardingNode = $GetOrCreateElement.InvokeReturnAsIs($UnboundPlusNode, 'forwarding')
$Null = $SetElementValue.InvokeReturnAsIs($UnboundPlusForwardingNode, 'enabled', '1')
#endregion
#endregion
#region Kea dynamic host configuration protocol
docs/Invoke-OPNSenseVMDeployment.md
+1 -1
View File
@@ -48,7 +48,7 @@ Every stage of the deployment detects the current state before it acts, so the s
| `ConfigurationDiskSizeBytes` | `Int64` | No | CDSB | The size of the virtual hard disk that carries the configuration document. The disk is dynamically expanding, so this is the size that the installer reports rather than the space that is consumed on the host. It is deliberately distinctive rather than minimal, because the operator identifies this disk by its size within the installer, where it appears as "da1" alongside the far larger boot disk. |
| `EnableDynamicMemory` | `Switch` | No | EDM | Enable dynamic memory on the virtual machine. |
| `VirtualMachineRootDirectory` | `IO.DirectoryInfo` | No | VMRD | A valid folder path that overrides the automatic determination of where the virtual machine and its virtual hard disks are stored. |
| `UpstreamDNSServerList` | `String[]` | No | UDSL | One or more upstream name server addresses. When this parameter is not specified, the default gateway of the host is used, followed by every name server address that the host is configured with. |
| `UpstreamDNSServerList` | `String[]` | No | UDSL | The addresses that populate the "AUTHORIZED_DNS_SERVERS_UPSTREAM" alias, which an authorised internal name server is permitted to forward towards. When this parameter is not specified, the public resolver addresses of "1.1.1.1" and "1.0.0.1" are used. These are not written into the system section of the appliance, and nothing is read from this host to populate them. The appliance resolves through the resolver that it runs itself, which is what allows a local record to be defined for it, and it takes its own upstream name server addresses from the wide area network lease. |
| `RootPassword` | `String` | No | RP | The password to assign to the "root" account of the appliance. When this parameter is not specified, the stock appliance password of "opnsense" is retained. |
| `GenerateRootPassword` | `Switch` | No | GRP | Generate a random password for the "root" account instead of retaining the stock appliance password. The generated password is reported within the deployment summary. |
| `DHCPSocketType` | `String` | No | DST | The socket type that the Kea dynamic host configuration protocol service binds with. "raw" is the default. It is what the appliance ships with, and it is the only one of the two that reliably answers a client that holds no address yet, which is precisely the preboot execution environment case. Specify "udp" only when something in the environment requires it. |
docs/New-OPNSenseConfigurationDocument.md
+5 -5
View File
@@ -28,7 +28,7 @@ The following sections are populated.
| `DomainName` | `String` | No | DN | The domain name of the appliance. |
| `WANInterfaceDevice` | `String` | No | WID | The name of the network interface device within the appliance that is attached to the wide area network. |
| `WANInterfaceName` | `String` | No | WIN | The description that is assigned to the wide area network interface. |
| `DNSServerList` | `String[]` | No | DSL | One or more upstream name server addresses. |
| `UpstreamDNSServerAddressList` | `String[]` | No | UDSAL | The addresses that populate the "AUTHORIZED_DNS_SERVERS_UPSTREAM" alias, which an authorised internal name server is permitted to forward towards. These are not written into the system section of the appliance. The appliance resolves through the resolver that it runs itself and takes its own upstream name server addresses from the wide area network lease, so this list describes what an internal resolver is allowed to forward towards rather than what the appliance is configured to use. |
| `TimeZone` | `String` | No | TZ | The time zone of the appliance. |
| `TimeServerList` | `String[]` | No | TSL | One or more network time protocol server names. |
| `RootPasswordHash` | `String` | No | RPH | The blowfish crypt hash that is assigned to the root account. When this parameter is not specified, the stock appliance credentials are retained. |
@@ -37,10 +37,10 @@ The following sections are populated.
| `PXEBootFileNameBIOS` | `String` | No | PBFNB | The boot file that is offered to a legacy basic input output system client. |
| `PXEBootFileNameUEFI` | `String` | No | PBFNU | The boot file that is offered to a unified extensible firmware interface client. |
| `SkipPXEConfiguration` | `Switch` | No | SPC | Do not emit any preboot execution environment option. |
| `DNSServerAddressList` | `String[]` | No | DSAL | The addresses that populate the "DNS_SERVERS_001" alias. When this parameter is not specified, the address of the firewall on every planned network is used, because that is the resolver that each network is handed. |
| `DNSServerAddressList` | `String[]` | No | DSAL | The addresses that populate the "AUTHORIZED_DNS_SERVERS_INTERNAL" alias. When this parameter is not specified, the address of the firewall on every planned network is used, because the appliance is the resolver that each network is handed. Add the address of an internal name server of your own to authorise it. |
| `BastionServerAddressList` | `String[]` | No | BSAL | The addresses that populate the "BASTION_SERVERS_001" alias. When this parameter is not specified, the address of the firewall on the management network is used as a placeholder. |
| `DNSTCPPortList` | `String[]` | No | DTPL | The ports that populate the "DNS_PORTS_TCP_001" alias. |
| `DNSUDPPortList` | `String[]` | No | DUPL | The ports that populate the "DNS_PORTS_UDP_001" alias. |
| `DNSTCPPortList` | `String[]` | No | DTPL | The ports that populate the "AUTHORIZED_DNS_PORTS_TCP" alias. |
| `DNSUDPPortList` | `String[]` | No | DUPL | The ports that populate the "AUTHORIZED_DNS_PORTS_UDP" alias. |
| `BastionPortList` | `String[]` | No | BPL | The ports that populate the "BASTION_PORTS_001" alias. |
| `EnableZoneIsolation` | `Switch` | No | EZI | Do not emit the per interface rule that permits all traffic from a network to any destination. Only the management, jump host, name resolution, and zone pairing rules will then apply, which turns the zones into genuinely isolated segments. |
| `SkipTrafficShaping` | `Switch` | No | STS | |
@@ -65,7 +65,7 @@ $NewOPNSenseConfigurationDocumentParameters = New-Object -TypeName 'System.Colle
$NewOPNSenseConfigurationDocumentParameters.NetworkPlan = $NewOPNSenseNetworkPlanResult
$NewOPNSenseConfigurationDocumentParameters.HostName = 'vFW-HQ-00001'
$NewOPNSenseConfigurationDocumentParameters.DomainName = 'lab.prv'
$NewOPNSenseConfigurationDocumentParameters.DNSServerList = @('192.168.1.1')
$NewOPNSenseConfigurationDocumentParameters.UpstreamDNSServerAddressList = @('1.1.1.1', '1.0.0.1')
$NewOPNSenseConfigurationDocumentParameters.Verbose = $True
$ConfigurationDocument = New-OPNSenseConfigurationDocument @NewOPNSenseConfigurationDocumentParameters