mirror of
https://github.com/freedbygrace/PSOPNSenseAPI.git
synced 2026-07-28 12:49:00 +00:00
Add port forwarding support, improve XML documentation, and add unit tests
This commit is contained in:
GraceSolutions
@@ -0,0 +1,411 @@
|
||||
# DNS Management
|
||||
|
||||
This component provides cmdlets for managing DNS settings on OPNSense firewalls.
|
||||
|
||||
## Overview
|
||||
|
||||
The DNS Management component allows you to configure and manage DNS settings on OPNSense firewalls. It provides cmdlets for configuring DNS servers, DNS forwarders, DNS overrides, and DNS forwarding.
|
||||
|
||||
## Cmdlets
|
||||
|
||||
### Get-OPNSenseDNSServer
|
||||
|
||||
Retrieves DNS server configurations from an OPNSense firewall.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Get DNS server configuration
|
||||
Get-OPNSenseDNSServer
|
||||
```
|
||||
|
||||
### Set-OPNSenseDNSServer
|
||||
|
||||
Updates the DNS server configuration on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Enabled** - Whether the DNS server is enabled.
|
||||
- **ListenIPs** - The IP addresses to listen on.
|
||||
- **Port** - The port to listen on. Default is 53.
|
||||
- **DNSSECEnabled** - Whether DNSSEC is enabled.
|
||||
- **ForwardingEnabled** - Whether DNS forwarding is enabled.
|
||||
- **ForwardingServers** - The DNS servers to forward queries to.
|
||||
- **CacheEnabled** - Whether DNS caching is enabled.
|
||||
- **CacheSize** - The size of the DNS cache in MB.
|
||||
- **PrefetchEnabled** - Whether DNS prefetching is enabled.
|
||||
- **PrefetchDomains** - Whether to prefetch domains.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
- **PassThru** - Returns the updated DNS server configuration.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Enable the DNS server
|
||||
Set-OPNSenseDNSServer -Enabled
|
||||
|
||||
# Configure DNS forwarding
|
||||
Set-OPNSenseDNSServer -ForwardingEnabled -ForwardingServers "8.8.8.8","8.8.4.4"
|
||||
|
||||
# Configure DNS caching
|
||||
Set-OPNSenseDNSServer -CacheEnabled -CacheSize 10 -PrefetchEnabled -PrefetchDomains
|
||||
|
||||
# Configure DNS server with multiple options
|
||||
Set-OPNSenseDNSServer -Enabled -ListenIPs "192.168.1.1" -Port 53 -DNSSECEnabled -ForwardingEnabled -ForwardingServers "1.1.1.1","1.0.0.1" -CacheEnabled -CacheSize 20 -PrefetchEnabled -PassThru
|
||||
```
|
||||
|
||||
### Get-OPNSenseDNSOverride
|
||||
|
||||
Retrieves DNS overrides from an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Host** - Filter overrides by host.
|
||||
- **Domain** - Filter overrides by domain.
|
||||
- **IP** - Filter overrides by IP address.
|
||||
- **Description** - Filter overrides by description.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Get all DNS overrides
|
||||
Get-OPNSenseDNSOverride
|
||||
|
||||
# Get DNS overrides for a specific host
|
||||
Get-OPNSenseDNSOverride -Host "server"
|
||||
|
||||
# Get DNS overrides for a specific domain
|
||||
Get-OPNSenseDNSOverride -Domain "example.com"
|
||||
```
|
||||
|
||||
### New-OPNSenseDNSOverride
|
||||
|
||||
Creates a new DNS override on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Host** - The hostname to override.
|
||||
- **Domain** - The domain to override.
|
||||
- **IP** - The IP address to resolve to.
|
||||
- **Description** - A description for the override.
|
||||
- **Enabled** - Whether the override is enabled. Default is true.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Create a DNS override for a specific host
|
||||
New-OPNSenseDNSOverride -Host "server" -Domain "example.com" -IP "192.168.1.10" -Description "Internal Server"
|
||||
|
||||
# Create a DNS override for a wildcard domain
|
||||
New-OPNSenseDNSOverride -Host "*" -Domain "example.com" -IP "192.168.1.20" -Description "All example.com hosts"
|
||||
|
||||
# Create a DNS override without confirmation
|
||||
New-OPNSenseDNSOverride -Host "printer" -Domain "example.com" -IP "192.168.1.30" -Description "Office Printer" -Force
|
||||
```
|
||||
|
||||
### Set-OPNSenseDNSOverride
|
||||
|
||||
Updates an existing DNS override on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Uuid** - The UUID of the DNS override to update.
|
||||
- **Host** - The hostname to override.
|
||||
- **Domain** - The domain to override.
|
||||
- **IP** - The IP address to resolve to.
|
||||
- **Description** - A description for the override.
|
||||
- **Enabled** - Whether the override is enabled.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
- **PassThru** - Returns the updated DNS override.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Update a DNS override's IP address
|
||||
Set-OPNSenseDNSOverride -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -IP "192.168.1.15"
|
||||
|
||||
# Update a DNS override's description
|
||||
Set-OPNSenseDNSOverride -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Description "Updated Server"
|
||||
|
||||
# Update multiple properties of a DNS override
|
||||
Set-OPNSenseDNSOverride -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Host "newserver" -Domain "example.com" -IP "192.168.1.20" -Description "New Server" -PassThru
|
||||
```
|
||||
|
||||
### Remove-OPNSenseDNSOverride
|
||||
|
||||
Removes a DNS override from an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Uuid** - The UUID of the DNS override to remove.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Remove a DNS override
|
||||
Remove-OPNSenseDNSOverride -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
|
||||
|
||||
# Remove a DNS override without confirmation
|
||||
Remove-OPNSenseDNSOverride -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Force
|
||||
```
|
||||
|
||||
### Get-OPNSenseDNSForwarder
|
||||
|
||||
Retrieves DNS forwarder configurations from an OPNSense firewall.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Get DNS forwarder configuration
|
||||
Get-OPNSenseDNSForwarder
|
||||
```
|
||||
|
||||
### Set-OPNSenseDNSForwarder
|
||||
|
||||
Updates the DNS forwarder configuration on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Enabled** - Whether the DNS forwarder is enabled.
|
||||
- **ListenIPs** - The IP addresses to listen on.
|
||||
- **Port** - The port to listen on. Default is 53.
|
||||
- **Interfaces** - The interfaces to listen on.
|
||||
- **DNSSECEnabled** - Whether DNSSEC is enabled.
|
||||
- **RegdhcpStatic** - Whether to register DHCP static mappings.
|
||||
- **RegdhcpDynamic** - Whether to register DHCP leases.
|
||||
- **StrictBind** - Whether to use strict binding.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
- **PassThru** - Returns the updated DNS forwarder configuration.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Enable the DNS forwarder
|
||||
Set-OPNSenseDNSForwarder -Enabled
|
||||
|
||||
# Configure DNS forwarder interfaces
|
||||
Set-OPNSenseDNSForwarder -Interfaces "lan","opt1"
|
||||
|
||||
# Configure DNS forwarder with DHCP registration
|
||||
Set-OPNSenseDNSForwarder -RegdhcpStatic -RegdhcpDynamic
|
||||
|
||||
# Configure DNS forwarder with multiple options
|
||||
Set-OPNSenseDNSForwarder -Enabled -ListenIPs "192.168.1.1" -Port 53 -Interfaces "lan","opt1" -DNSSECEnabled -RegdhcpStatic -RegdhcpDynamic -StrictBind -PassThru
|
||||
```
|
||||
|
||||
### Get-OPNSenseDNSForwarding
|
||||
|
||||
Retrieves DNS forwarding configurations from an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Domain** - Filter forwarding by domain.
|
||||
- **Server** - Filter forwarding by server.
|
||||
- **Description** - Filter forwarding by description.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Get all DNS forwarding configurations
|
||||
Get-OPNSenseDNSForwarding
|
||||
|
||||
# Get DNS forwarding for a specific domain
|
||||
Get-OPNSenseDNSForwarding -Domain "example.com"
|
||||
```
|
||||
|
||||
### New-OPNSenseDNSForwarding
|
||||
|
||||
Creates a new DNS forwarding configuration on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Domain** - The domain to forward.
|
||||
- **Server** - The server to forward to.
|
||||
- **Description** - A description for the forwarding.
|
||||
- **Enabled** - Whether the forwarding is enabled. Default is true.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Create a DNS forwarding for a specific domain
|
||||
New-OPNSenseDNSForwarding -Domain "example.com" -Server "192.168.1.10" -Description "Internal DNS"
|
||||
|
||||
# Create a DNS forwarding for a domain to multiple servers
|
||||
New-OPNSenseDNSForwarding -Domain "example.org" -Server "192.168.1.10,192.168.1.11" -Description "Redundant DNS"
|
||||
|
||||
# Create a DNS forwarding without confirmation
|
||||
New-OPNSenseDNSForwarding -Domain "example.net" -Server "192.168.1.12" -Description "External DNS" -Force
|
||||
```
|
||||
|
||||
### Set-OPNSenseDNSForwarding
|
||||
|
||||
Updates an existing DNS forwarding configuration on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Uuid** - The UUID of the DNS forwarding to update.
|
||||
- **Domain** - The domain to forward.
|
||||
- **Server** - The server to forward to.
|
||||
- **Description** - A description for the forwarding.
|
||||
- **Enabled** - Whether the forwarding is enabled.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
- **PassThru** - Returns the updated DNS forwarding.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Update a DNS forwarding's server
|
||||
Set-OPNSenseDNSForwarding -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Server "192.168.1.15"
|
||||
|
||||
# Update a DNS forwarding's description
|
||||
Set-OPNSenseDNSForwarding -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Description "Updated DNS"
|
||||
|
||||
# Update multiple properties of a DNS forwarding
|
||||
Set-OPNSenseDNSForwarding -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Domain "new.example.com" -Server "192.168.1.20" -Description "New DNS" -PassThru
|
||||
```
|
||||
|
||||
### Remove-OPNSenseDNSForwarding
|
||||
|
||||
Removes a DNS forwarding configuration from an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Uuid** - The UUID of the DNS forwarding to remove.
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Remove a DNS forwarding
|
||||
Remove-OPNSenseDNSForwarding -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
|
||||
|
||||
# Remove a DNS forwarding without confirmation
|
||||
Remove-OPNSenseDNSForwarding -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Force
|
||||
```
|
||||
|
||||
### Apply-OPNSenseDNSChanges
|
||||
|
||||
Applies pending DNS changes on an OPNSense firewall.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **Force** - Suppresses the confirmation prompt.
|
||||
|
||||
#### Examples
|
||||
|
||||
```powershell
|
||||
# Apply DNS changes
|
||||
Apply-OPNSenseDNSChanges
|
||||
|
||||
# Apply DNS changes without confirmation
|
||||
Apply-OPNSenseDNSChanges -Force
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Basic DNS Configuration
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Configure the DNS server
|
||||
Set-OPNSenseDNSServer -Enabled -ListenIPs "192.168.1.1" -ForwardingEnabled -ForwardingServers "1.1.1.1","1.0.0.1" -CacheEnabled -CacheSize 10 -Force
|
||||
|
||||
# Apply the changes
|
||||
Apply-OPNSenseDNSChanges -Force
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
### DNS Overrides for Internal Services
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Create DNS overrides for internal services
|
||||
$dnsOverrides = @(
|
||||
@{ Host = "www"; Domain = "example.com"; IP = "192.168.1.10"; Description = "Internal Web Server" },
|
||||
@{ Host = "mail"; Domain = "example.com"; IP = "192.168.1.11"; Description = "Internal Mail Server" },
|
||||
@{ Host = "files"; Domain = "example.com"; IP = "192.168.1.12"; Description = "Internal File Server" },
|
||||
@{ Host = "*"; Domain = "internal.example.com"; IP = "192.168.1.13"; Description = "Internal Services" }
|
||||
)
|
||||
|
||||
foreach ($override in $dnsOverrides) {
|
||||
New-OPNSenseDNSOverride -Host $override.Host -Domain $override.Domain -IP $override.IP -Description $override.Description -Force
|
||||
}
|
||||
|
||||
# Apply the changes
|
||||
Apply-OPNSenseDNSChanges -Force
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
### DNS Forwarding for Specific Domains
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Configure DNS forwarding for specific domains
|
||||
$dnsForwarding = @(
|
||||
@{ Domain = "example.com"; Server = "192.168.1.10"; Description = "Internal Domain" },
|
||||
@{ Domain = "partner.com"; Server = "10.0.0.10"; Description = "Partner Domain" },
|
||||
@{ Domain = "vendor.com"; Server = "172.16.0.10"; Description = "Vendor Domain" }
|
||||
)
|
||||
|
||||
foreach ($forwarding in $dnsForwarding) {
|
||||
New-OPNSenseDNSForwarding -Domain $forwarding.Domain -Server $forwarding.Server -Description $forwarding.Description -Force
|
||||
}
|
||||
|
||||
# Apply the changes
|
||||
Apply-OPNSenseDNSChanges -Force
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
### Managing DNS Overrides
|
||||
|
||||
```powershell
|
||||
# Connect to the OPNSense firewall
|
||||
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
|
||||
|
||||
# Get all DNS overrides
|
||||
$overrides = Get-OPNSenseDNSOverride
|
||||
|
||||
# Update all overrides for a specific domain
|
||||
$overrides | Where-Object { $_.Domain -eq "example.com" } | ForEach-Object {
|
||||
Set-OPNSenseDNSOverride -Uuid $_.Uuid -IP "192.168.2.$($_.IP.Split('.')[-1])" -Description "$($_.Description) (Migrated)" -Force
|
||||
Write-Output "Updated override: $($_.Host).$($_.Domain)"
|
||||
}
|
||||
|
||||
# Remove all overrides with "Temporary" in the description
|
||||
$overrides | Where-Object { $_.Description -like "*Temporary*" } | ForEach-Object {
|
||||
Remove-OPNSenseDNSOverride -Uuid $_.Uuid -Force
|
||||
Write-Output "Removed override: $($_.Host).$($_.Domain)"
|
||||
}
|
||||
|
||||
# Apply the changes
|
||||
Apply-OPNSenseDNSChanges -Force
|
||||
|
||||
# Disconnect from the firewall
|
||||
Disconnect-OPNSense
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- DNS changes are not applied until you call `Apply-OPNSenseDNSChanges`.
|
||||
- DNS overrides take precedence over DNS forwarding.
|
||||
- When using DNS forwarding, ensure that the forwarded domains are accessible from the OPNSense firewall.
|
||||
- DNS caching can improve performance by reducing the number of external DNS queries.
|
||||
- DNSSEC provides additional security by validating DNS responses.
|
||||
- Consider using the `-PassThru` parameter when updating DNS configurations to verify the changes.
|
||||
- Wildcard DNS overrides (using "*" as the host) can be used to override all subdomains of a domain.
|
||||
- DNS forwarding can be used to direct queries for specific domains to internal or external DNS servers.
|
||||
Reference in New Issue
Block a user