Documentation
pfSense Documentation - Configuration and Administration Guides
pfSense Configuration Recipes - Common Scenarios
pfSense Service Recipes - HAProxy, Squid, SNMP

pfSense Service Recipes - HAProxy, Squid, SNMP

This section provides recipes for configuring network services in pfSense: HAProxy reverse proxy with automated certificates, Squid caching proxy, SNMP and NetFlow monitoring, captive portal for guest access, and other service deployment scenarios.

Before configuring services, create a configuration backup at Diagnostics - Backup & Restore. For a general overview of pfSense packages, see the pfSense packages section.

HAProxy as Reverse Proxy with Let’s Encrypt

HAProxy in pfSense serves as a reverse proxy, accepting HTTPS traffic on a single public IP and routing it to different internal web servers based on the domain name. The ACME package automates Let’s Encrypt certificate issuance and renewal.

Step-by-Step

  1. Install the required packages:

    • System - Package Manager - Available Packages - haproxy-devel
    • System - Package Manager - Available Packages - acme

  2. Configure ACME (Let’s Encrypt):

    • Navigate to Services - ACME Certificates - Account Keys
    • Click Add and create a Let’s Encrypt account:
      • Name - LetsEncrypt
      • ACME Server - Let’s Encrypt Production
      • Click Register ACME account key

  3. Create a certificate:

    • Navigate to Services - ACME Certificates - Certificates
    • Click Add:
      • Name - app1.example.com
      • Domain SAN list - add domains (app1.example.com, app2.example.com)
      • Method - standalone HTTP (port 8080) or DNS validation
      • Click Issue/Renew

  4. Configure HAProxy Backend (internal servers):

    • Navigate to Services - HAProxy - Backend
    • Create a backend for each web server:
      • Name - app1_backend
      • Server list:
        • Name - app1_server
        • Address - 192.168.1.10
        • Port - 80
      • Health check method - HTTP
      • Health check URI - /

  5. Configure HAProxy Frontend:

    • Navigate to Services - HAProxy - Frontend
    • Create a frontend:
      • Name - HTTPS_Frontend
      • External Address - WAN Address
      • Port - 443
      • SSL Offloading - checked
      • SSL Certificate - select the ACME certificate
      • Type - http/https (offloading)

  6. Configure ACL for domain-based routing:

    • In the frontend Access Control Lists section:
      • Name - app1_acl
      • Expression - Host matches
      • Value - app1.example.com
    • In the Actions section:
      • Action - Use Backend
      • Condition ACL names - app1_acl
      • Backend - app1_backend

  7. Repeat ACL and Actions for each domain

  8. Create a firewall rule on WAN:

Action: Pass
Protocol: TCP
Destination: WAN address
Destination port: 443

  1. Configure HTTP to HTTPS redirect:

    • Create an additional frontend on port 80
    • Enable HTTP Redirect to HTTPS

  2. Certificate auto-renewal is handled by ACME via cron

For certificate management details, see the pfSense certificates section.

HAProxy Load Balancing for Web Servers

HAProxy distributes incoming traffic across multiple servers for scalability and fault tolerance. It supports health checks and automatically removes failed nodes from the pool.

Step-by-Step

  1. Install haproxy-devel (if not already installed)

  2. Navigate to Services - HAProxy - Backend and create a backend:

    • Name - web_pool
    • Balance - Round Robin (or Least Connections)
    • Server list - add all servers:
NameAddressPortWeight
web1192.168.1.1080100
web2192.168.1.1180100
web3192.168.1.1280100
  • Health check method - HTTP
  • Health check URI - /health
  • Health check HTTP version - HTTP/1.1
  • Health check interval - 5000 (ms)

  1. Configure sticky sessions (if needed):

    • Cookie Name - SERVERID
    • Cookie Mode - Insert

  2. Create a frontend:

    • Name - Web_LB_Frontend
    • External Address - WAN Address
    • Port - 443
    • SSL Offloading - checked
    • Default Backend - web_pool

  3. Monitor HAProxy:

    • Navigate to Services - HAProxy - Stats
    • Enable the Statistics page
    • Access statistics at: https://pfSense_IP:stats_port/haproxy?stats

  4. Configure firewall rules on WAN to allow inbound traffic on port 443

Squid Transparent Proxy with Caching

Squid in caching proxy mode stores copies of frequently requested content, reducing bandwidth usage and accelerating page loads for users.

