PSOPNSenseAPI/docs/Route-Management.md

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

# 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

# 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

# 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

# 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

# Apply route changes
Apply-OPNSenseRouteChanges

# Apply route changes without confirmation
Apply-OPNSenseRouteChanges -Force

Common Scenarios

Basic Route Configuration

# 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

# 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

# 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

# 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

# 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

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