PSOPNSenseAPI/docs/Network-Utilities.md

Network Utilities

This component provides cmdlets for performing network calculations and conversions.

Overview

The Network Utilities component includes cmdlets for working with IP networks, subnets, CIDR notation, and other network-related calculations. These utilities help with planning and managing network configurations on OPNSense firewalls.

Cmdlets

Invoke-OPNSenseNetworkCalculation

Performs various network calculations on IP networks.

Parameters

• Network - The network in CIDR notation to perform calculations on.
• Operation - The operation to perform. Valid values are:
  • Info - Shows detailed information about the network.
  • Subnet - Divides the network into subnets of a specified prefix length.
  • SubnetByCount - Divides the network into a specified number of subnets.
  • Contains - Checks if an IP address or network is contained within the specified network.
  • Overlaps - Checks if the network overlaps with other networks.
  • Supernet - Combines the network with other networks into a supernet.
  • SupernetSummarize - Summarizes multiple networks into the smallest possible set of networks.
• PrefixLength - The prefix length to use for subnetting.
• SubnetCount - The number of subnets to create when using SubnetByCount.
• IpAddress - The IP address to check when using Contains.
• AdditionalNetworks - Additional networks to use with Overlaps, Supernet, or SupernetSummarize.

Examples

# Show network information
Invoke-OPNSenseNetworkCalculation -Network "192.168.1.0/24" -Operation Info

# Subnet a network into /27 networks
Invoke-OPNSenseNetworkCalculation -Network "10.0.0.0/24" -Operation Subnet -PrefixLength 27

# Create 4 equal-sized subnets
Invoke-OPNSenseNetworkCalculation -Network "172.16.0.0/24" -Operation SubnetByCount -SubnetCount 4

# Check if an IP is within a network
Invoke-OPNSenseNetworkCalculation -Network "192.168.1.0/24" -Operation Contains -IpAddress "192.168.1.100"

# Check if networks overlap
Invoke-OPNSenseNetworkCalculation -Network "10.0.0.0/16" -Operation Overlaps -AdditionalNetworks "10.0.1.0/24","10.0.2.0/24"

# Combine networks into a supernet
Invoke-OPNSenseNetworkCalculation -Network "192.168.0.0/24" -Operation Supernet -AdditionalNetworks "192.168.1.0/24"

# Summarize multiple networks
Invoke-OPNSenseNetworkCalculation -Network "10.0.0.0/24" -Operation SupernetSummarize -AdditionalNetworks "10.0.1.0/24","10.0.2.0/24"

ConvertTo-OPNSenseNetworkNotation

Converts between different network notation formats.

Parameters

• CIDR - The CIDR prefix length to convert to a subnet mask.
• SubnetMask - The subnet mask to convert to a CIDR prefix length.

Examples

# Convert CIDR to subnet mask
ConvertTo-OPNSenseNetworkNotation -CIDR 24  # Returns "255.255.255.0"

# Convert subnet mask to CIDR
ConvertTo-OPNSenseNetworkNotation -SubnetMask "255.255.255.0"  # Returns 24

Common Scenarios

Network Planning

# Plan a network subdivision
$network = "10.0.0.0/16"
$subnets = Invoke-OPNSenseNetworkCalculation -Network $network -Operation Subnet -PrefixLength 24
$subnets | Format-Table -Property CIDR, Network, Broadcast, FirstUsableHost, LastUsableHost, UsableHostCount

# Create equal-sized subnets
$departmentCount = 8
$subnets = Invoke-OPNSenseNetworkCalculation -Network "172.16.0.0/20" -Operation SubnetByCount -SubnetCount $departmentCount
$subnets | Format-Table -Property CIDR, Network, Broadcast, UsableHostCount

Network Verification

# Verify if an IP address is within a network
$serverIP = "192.168.1.50"
$network = "192.168.1.0/24"
$isInNetwork = Invoke-OPNSenseNetworkCalculation -Network $network -Operation Contains -IpAddress $serverIP

# Check if networks overlap
$network1 = "10.0.0.0/16"
$network2 = "10.0.5.0/24"
$overlaps = Invoke-OPNSenseNetworkCalculation -Network $network1 -Operation Overlaps -AdditionalNetworks $network2

Network Optimization

# Optimize a list of networks by summarizing them
$networks = @(
    "192.168.1.0/24",
    "192.168.2.0/24",
    "192.168.3.0/24",
    "192.168.4.0/24"
)
$optimized = Invoke-OPNSenseNetworkCalculation -Network $networks[0] -Operation SupernetSummarize -AdditionalNetworks $networks[1..($networks.Length-1)]
$optimized | Format-Table -Property CIDR, Network, Broadcast

VLAN Planning

# Plan VLANs with appropriate subnet sizes
$corporateNetwork = "10.0.0.0/16"
$vlans = @{
    "Management" = 10
    "Servers" = 20
    "Users" = 30
    "Guest" = 40
    "IoT" = 50
}

foreach ($vlan in $vlans.GetEnumerator()) {
    $vlanName = $vlan.Key
    $vlanId = $vlan.Value
    $prefix = switch ($vlanName) {
        "Management" { 24 }  # 254 hosts
        "Servers" { 23 }     # 510 hosts
        "Users" { 22 }       # 1022 hosts
        "Guest" { 24 }       # 254 hosts
        "IoT" { 23 }         # 510 hosts
    }
    
    # Calculate network details
    $subnet = Invoke-OPNSenseNetworkCalculation -Network $corporateNetwork -Operation Subnet -PrefixLength $prefix | Select-Object -First 1
    
    Write-Output "VLAN $vlanId ($vlanName): $($subnet.CIDR) - $($subnet.UsableHostCount) usable hosts"
}

Notes

• The Network Utilities component uses the IPNetwork2 library for network calculations.
• All operations are performed locally and do not require communication with the OPNSense firewall.
• These utilities can be used for planning network configurations before implementing them on the firewall.
• When working with large networks, be aware that some operations (like subnetting a /8 network into /30 networks) may generate a large number of results.