pfSense General Troubleshooting Guide

pfSense troubleshooting spans a wide range of scenarios: from complete loss of internet connectivity to performance degradation and inability to access the web GUI. This guide organizes the most common problems and their solutions, starting with a general diagnostic methodology.

Before beginning any troubleshooting, define the exact symptom: complete loss of connectivity, intermittent packet loss, issues limited to specific protocols, or problems originating from specific hosts. Precisely defining the symptom reduces diagnostic time significantly.

Diagnostic Methodology

Layer-by-Layer Verification

Follow a bottom-up approach based on the OSI model:

1. Physical layer - verify link indicators on interfaces (Status - Interfaces), confirm cables are connected and link is established
2. Data link layer - check the ARP table (Diagnostics - ARP Table), verify the upstream gateway MAC address is present
3. Network layer - verify interface IP addressing, routing table (Diagnostics - Routes), ping from pfSense itself (Diagnostics - Ping)
4. Transport layer - review firewall rules (Firewall - Rules), connection states (Diagnostics - States), NAT rules
5. Application layer - test DNS (Diagnostics - DNS Lookup), proxy servers, VPN tunnels

pfSense Diagnostic Tools

Connectivity Issues

No Internet Access

Symptom: LAN clients cannot reach the internet, but pfSense is reachable at its LAN address.

Verification sequence:

1. Check the WAN interface: Status - Interfaces. Confirm WAN has received an IP address, gateway, and DNS servers
2. Check the gateway: System - Routing - Gateways. The default gateway status must show Online
3. Ping from pfSense: Diagnostics - Ping, select the WAN interface as source, ping 8.8.8.8
4. Check NAT: Firewall - NAT - Outbound. For standard configurations, the mode should be set to Automatic outbound NAT
5. Check DNS: Diagnostics - DNS Lookup, resolve google.com. If resolution fails, verify System - General Setup - DNS Servers

If pinging an external IP from pfSense’s WAN interface succeeds but LAN clients cannot reach the internet, the issue lies in NAT configuration or firewall rules on the LAN interface.

Cannot Reach Internal Hosts

Symptom: clients in one subnet cannot connect to servers in another subnet through pfSense.

Verification:

1. Firewall rules: check rules on the source interface. pfSense applies rules on the ingress interface
2. Routing: confirm pfSense has routes to both subnets (Diagnostics - Routes)
3. Return route: verify destination hosts have a route back through pfSense
4. Asymmetric routing: if traffic arrives on one pfSense interface and leaves through another, check System - Advanced - Firewall & NAT - Bypass firewall rules for traffic on the same interface

DNS Resolution Problems

DNS Fails to Resolve Names

Symptom: ping by IP address works, but ping by hostname returns an error.

Steps:

1. Check pfSense DNS servers: System - General Setup. Confirm DNS servers are configured and reachable
2. Check DNS Resolver: Services - DNS Resolver. Verify the service is running and bound to the appropriate interfaces
3. Test DNS server reachability: Diagnostics - Ping, ping each DNS server
4. Check firewall rules: ensure DNS traffic (port 53 TCP/UDP) is permitted from pfSense to external DNS servers
5. Clear DNS cache: Services - DNS Resolver, click Clear DNS Resolver Cache

DNS Resolver vs DNS Forwarder

pfSense offers two DNS operating modes:

• DNS Resolver (Unbound) - a recursive resolver that queries root servers directly. This is the default
• DNS Forwarder (dnsmasq) - forwards queries to upstream servers

Running both services simultaneously causes a port conflict. Ensure only one is enabled, or configure them on different ports.

Common mistake: when DNS Resolver operates in forwarding mode (DNS Query Forwarding enabled), verify that DNS servers in System - General Setup are correct and reachable. In forwarding mode, Unbound does not perform recursion independently.

Performance Issues

High CPU Usage

Identify the process consuming resources: Status - Dashboard (System Information widget) or via console with top -SH.

Common causes:

High Memory Usage

Check current consumption: Status - Dashboard. Primary consumers:

• State table - grows with active connections. Check size: Diagnostics - States Summary
• Packages (Suricata, Snort, ntopng) - can consume significant memory
• DNS Resolver cache - increases when serving many clients

To reduce state table memory consumption, lower the Firewall Maximum States value in System - Advanced - Firewall & NAT.

Low Throughput

If throughput through pfSense is below expectations:

