PSOPNSenseAPI/docs/IPNetwork2-Integration.md

IPNetwork2 Integration

This document provides information about the integration of the IPNetwork2 library in the PSOPNSenseAPI module.

Overview

The PSOPNSenseAPI module uses the IPNetwork2 library for IP network calculations and manipulations. This library provides functionality for working with IP networks, subnets, CIDR notation, and other network-related operations.

IPNetwork2 Library

The IPNetwork2 library is a .NET library that provides classes and methods for working with IP networks. It supports both IPv4 and IPv6 networks and provides functionality for:

• Parsing CIDR notation
• Subnetting
• Supernetting
• Network calculations
• IP address manipulation
• Network containment and overlap checks

Integration in PSOPNSenseAPI

The IPNetwork2 library is integrated into the PSOPNSenseAPI module in the following ways:

1. NetworkUtility Class: The NetworkUtility class in the PSOPNSenseAPI.Utilities namespace provides wrapper methods for the IPNetwork2 functionality.

2. Network Calculation Cmdlets: The Invoke-OPNSenseNetworkCalculation cmdlet exposes the IPNetwork2 functionality to PowerShell users.

3. VLAN and Subnet Management: The New-OPNSenseSubnetVLANs cmdlet uses IPNetwork2 for subnet calculations when creating VLANs from subnet divisions.

Using IPNetwork2 in the Code

When using IPNetwork2 in the code, it's important to use the correct namespace and class name:

using System.Net;

// Parse a CIDR notation string
IPNetwork2 network = IPNetwork2.Parse("192.168.1.0/24");

// Get network properties
IPAddress networkAddress = network.Network;
IPAddress broadcastAddress = network.Broadcast;
int cidrPrefix = network.Cidr;
BigInteger totalHosts = network.Total;

// Subnet a network
IEnumerable<IPNetwork2> subnets = IPNetwork2.Subnet(network, 27);

// Check if an IP address is in a network
bool contains = network.Contains(IPAddress.Parse("192.168.1.100"));

// Check if networks overlap
bool overlaps = network1.Overlap(network2);

// Create a supernet
IPNetwork2[] supernet = IPNetwork2.Supernet(new[] { network1, network2 });

Common Issues and Solutions

Namespace and Class Name

The most common issue when working with IPNetwork2 is using the incorrect namespace or class name. The correct usage is:

using System.Net;

// Use the class name directly
IPNetwork2 network = IPNetwork2.Parse("192.168.1.0/24");

// Or use the fully qualified name for clarity
System.Net.IPNetwork2 network = System.Net.IPNetwork2.Parse("192.168.1.0/24");

Version Compatibility

Ensure that you're using a compatible version of IPNetwork2. The PSOPNSenseAPI module uses version 3.1.764, which is the latest version as of April 2025.

<PackageReference Include="IPNetwork2" Version="3.1.764" />

This version supports .NET 8.0, .NET 9.0, .NET Standard 2.0, and .NET Standard 2.1.

Method Signatures

Be aware of the method signatures when using IPNetwork2. For example, the Subnet method has multiple overloads:

// Subnet by prefix length
IEnumerable<IPNetwork2> Subnet(IPNetwork2 network, int prefixLength);

// Subnet by subnet count
IEnumerable<IPNetwork2> Subnet(IPNetwork2 network, BigInteger subnetCount);

// Subnet by target network
IEnumerable<IPNetwork2> Subnet(IPNetwork2 network, IPNetwork2 targetNetwork);

Memory Usage

When working with large networks (e.g., /8 networks) and small subnets (e.g., /30), be aware that operations like subnetting can generate a large number of results and consume significant memory.

Exposing IPNetwork2 Functionality to PowerShell

The PSOPNSenseAPI module exposes IPNetwork2 functionality to PowerShell users through the Invoke-OPNSenseNetworkCalculation cmdlet:

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

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

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

Advanced Usage

Custom Network Utility Methods

The NetworkUtility class provides additional methods that extend the functionality of IPNetwork2:

// Get the first usable host address in a network
IPAddress firstHost = NetworkUtility.GetFirstUsableHost(network);

// Get the last usable host address in a network
IPAddress lastHost = NetworkUtility.GetLastUsableHost(network);

// Get the number of usable host addresses in a network
BigInteger usableHosts = NetworkUtility.GetUsableHostCount(network);

// Convert between CIDR and subnet mask
int cidr = NetworkUtility.GetCIDRFromSubnetMask("255.255.255.0");
string subnetMask = NetworkUtility.GetSubnetMaskFromCIDR(24);

Network Summarization

The SupernetSummarize method provides advanced network summarization:

// Summarize multiple networks into the smallest possible set
List<IPNetwork2> networks = new List<IPNetwork2>
{
    IPNetwork2.Parse("192.168.1.0/24"),
    IPNetwork2.Parse("192.168.2.0/24"),
    IPNetwork2.Parse("192.168.3.0/24"),
    IPNetwork2.Parse("192.168.4.0/24")
};

List<IPNetwork2> summarized = NetworkUtility.SupernetSummarize(networks);
// Result: 192.168.0.0/22

Notes

• The IPNetwork2 library is a third-party library and is subject to its own licensing terms.
• The PSOPNSenseAPI module includes the IPNetwork2 library as a NuGet package dependency.
• The IPNetwork2 library is used for local network calculations and does not require communication with the OPNSense firewall.
• Version 3.1.764 of IPNetwork2 has moved the IPNetwork2 class to the System.Net namespace, which is different from earlier versions that used the System.Net.IPNetwork namespace.
• When upgrading the IPNetwork2 library, ensure that all code is updated to use the correct namespace and class names.
• Version 3.1.764 supports .NET 8.0, .NET 9.0, .NET Standard 2.0, and .NET Standard 2.1.
• For .NET Standard 2.0 and 2.1, IPNetwork2 has a dependency on System.Memory (>= 4.5.5).