mirror of
https://github.com/freedbygrace/PSOPNSenseAPI.git
synced 2026-07-26 11:58:18 +00:00
GraceSolutions
412 lines
13 KiB
Markdown
412 lines
13 KiB
Markdown
# 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.
|