Step-by-Step

  1. Install Squid: System - Package Manager - Available Packages - squid

  2. Navigate to Services - Squid Proxy Server - General:

    • Enable Squid Proxy - checked
    • Proxy Interface - LAN
    • Proxy Port - 3128
    • Transparent HTTP Proxy - checked
    • Bypass Proxy for Private Address Destination - checked

  3. Navigate to Services - Squid Proxy Server - Local Cache:

    • Cache Replacement Policy - Heap LFUDA (recommended for caching)
    • Hard Disk Cache Size - cache size in MB (e.g., 10000 for 10 GB)
    • Hard Disk Cache System - ufs or aufs
    • Memory Cache Size - 256 or 512 MB
    • Maximum Object Size - 256 MB (for caching updates)
    • Maximum Object Size in RAM - 32 KB

  4. To cache Windows/Linux updates, add to Custom Options (Advanced):

refresh_pattern -i windowsupdate.com/.*\.(cab|exe|ms[i|u|f]|[ap]sf|wm[v|a]|dat|zip) 43200 80% 129600 reload-into-ims
refresh_pattern -i update.microsoft.com/.*\.(cab|exe|ms[i|u|f]|[ap]sf|wm[v|a]|dat|zip) 43200 80% 129600 reload-into-ims
refresh_pattern -i download.windowsupdate.com/.*\.(cab|exe|ms[i|u|f]|[ap]sf|wm[v|a]|dat|zip) 43200 80% 129600 reload-into-ims

  1. Navigate to Services - Squid Proxy Server - ACLs:

    • Allowed Subnets - 192.168.1.0/24
    • Unrestricted IPs - IP addresses bypassing the proxy (optional)

  2. Monitoring: Services - Squid Proxy Server - Real Time and install the LightSquid package for reporting

SNMP Monitoring with Zabbix/LibreNMS

SNMP (Simple Network Management Protocol) allows monitoring systems (Zabbix, LibreNMS, PRTG) to collect pfSense status data: CPU load, memory, interface traffic, and firewall state counts.

Step-by-Step

  1. Navigate to Services - SNMP:

    • Enable - checked
    • System Location - physical location (server room, rack)
    • System Contact - contact email
    • Community String - change from public to a unique string (SNMPv2c)
    • Bind Interface - LAN (do not bind to WAN)
    • SNMP Modules - enable MibII, Netgraph, PF, Host Resources

  2. For SNMPv3 (recommended for security):

    • Configure via SSH on pfSense by editing /usr/local/etc/snmpd.conf
    • Add an SNMPv3 user with SHA authentication and AES encryption

  3. Create a firewall rule on LAN:

Action: Pass
Protocol: UDP
Source: monitoring_server_IP
Destination: LAN address
Destination port: 161

  1. On Zabbix:

    • Add a host with the pfSense IP
    • Apply the Template Net pfSense SNMPv2 (or SNMPv3)
    • Specify the SNMP community string

  2. On LibreNMS:

    • Add a device via the web interface or CLI:
    lnms device:add pfSense_IP -c community_string
    • LibreNMS auto-detects pfSense and applies the appropriate sensors

  3. Key OIDs for pfSense monitoring:

ParameterOID
CPU Usage1.3.6.1.4.1.2021.11
Memory Usage1.3.6.1.4.1.2021.4
Interface Traffic1.3.6.1.2.1.2.2.1
PF States1.3.6.1.4.1.12325.1.200.1

For extended pfSense monitoring, see the pfSense monitoring section.

NetFlow/sFlow Export for Traffic Analysis

NetFlow exports network flow metadata (IP addresses, ports, volumes, protocols) to a collector for detailed traffic analysis and anomaly detection.

Step-by-Step

  1. Install the package: System - Package Manager - Available Packages - softflowd

  2. Navigate to Services - softflowd:

    • Interface - LAN (or WAN, depending on requirements)
    • Host - NetFlow collector IP (e.g., 192.168.1.100)
    • Port - collector port (e.g., 2055)
    • Max Flows - 8192
    • NetFlow Version - 9 (or IPFIX for v10)
    • Tracking Level - Full (IP + Port + Protocol)

  3. To monitor multiple interfaces, add separate softflowd instances

  4. NetFlow Collectors:

    • ntopng - install via Package Manager on pfSense or a dedicated server
    • Elastic Stack - use Logstash with the netflow input
    • nfdump/nfsen - lightweight solution for storage and analysis

  5. Create a firewall rule to allow NetFlow data transmission to the collector

  6. Alternatively, for sFlow use the hsflowd package:

    • Install via pkg from the pfSense console
    • Configure the sFlow collector

Captive Portal with Vouchers for Guest Access

A captive portal redirects users to an authentication page before granting internet access. The voucher system generates single-use codes for hotel, cafe, or conference guests.

Step-by-Step

  1. Prepare a dedicated interface or VLAN for the guest network:

    • Create a VLAN for guests (e.g., VLAN 50 - 10.50.0.0/24)
    • Configure DHCP for the guest interface

  2. Navigate to Services - Captive Portal:

    • Click Add to create a new zone
    • Zone Name - Guest_WiFi

  3. Configure zone parameters:

    • Interfaces - guest interface (VLAN 50)
    • Maximum Concurrent Connections - limit (e.g., 100)
    • Idle Timeout - 30 minutes
    • Hard Timeout - 480 minutes (8 hours)
    • Pass-through MAC - MAC addresses of devices exempt from authentication (printers, Smart TVs)

  4. Configure the authentication page:

    • Upload an HTML portal template in the Portal page contents field
    • Add branding and styling for the establishment

  5. Enable vouchers:

    • Navigate to the Vouchers tab
    • Enable Vouchers - checked
    • Voucher Rolls - click Add to create a batch:
      • Roll Number - 1
      • Minutes per Ticket - 60 (1 hour) or 1440 (24 hours)
      • Count - number of vouchers in the batch (e.g., 1000)
    • Click Generate and export the voucher list to CSV

  6. Create firewall rules on the guest interface:

# Block access to internal network
Action: Block
Interface: Guest_WiFi
Source: Guest_WiFi net
Destination: LAN net

# Allow internet access
Action: Pass
Interface: Guest_WiFi
Source: Guest_WiFi net
Destination: any
  1. Configure a bandwidth limiter for guests: Firewall - Traffic Shaper - Limiters
    • Limit per-user bandwidth (e.g., 5 Mbps download / 2 Mbps upload)

For guest isolation via VLANs, see the pfSense VLANs section.

DHCP Failover with HA Cluster

In a high availability (HA) configuration, two pfSense nodes synchronize their DHCP servers to ensure uninterrupted address assignment when one node fails.

Step-by-Step

  1. Confirm the pfSense high availability cluster is configured and operational (CARP + pfsync)

  2. On the primary node, navigate to Services - DHCP Server - LAN:

    • Enable - checked
    • Failover Peer IP - IP address of the secondary pfSense node (CARP interface or dedicated sync interface)

  3. On the secondary node:

    • Configure an identical DHCP server with the same pool parameters
    • Failover Peer IP - primary node IP

  4. Configure configuration synchronization:

    • On the primary node: System - High Avail. Sync
    • Enable DHCP Server synchronization

  5. Verify failover:

    • Shut down the primary node
    • Confirm clients continue receiving IPs from the secondary node
    • DHCP leases persist through the switch

  6. Monitoring: Status - DHCP Leases - view active leases on both nodes

Important: when configuring DHCP failover, both nodes must use non-overlapping address ranges or a shared range with coordination through the failover protocol. pfSense uses ISC DHCP, which supports native failover.

Wake-on-LAN Through pfSense

Wake-on-LAN (WoL) enables remote power-on of computers by sending a magic packet to the target device’s MAC address. pfSense provides a built-in WoL interface.

Step-by-Step

  1. Confirm target computers support WoL:

    • In BIOS/UEFI, enable Wake-on-LAN (typically under Power Management)
    • In the OS, enable WoL support on the network adapter:
      • Windows: Device Manager - Network Adapter - Properties - Power Management - Allow this device to wake the computer
      • Linux: ethtool -s eth0 wol g

  2. Navigate to Services - Wake-on-LAN:

    • Interface - LAN (interface where the target device is connected)
    • MAC Address - target device MAC address

  3. Click Send to transmit the magic packet

  4. For convenience, save devices:

    • Fill in MAC Address and Description
    • Click Save to add to the list
    • Subsequently, click Wake next to the desired device

  5. For WoL from a different subnet (via VPN or WAN):

    • A directed broadcast to the target subnet is required
    • Create a firewall rule allowing UDP packets to port 9 (or 7) to the target subnet broadcast address
    • Configure directed broadcast: System - Advanced - Firewall & NAT - enable Directed Broadcast if needed

  6. WoL via VPN:

    • Connect to pfSense through VPN
    • Use the built-in WoL interface or send a magic packet using a utility from the VPN client

Important: WoL functions only within a broadcast domain (single subnet). Waking devices across routed networks requires directed broadcast or a dedicated relay.

Last updated on
pfSense Security Recipes - Hardening and IDSpfSense VPN Recipes - IPsec, OpenVPN, WireGuard