PSOPNSenseAPI/docs/examples/Port-Forwarding-README.md

Port Forwarding Examples

This document provides examples of using the PSOPNSenseAPI module to manage port forwarding rules on OPNSense firewalls.

Basic Port Forwarding

The following example demonstrates how to create, view, update, and delete port forwarding rules:

# Import the module
Import-Module PSOPNSenseAPI

# Connect to the OPNSense firewall
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck

# Get all port forwarding rules
$rules = Get-OPNSensePortForwardingRule
Write-Output "Current port forwarding rules:"
$rules | Format-Table -Property Uuid, Description, Interface, Protocol, DestinationPort, TargetIP, TargetPort

# Create a new port forwarding rule for HTTP
$httpRule = New-OPNSensePortForwardingRule -Interface "WAN" -Protocol "tcp" -DestinationPort "80" -TargetIP "192.168.1.100" -TargetPort "80" -Description "Web Server HTTP"
Write-Output "Created HTTP port forwarding rule:"
$httpRule | Format-Table -Property Uuid, Description, Interface, Protocol, DestinationPort, TargetIP, TargetPort

# Create a new port forwarding rule for HTTPS
$httpsRule = New-OPNSensePortForwardingRule -Interface "WAN" -Protocol "tcp" -DestinationPort "443" -TargetIP "192.168.1.100" -TargetPort "443" -Description "Web Server HTTPS"
Write-Output "Created HTTPS port forwarding rule:"
$httpsRule | Format-Table -Property Uuid, Description, Interface, Protocol, DestinationPort, TargetIP, TargetPort

# Update the HTTP rule to point to a different server
$updatedRule = Set-OPNSensePortForwardingRule -Uuid $httpRule.Uuid -TargetIP "192.168.1.200" -Description "Updated Web Server HTTP" -PassThru
Write-Output "Updated HTTP port forwarding rule:"
$updatedRule | Format-Table -Property Uuid, Description, Interface, Protocol, DestinationPort, TargetIP, TargetPort

# Get a specific rule by UUID
$rule = Get-OPNSensePortForwardingRule -Uuid $httpsRule.Uuid
Write-Output "Retrieved HTTPS port forwarding rule:"
$rule | Format-Table -Property Uuid, Description, Interface, Protocol, DestinationPort, TargetIP, TargetPort

# Remove the HTTP rule
Remove-OPNSensePortForwardingRule -Uuid $httpRule.Uuid -Force
Write-Output "Removed HTTP port forwarding rule"

# Get all port forwarding rules again to verify changes
$rules = Get-OPNSensePortForwardingRule
Write-Output "Updated port forwarding rules:"
$rules | Format-Table -Property Uuid, Description, Interface, Protocol, DestinationPort, TargetIP, TargetPort

# Disconnect from the firewall
Disconnect-OPNSense

Advanced Port Forwarding Scenarios

Web Server with Multiple Services

This example shows how to set up port forwarding for a web server with multiple services:

# Connect to the OPNSense firewall
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck

# Define the web server details
$webServerIP = "192.168.1.100"
$services = @(
    @{ Name = "HTTP"; Protocol = "tcp"; ExternalPort = "80"; InternalPort = "80" },
    @{ Name = "HTTPS"; Protocol = "tcp"; ExternalPort = "443"; InternalPort = "443" },
    @{ Name = "Alternative HTTP"; Protocol = "tcp"; ExternalPort = "8080"; InternalPort = "8080" },
    @{ Name = "WebSocket"; Protocol = "tcp"; ExternalPort = "9000"; InternalPort = "9000" }
)

# Create port forwarding rules for each service
foreach ($service in $services) {
    New-OPNSensePortForwardingRule -Interface "WAN" `
        -Protocol $service.Protocol `
        -DestinationPort $service.ExternalPort `
        -TargetIP $webServerIP `
        -TargetPort $service.InternalPort `
        -Description "Web Server - $($service.Name)" `
        -Force
}

# Verify the rules were created
Get-OPNSensePortForwardingRule | Where-Object { $_.TargetIP -eq $webServerIP } | 
    Format-Table -Property Description, Protocol, DestinationPort, TargetPort

# Disconnect from the firewall
Disconnect-OPNSense

Game Server Port Forwarding

This example demonstrates how to set up port forwarding for a game server with multiple ports:

# Connect to the OPNSense firewall
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck

