The high-performance, real-time perimeter security, telemetry, and dynamic policy routing platform for Home Assistant.
⚠️ LATEST ARCHITECTURAL REWRITE ANNOUNCEMENTThis project is a complete, ground-up rewrite! We have successfully migrated to a Dynamic Entity Auto-Discovery Engine. The integration now features an optimized XML-RPC non-blocking mutex pipeline, a protective storage smart-cache system, direct browser DOM-injection counters to prevent dashboard freezing, and an instantaneous connection State-Killing matrix.
Bring hyper-fast, live firewall diagnostics, packet drop counters, and active interface throughput tracking directly into Home Assistant.
Engineered for low-overhead edge networks, this platform allows you to execute on-the-fly multi-table alias swaps, manage core daemon service states, and isolate rogue client nodes with instantaneous execution.
The most efficient deployment method is through HACS (Home Assistant Community Store):
- Open HACS in your sidebar and navigate into the Integrations panel.
- Click the three dots (
...) located in the upper right quadrant and select Custom repositories. - Input the repository web link:
https://github.com/DonTranQuiL/pfsense-pro
- Set the Category selector dropdown to Integration and hit Add.
- Locate the newly added pfSense Pro repository card and hit Download.
⚠️ Restart your Home Assistant instance to flush internal class caches.
- Navigate to:
Settings → Devices & Services → Add Integration
- Search for pfSense and complete the initial setup form:
- URL
- Username
- Password
- Download the latest release from the Releases page.
- Extract the
pfsensefolder into your Home Assistantcustom_componentsdirectory.
⚠️ Restart your Home Assistant instance.
- Configure via:
Settings → Devices & Services → Add Integration
To achieve the full NOC (Network Operations Center) visual experience, you must install the custom frontend architecture.
This is not a standard YAML card—it is a high-performance JavaScript module utilizing direct DOM-injection to prevent dashboard stalling.
High-frequency metrics (CPU, RAM, DHCP Leases) bypass Home Assistant's standard template re-rendering loops.
Data ticks freely in the UI without causing text-focus drops or browser freezes.
Major sub-sections:
- Interfaces
- Gateways
- Daemons
slide open beautifully on a single click while keeping your dashboard pristine.
A specialized, stealthy dropdown panel built to hold critical system execution scripts:
- Flush State Tables
- Reboot Router
- Halt Appliance
Tapping any daemon toggle (e.g. WireGuard/Tailscale) or appliance recovery script throws a native browser confirm() prompt, protecting your home network from accidental downtime.
A stylized cyber-terminal event box tracking and displaying:
- API calls
- Alias pool variations
- Security sinks
in real time.
- Download the card file from this repo:
www/pfsense-command-center.js(raw download). - Connect to your Home Assistant file system (via SSH, Samba, or File Editor).
- Copy the file to:
/config/www/pfsense-command-center.js
Or via SSH / Terminal in one go:
wget -O /config/www/pfsense-command-center.js https://raw.githubusercontent.com/DonTranQuiL/Pfsense-pro/main/www/pfsense-command-center.js-
If
/config/www/did not exist before, restart Home Assistant once so/local/is served. -
In Home Assistant navigate to:
Settings → Dashboards → Three Dots (Top Right) → Resources
- Click + Add Resource
Set:
URL:
/local/pfsense-command-center.js
Resource Type:
JavaScript Module
- Go to your dashboard.
- Click Edit Dashboard.
- Add a Manual Card.
- Paste the following zero-config trigger:
type: custom:pfsense-command-center-cardTo harness the true power of pfSense Pro, network administrators must understand how the dynamic alias modification pipeline and outbound connection state-killing engines operate under the hood.
┌─────────────────────────┐ ┌──────────────────────────┐ ┌───────────────────────────┐
│ Home Assistant UI Card │ ───────────> │ Services Mapping Layer │ ───────────> │ pypfsense Client Engine │
│ [Alias / Target Input] │ │ [services.py Patch] │ │ [pypfsense/__init__.py]│
└─────────────────────────┘ └──────────────────────────┘ └───────────────────────────┘
│
▼
[Secure XML-RPC Remote Script Execution]
┌─────────────────────────┐ ┌──────────────────────────┐ ┌───────────────────────────┐
│ Active Sessions Cleared │ <─────────── │ Background Filter Reload │ <─────────── │ config.xml Array Appended │
│ [pfctl State Purge] │ │ [filter_configure()] │ │ [Array Nesting Normalized]│
└─────────────────────────┘ └──────────────────────────┘ └───────────────────────────┘
In pfSense, an Alias acts as a named bucket of host IPs.
By itself, it performs no actions.
You must link the alias to a static rule in your pfSense WebGUI (for example, route alias through VPN or block alias from WAN) exactly once.
Home Assistant then takes over as the dynamic engine.
When a service call is executed, the client triggers an enterprise-grade operational pipeline:
Home Assistant formats and passes your target IP and Alias name into the backend wrapper.
A custom, secured PHP string is passed to the pfSense xmlrpc.php target endpoint.
pfSense natively stores single-IP aliases as flat strings, but multi-IP aliases as indexed arrays.
The integration intercepts this and dynamically normalizes the array structure to prevent parsing crashes.
The engine:
- Updates the internal table.
- Serializes the memory state back onto local disk via
write_config(). - Triggers a lightweight ruleset rebuild via
filter_configure().
Standard policy-routing adjustments suffer from session persistence delays.
Active network connections remain locked to their old gateway paths until state table timers naturally expire.
pfSense Pro resolves this completely.
When modifying an alias entry, the engine executes a rapid connection state purge inside the firewall shell:
/sbin/pfctl -k [target_device_ip]
/sbin/pfctl -k 0.0.0.0/0 -k [target_device_ip]Breaks every active socket where your target client machine is the originator.
Clears inbound path echoes.
The device experiences a clean, instantaneous socket reset.
When it automatically retries its connection a millisecond later, the newly reloaded firewall rules catch the session and push it down your new VPN tunnel or isolation path instantly.
Leverage the true power of Home Assistant by tying the pfSense Pro alias manipulation engine directly into your smart-home telemetry.
Protect your infrastructure.
Instantly drop a suspicious client machine out of your main network and lock it into a strict firewall isolation bucket if a security sensor logs anomalous LAN activities.
alias: "Security Matrix: Critical Boundary Node Isolation"
trigger:
- platform: state
entity_id: binary_sensor.perimeter_intrusion_alert
to: "on"
action:
- service: pfsense.update_alias
data:
entity_id: sensor.pfsense_pfsense_local_wan_ip_address
alias_name: "Isolatie"
address: "{{ state_attr('device_tracker.suspicious_client_node', 'ip_address') }}"
action: "add"
kill_states: trueEnforce strict routing schedules.
Automatically redirect streaming boxes, game consoles, or local workstations out of your unencrypted ISP gateway and straight into your secure vpn2_enabled tunnel at specific times of the day.
alias: "Network Optimization: Scheduled Workstation VPN Redirect"
trigger:
- platform: time
at: "08:00:00"
action:
- service: pfsense.update_alias
data:
entity_id: sensor.pfsense_pfsense_local_wan_ip_address
alias_name: "vpn2_enabled"
address: "192.168.1.120"
action: "add"
kill_states: trueA profound thank you and deep respect goes out to Travis Hansen (@travisghansen) and the extensive line of repository contributors who built the initial upstream framework located at:
travisghansen/hass-pfsense
Their early pioneering developments paved the way for local XML-RPC network routing control inside the Home Assistant smart-home ecosystem, making this highly-optimized rewrite possible.
pfSense® is a registered trademark of Rubicon Communications, LLC (Netgate).
This project is an independent Home Assistant integration and is not affiliated with, endorsed by, or sponsored by Netgate.