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

2026-07-26 11:58:18 +00:00 · 2025-04-14 22:48:53 -04:00
commit afcb6dbbfa
203 changed files with 30165 additions and 0 deletions
@@ -0,0 +1,291 @@
+# Route Management
+
+This component provides cmdlets for managing static routes on OPNSense firewalls.
+
+## Overview
+
+The Route Management component allows you to configure and manage static routes on OPNSense firewalls. It provides cmdlets for creating, viewing, modifying, and deleting static routes.
+
+## Cmdlets
+
+### Get-OPNSenseRoute
+
+Retrieves static routes from an OPNSense firewall.
+
+#### Parameters
+
+- **Uuid** - The UUID of a specific route to retrieve. If not specified, all routes are returned.
+- **Network** - Filter routes by network.
+- **Gateway** - Filter routes by gateway.
+- **Description** - Filter routes by description.
+
+#### Examples
+
+```powershell
+# Get all static routes
+Get-OPNSenseRoute
+
+# Get a specific route by UUID
+Get-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
+
+# Get routes for a specific network
+Get-OPNSenseRoute -Network "192.168.100.0/24"
+
+# Get routes using a specific gateway
+Get-OPNSenseRoute -Gateway "WAN_GATEWAY"
+```
+
+### New-OPNSenseRoute
+
+Creates a new static route on an OPNSense firewall.
+
+#### Parameters
+
+- **Network** - The network for the route in CIDR notation.
+- **Gateway** - The gateway for the route.
+- **Description** - A description for the route.
+- **Disabled** - Whether the route is disabled. Default is false.
+- **Force** - Suppresses the confirmation prompt.
+
+#### Examples
+
+```powershell
+# Create a basic static route
+New-OPNSenseRoute -Network "192.168.100.0/24" -Gateway "WAN_GATEWAY" -Description "Remote Office Network"
+
+# Create a disabled static route
+New-OPNSenseRoute -Network "10.0.0.0/8" -Gateway "WAN2_GATEWAY" -Description "Corporate Network" -Disabled
+
+# Create a static route without confirmation
+New-OPNSenseRoute -Network "172.16.0.0/16" -Gateway "WAN3_GATEWAY" -Description "Partner Network" -Force
+```
+
+### Set-OPNSenseRoute
+
+Updates an existing static route on an OPNSense firewall.
+
+#### Parameters
+
+- **Uuid** - The UUID of the route to update.
+- **Network** - The network for the route in CIDR notation.
+- **Gateway** - The gateway for the route.
+- **Description** - A description for the route.
+- **Disabled** - Whether the route is disabled.
+- **Force** - Suppresses the confirmation prompt.
+- **PassThru** - Returns the updated route.
+
+#### Examples
+
+```powershell
+# Update a route's network
+Set-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Network "192.168.200.0/24"
+
+# Update a route's gateway
+Set-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Gateway "WAN2_GATEWAY"
+
+# Update a route's description
+Set-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Description "Updated Remote Office Network"
+
+# Enable a disabled route
+Set-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Disabled:$false
+
+# Update multiple properties of a route
+Set-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Network "192.168.200.0/24" -Gateway "WAN3_GATEWAY" -Description "Updated Remote Office Network" -PassThru
+```
+
+### Remove-OPNSenseRoute
+
+Removes a static route from an OPNSense firewall.
+
+#### Parameters
+
+- **Uuid** - The UUID of the route to remove.
+- **Force** - Suppresses the confirmation prompt.
+
+#### Examples
+
+```powershell
+# Remove a route
+Remove-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
+
+# Remove a route without confirmation
+Remove-OPNSenseRoute -Uuid "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" -Force
+```
+
+### Apply-OPNSenseRouteChanges
+
+Applies pending route changes on an OPNSense firewall.
+
+#### Parameters
+
+- **Force** - Suppresses the confirmation prompt.
+
+#### Examples
+
+```powershell
+# Apply route changes
+Apply-OPNSenseRouteChanges
+
+# Apply route changes without confirmation
+Apply-OPNSenseRouteChanges -Force
+```
+
+## Common Scenarios
+
+### Basic Route Configuration
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+
+# Create a static route to a remote network
+New-OPNSenseRoute -Network "192.168.100.0/24" -Gateway "WAN_GATEWAY" -Description "Remote Office Network" -Force
+
+# Apply the changes
+Apply-OPNSenseRouteChanges -Force
+
+# Disconnect from the firewall
+Disconnect-OPNSense
+```
+
+### Managing Multiple Routes
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+
+# Define routes for different networks
+$routes = @(
+    @{ Network = "192.168.100.0/24"; Gateway = "WAN_GATEWAY"; Description = "Remote Office 1" },
+    @{ Network = "192.168.200.0/24"; Gateway = "WAN_GATEWAY"; Description = "Remote Office 2" },
+    @{ Network = "10.0.0.0/8"; Gateway = "WAN2_GATEWAY"; Description = "Corporate Network" },
+    @{ Network = "172.16.0.0/16"; Gateway = "WAN3_GATEWAY"; Description = "Partner Network" }
+)
+
+# Create routes
+foreach ($route in $routes) {
+    New-OPNSenseRoute -Network $route.Network -Gateway $route.Gateway -Description $route.Description -Force
+}
+
+# Apply the changes
+Apply-OPNSenseRouteChanges -Force
+
+# Disconnect from the firewall
+Disconnect-OPNSense
+```
+
+### Updating Routes for a Gateway Change
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+
+# Get all routes using a specific gateway
+$routes = Get-OPNSenseRoute -Gateway "WAN_GATEWAY"
+
+# Update routes to use a different gateway
+foreach ($route in $routes) {
+    Set-OPNSenseRoute -Uuid $route.Uuid -Gateway "WAN2_GATEWAY" -Description "$($route.Description) (Updated)" -Force
+    Write-Output "Updated route for network $($route.Network) to use gateway WAN2_GATEWAY"
+}
+
+# Apply the changes
+Apply-OPNSenseRouteChanges -Force
+
+# Disconnect from the firewall
+Disconnect-OPNSense
+```
+
+### Temporarily Disabling Routes
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+
+# Get all routes
+$routes = Get-OPNSenseRoute
+
+# Disable routes for a specific network range
+foreach ($route in $routes) {
+    if ($route.Network -like "10.*") {
+        Set-OPNSenseRoute -Uuid $route.Uuid -Disabled:$true -Force
+        Write-Output "Disabled route for network $($route.Network)"
+    }
+}
+
+# Apply the changes
+Apply-OPNSenseRouteChanges -Force
+
+# Disconnect from the firewall
+Disconnect-OPNSense
+```
+
+### Route Cleanup
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+
+# Get all routes
+$routes = Get-OPNSenseRoute
+
+# Remove routes with "Temporary" in the description
+foreach ($route in $routes) {
+    if ($route.Description -like "*Temporary*") {
+        Remove-OPNSenseRoute -Uuid $route.Uuid -Force
+        Write-Output "Removed route for network $($route.Network) with description '$($route.Description)'"
+    }
+}
+
+# Apply the changes
+Apply-OPNSenseRouteChanges -Force
+
+# Disconnect from the firewall
+Disconnect-OPNSense
+```
+
+### Creating Routes from Network Calculations
+
+```powershell
+# Connect to the OPNSense firewall
+Connect-OPNSense -Server "https://firewall.example.com" -ApiKey "your_api_key" -ApiSecret "your_api_secret" -SkipCertificateCheck
+
+# Calculate subnets
+$network = "10.0.0.0/16"
+$prefixLength = 24
+$subnets = Invoke-OPNSenseNetworkCalculation -Network $network -Operation Subnet -PrefixLength $prefixLength
+
+# Create routes for each subnet
+foreach ($subnet in $subnets) {
+    # Determine the gateway based on the subnet
+    $gateway = if ($subnet.CIDR -like "10.0.1*") {
+        "WAN_GATEWAY"
+    } elseif ($subnet.CIDR -like "10.0.2*") {
+        "WAN2_GATEWAY"
+    } else {
+        "WAN3_GATEWAY"
+    }
+    
+    New-OPNSenseRoute -Network $subnet.CIDR -Gateway $gateway -Description "Subnet $($subnet.CIDR)" -Force
+    Write-Output "Created route for network $($subnet.CIDR) via gateway $gateway"
+}
+
+# Apply the changes
+Apply-OPNSenseRouteChanges -Force
+
+# Disconnect from the firewall
+Disconnect-OPNSense
+```
+
+## Notes
+
+- Route changes are not applied until you call `Apply-OPNSenseRouteChanges`.
+- When creating a route, ensure that the gateway is properly configured and reachable.
+- Static routes take precedence over dynamic routes.
+- The network should be specified in CIDR notation (e.g., "192.168.1.0/24").
+- Routes can be temporarily disabled without removing them.
+- Consider using the `-PassThru` parameter when updating routes to verify the changes.
+- Route descriptions should be descriptive and follow a consistent naming convention.
+- When managing multiple routes, consider using a CSV file or other structured data source to maintain the route information.
+- Static routes are useful for directing traffic to specific networks through different gateways.
+- For complex routing scenarios, consider using policy-based routing instead of static routes.