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.
Physical Layer Requirements
The environment requires four dedicated physical network interfaces to separate WAN, LAN/Management, Replication, and Tenant traffic. The WAN interface connects to the ISP or edge network and carries public IP addressing, while a dedicated LAN/Management interface provides secure administrative access. A separate Replication interface is reserved exclusively for pfSense HA synchronization traffic to ensure reliable failover operations, and a Tenant trunk interface carries all customer VLAN traffic using tagged VLANs that align with the MachPanel-provisioned VLAN configuration.
This design ensures traffic isolation, security, and high availability across the deployment.
|
Link
|
Physical NIC
|
Switch port config
|
Notes
|
|
WAN
|
pNIC1
|
Access port, ISP/edge VLAN, or direct to edge router
|
Carries public IP(s). If you have a /29 or larger block, this is where it lands. No tagging needed unless your ISP hands off tagged.
|
|
LAN/MGMT
|
pNIC2
|
Access port, dedicated management VLAN
|
Used for pfSense WebGUI/SSH, Hyper-V host management (if co-located), and any internal admin traffic. Route this off your production tenant network.
|
|
Replication
|
pNIC3
|
Access port, no gateway, no routing — ideally a dedicated switch or even a direct crossover/DAC between the two Hyper-V hosts running pfSense HA pairs
|
Carries pfSync state table sync, CARP heartbeats, and XMLRPC config sync between the two pfSense nodes. Latency and loss here directly affect failover reliability, so keep it off shared/congested links.
|
|
Tenant trunk
|
pNIC4
|
Trunk port, tagged with every tenant VLAN
|
This is the one link that carries all customer traffic. Needs to match your MachPanel-provisioned VLAN range exactly.
|
1. pfSense Deployment on Hyper-V
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:
