gsadmin/PSOPNSenseAPI

Fork 0

mirror of https://github.com/freedbygrace/PSOPNSenseAPI.git synced 2026-07-26 11:58:18 +00:00

Files

T

GraceSolutions afcb6dbbfa Add port forwarding support, improve XML documentation, and add unit tests

2025-04-14 22:48:53 -04:00

13 KiB

Raw Blame History

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Apply DNS changes
Apply-OPNSenseDNSChanges

# Apply DNS changes without confirmation
Apply-OPNSenseDNSChanges -Force

Common Scenarios

Basic DNS Configuration

# 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

# 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

# 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

# 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.

13 KiB Raw Blame History

DNS Management

Overview

Cmdlets

Get-OPNSenseDNSServer

Examples

Set-OPNSenseDNSServer

Parameters

Examples

Get-OPNSenseDNSOverride

Parameters

Examples

New-OPNSenseDNSOverride

Parameters

Examples

Set-OPNSenseDNSOverride

Parameters

Examples

Remove-OPNSenseDNSOverride

Parameters

Examples

Get-OPNSenseDNSForwarder

Examples

Set-OPNSenseDNSForwarder

Parameters

Examples

Get-OPNSenseDNSForwarding

Parameters

Examples

New-OPNSenseDNSForwarding

Parameters

Examples

Set-OPNSenseDNSForwarding

Parameters

Examples

Remove-OPNSenseDNSForwarding

Parameters

Examples

Apply-OPNSenseDNSChanges

Parameters

Examples

Common Scenarios

Basic DNS Configuration

DNS Overrides for Internal Services

DNS Forwarding for Specific Domains

Managing DNS Overrides

Notes

13 KiB

Raw Blame History