# Define the game server details
$gameServerIP = "192.168.1.150"
$gameServerPorts = @(
    @{ Name = "Game Server - Main"; Protocol = "tcp/udp"; Ports = "27015" },
    @{ Name = "Game Server - Query"; Protocol = "udp"; Ports = "27016" },
    @{ Name = "Game Server - RCON"; Protocol = "tcp"; Ports = "27017" },
    @{ Name = "Game Server - Voice"; Protocol = "udp"; Ports = "9987-9989" }
)

# Create port forwarding rules for the game server
foreach ($port in $gameServerPorts) {
    New-OPNSensePortForwardingRule -Interface "WAN" `
        -Protocol $port.Protocol `
        -DestinationPort $port.Ports `
        -TargetIP $gameServerIP `
        -TargetPort $port.Ports `
        -Description $port.Name `
        -Force
}

# Verify the rules were created
Get-OPNSensePortForwardingRule | Where-Object { $_.TargetIP -eq $gameServerIP } | 
    Format-Table -Property Description, Protocol, DestinationPort, TargetPort

# Disconnect from the firewall
Disconnect-OPNSense

Remote Access Services

This example shows how to set up port forwarding for remote access services:

# Connect to the OPNSense firewall
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck

# Define remote access services
$remoteServices = @(
    @{ Name = "RDP - Admin Server"; TargetIP = "192.168.1.200"; ExternalPort = "33389"; InternalPort = "3389"; Protocol = "tcp" },
    @{ Name = "SSH - Dev Server"; TargetIP = "192.168.1.201"; ExternalPort = "2222"; InternalPort = "22"; Protocol = "tcp" },
    @{ Name = "VNC - Support"; TargetIP = "192.168.1.202"; ExternalPort = "5900"; InternalPort = "5900"; Protocol = "tcp" }
)

# Create port forwarding rules for remote access
foreach ($service in $remoteServices) {
    New-OPNSensePortForwardingRule -Interface "WAN" `
        -Protocol $service.Protocol `
        -DestinationPort $service.ExternalPort `
        -TargetIP $service.TargetIP `
        -TargetPort $service.InternalPort `
        -Description $service.Name `
        -Log `  # Enable logging for security
        -Force
}

# Verify the rules were created
Get-OPNSensePortForwardingRule | Where-Object { $_.Description -like "* - *" } | 
    Format-Table -Property Description, Protocol, DestinationPort, TargetIP, TargetPort

# Disconnect from the firewall
Disconnect-OPNSense

Bulk Management of Port Forwarding Rules

This example demonstrates how to perform bulk operations on port forwarding rules:

# Connect to the OPNSense firewall
Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck

# Get all port forwarding rules
$rules = Get-OPNSensePortForwardingRule

# Disable all rules with "Temporary" in the description
$rules | Where-Object { $_.Description -like "*Temporary*" } | ForEach-Object {
    Set-OPNSensePortForwardingRule -Uuid $_.Uuid -Enabled:$false -Force
    Write-Output "Disabled rule: $($_.Description)"
}

# Update all rules pointing to a decommissioned server
$oldServerIP = "192.168.1.100"
$newServerIP = "192.168.1.150"

$rules | Where-Object { $_.TargetIP -eq $oldServerIP } | ForEach-Object {
    Set-OPNSensePortForwardingRule -Uuid $_.Uuid -TargetIP $newServerIP -Description "$($_.Description) (Migrated)" -Force
    Write-Output "Updated rule: $($_.Description) to point to $newServerIP"
}

# Delete all rules with "Obsolete" in the description
$rules | Where-Object { $_.Description -like "*Obsolete*" } | ForEach-Object {
    Remove-OPNSensePortForwardingRule -Uuid $_.Uuid -Force
    Write-Output "Removed rule: $($_.Description)"
}

# Verify changes
$updatedRules = Get-OPNSensePortForwardingRule
Write-Output "Rules after bulk operations:"
$updatedRules | Format-Table -Property Uuid, Description, Enabled, TargetIP, DestinationPort, TargetPort

# Disconnect from the firewall
Disconnect-OPNSense

Notes

• Port forwarding rules are applied immediately after creation, update, or deletion.
• When creating or updating rules, consider security implications and only forward necessary ports.
• Use the FilterRuleAssociation parameter to automatically create associated firewall rules.
• NAT reflection allows internal clients to access forwarded services using the external IP address.
• For security-sensitive rules, enable logging with the -Log parameter.
• Always use strong authentication and encryption for remote access services.
• Consider using non-standard external ports for common services to reduce automated scanning attempts.