1. Check interface speeds: Status - Interfaces. Verify speed and duplex are set correctly (Auto-negotiate in most cases)
2. Disable offloading: System - Advanced - Networking. Uncheck Hardware Checksum Offload and Hardware TCP Segmentation Offload - this is especially important in virtual environments
3. Check Traffic Shaper: if a traffic shaper is configured, ensure limits match the available bandwidth
4. Check IDS/IPS: Suricata and Snort inspect every packet, which can reduce throughput by 30-50%
5. Check MTU size: MTU mismatches between interfaces cause fragmentation and performance degradation

Web GUI Issues

Cannot Access the Web GUI

Symptom: the browser cannot connect to https://192.168.1.1 (or the pfSense LAN address).

Verification:

1. Ping pfSense: if ping fails, the issue is at the network level (wrong IP, disabled interface)
2. Web GUI port: default is 443 (HTTPS) or 80 (HTTP). The port may have been changed in System - Advanced - Admin Access
3. Protocol: check whether pfSense uses HTTP or HTTPS. Try both
4. LAN rules: verify the anti-lockout rule is not disabled (System - Advanced - Admin Access - Anti-lockout)
5. Restart web server: from the console, run pfSsh.php playback svc restart webConfigurator

Console Recovery

If web GUI access is completely lost:

1. Connect to the pfSense console (physical console, serial, IPMI, or hypervisor console)
2. Select 2) Set interface(s) IP address to verify/change the LAN IP address
3. Select 8) Shell and run:

pfSsh.php playback enableallowallwan    # Temporarily allow access from WAN
pfSsh.php playback disablereferercheck  # Disable referer check
pfSsh.php playback svc restart webConfigurator  # Restart web server

Important: after recovering access, immediately restore security settings and remove the allow-all rule on WAN.

Boot Problems

pfSense Will Not Boot

If pfSense fails to boot after an update or configuration change:

1. Interrupt autoboot: press the spacebar when the bootloader appears
2. Boot single user: select 2) Boot Single User from the bootloader menu
3. Check the filesystem: run fsck -y /dev/ada0p2 (replace the device name as needed)
4. Roll back configuration: configuration backups are stored in /conf/backup/. Copy a working configuration:

cp /conf/backup/config-TIMESTAMP.xml /conf/config.xml
reboot

Filesystem Issues

Signs of filesystem corruption: write errors in logs, inability to save configuration, spontaneous reboots.

To check and repair:

1. Boot into single user mode
2. Mount the root filesystem read-write: mount -o rw /
3. Run a check: fsck -y /
4. If errors are found, run the check again until a clean result is obtained
5. Reboot: reboot

State Table Exhaustion

Symptom: new connections fail to establish, logs show state table full messages.

Check current utilization: Diagnostics - States Summary or via the Dashboard - Firewall States widget.

Solutions:

• Increase the limit: System - Advanced - Firewall & NAT - Firewall Maximum States. The default value depends on available RAM
• Reduce timeouts: System - Advanced - Firewall & NAT - Firewall Optimization. The aggressive mode shortens idle state lifetimes
• Find the source: Diagnostics - States, sort by count. Common causes include P2P traffic, port scanning, or DDoS

Each state consumes approximately 1 KB of RAM. At 100,000 states, consumption is roughly 100 MB.

Package Problems

Package Fails to Install

If installing a package through Package Manager results in an error:

1. Check DNS: packages are downloaded from the repository by DNS name
2. Check internet access: pfSense must have internet connectivity to download packages
3. Check free space: run df -h from the Shell. Insufficient disk space is a common cause
4. Refresh the package list: System - Package Manager - Installed Packages, click Update All
5. Check version compatibility: verify the package is compatible with the current pfSense version

Package Causes Instability

If the system becomes unstable after installing a package:

1. Try removing the package through the web GUI: System - Package Manager - Installed Packages
2. If the web GUI is inaccessible, remove the package from the console:

pkg delete package-name

3. Reboot pfSense after removal

Factory Reset Procedure

A factory reset completely erases the configuration and returns pfSense to default settings. Use only as a last resort.

Via Web GUI

Diagnostics - Factory Defaults. Confirm the reset. pfSense will reboot with default settings (LAN IP 192.168.1.1, DHCP enabled).

Via Console

1. Connect to the console
2. Select 4) Reset to factory defaults
3. Confirm the reset
4. Wait for the reboot to complete

Via Bootloader

If the console menu is inaccessible:

1. Interrupt boot by pressing the spacebar
2. Boot into single user mode
3. Run:

mount -o rw /
rm /conf/config.xml
reboot

pfSense will create a default configuration on the next boot.

For additional firewall rule configuration details, see the firewall rules section. For issues specific to virtualized pfSense, refer to the virtualization guide . VPN configuration is covered in the VPN section.