Summary

It describes how to integrate and deploy pfSense CE in MachPanel Hyper-V environment.

Applies To

Applies to MachPanel build v 8.2.50 and above

Overview

This document outlines the prerequisites and key configuration requirements for deploying pfSense CE in a Hyper-V environment and integrating it with MachPanel. Adhering to these guidelines ensures consistency, scalability, and seamless operation, especially in high-availability (HA) setups.

1. pfSense Deployment on Hyper-V

• Deploy pfSense CE as a virtual machine on Hyper-V hosts by following the official Netgate documentation: 
https://docs.netgate.com/pfsense/en/latest/recipes/virtualize-hyper-v.html
• Ensure that the VM is provisioned with appropriate resources (CPU, RAM, and storage) based on expected workload and tenant usage.

2. Network Interface Configuration

• Configure network interfaces in pfSense as per deployment requirements.
• Maintain consistent interface naming and ordering across all pfSense instances (Primary and HA peers).

Important:
 Consistent interface naming and ordering are critical for proper synchronization between pfSense nodes in high-availability configurations.
Reference Topology.

Below are two pfSense Servers shown side by side as example:

 ​

3. Virtual Switch & Interface Alignment

• Ensure that the Hyper-V virtual switch name matches the corresponding pfSense interface name used for tenant communication.
• Recommended naming convention:
"TENANTS" (ensure correct spelling and consistency across all systems)
  

Important:
 The naming must be identical across:

• Hyper-V Virtual Switches - required for pfSense deployment.
• pfSense Interfaces
 - required for proper mapping and automation via MachPanel.

4. Trunk Configuration

• Configure the "TENANTS" virtual switch on Hyper-V as a trunk port.
• This allows multiple VLANs to pass through, and enables tenant-level network segmentation.

**Sample Commands to configure Trunk - executed on hyper-v host

Steps for PFSense1 Server:
Command 1:
    Get-VMNetworkAdapter -VMName PFSense1 | Select Name, SwitchName, MacAddress
==>  Copy MacAddress (Lets say: 00155D1E0775)
Command 2:
    Get-VMNetworkAdapter -VMName "pfsense1" |
    Where-Object {$_.MacAddress -eq "00155D1E0775"} |
    Set-VMNetworkAdapterVlan -Trunk -NativeVlanId 1 -AllowedVlanIdList "1-4094"

**Repeat steps for PFSense2 Server:
Command 1: 
    Get-VMNetworkAdapter -VMName PFSense2 | Select Name, SwitchName, MacAddress
==> Copy MacAddress (Lets say: 00155D1E0779)
Command 2:
    Get-VMNetworkAdapter -VMName "pfsense2" |
    Where-Object {$_.MacAddress -eq "00155D1E0779"} |
    Set-VMNetworkAdapterVlan -Trunk -NativeVlanId 1 -AllowedVlanIdList "1-4094"

5. REST API Configuration and MachPanel Integration

• Install the pfSense REST API package.
• Generate and securely store the API key, which will be required for MachPanel integration. Reference:
 https://github.com/pfrest/pfSense-pkg-RESTAPI
• Once pfSense servers are set up, configure them in MachPanel as Master and Slave one by one:

Configure Admin Access on HTTP for demo setup:

Configure REST API Settings:

Configure REST API Keys:

Configure MachPanel and Integrate pfSense Server in MachPanel:

Configure Interfaces in MachPanel:

Add Master and Slave pfSense Servers in MachPanel:

​

6. High Availability Considerations

• For HA deployments:
• Apply identical configurations across all pfSense nodes.
• Ensure:

• Interface naming consistency
• Matching virtual switch configurations
• Proper synchronization settings

Failure to maintain consistency may result in sync failures or unpredictable behavior.

High Availability configuration required on Primary/Master PFSense Server:

​