PFSense | Timeout Waiting For Handshake

Overview 💥

If a PFSense inspection fails with the message similar to:

Timed out while waiting for handshake

This indicates the SSH handshake between the Liongard Agent and the pfSense device did not complete within the configured timeout. The root causes are typically network latency, firewall/routing issues, SSH service configuration, device performance, or the Inspector's SSH timeout (readyTimeout) being too short for the environment.

This article walks you through how to diagnose the problem from the agent host, remediate common causes, and when to contact Support.

Why this happens? 🤔

The SSH handshake must complete before authentication and data collection can begin. A timeout means the client (Liongard Agent) did not receive the server’s SSH banner / key exchange response within the expected window. Typical triggers:

Network latency, packet loss or asymmetric routing between the agent host and pfSense.
Firewall, NAT, or intermediate device blocking or delaying TCP/SSH packets.
pfSense SSH service disabled, listening on a different port, or rate-limited.
pfSense under heavy CPU / I/O load (slow to respond).
Agent readyTimeout too low for that network or device response time.
Incorrect credentials or account lockout (less common for pure handshake timeout).
Management interface changes (VPN/NAT rules, IP changes).

Quick checklist 📝

Run connectivity tests from the host running the Liongard Agent.
Confirm SSH port is reachable and listening on pfSense.
Attempt ssh -vvv from the agent host to observe where handshake stalls.
If network is slow but otherwise healthy, increase the readyTimeout (30s → 60s) and retry.
Re-run the Inspector in Clear Cache + Debug Mode and capture logs.

Steps to resolve 👨‍💻

Important: Always run the tests from the same machine the Liongard Agent runs on — this reproduces the agent’s network view.

1️⃣ — Validate basic reachability

From the agent host run:

Linux / macOS

ping -c 5 <pfsense-ip> 

traceroute <pfsense-ip>

Windows (PowerShell)

Test-Connection -ComputerName <pfsense-ip> -Count 4

tracert <pfsense-ip>

What to look for:

High packet loss or very high latency → investigate network/WAN issues.
Long or asymmetric routes → raise with networking team.

2️⃣ — Confirm SSH port connectivity

Default SSH port is 22 (confirm if customized). From agent host:

Linux

# with netcat
nc -vz <pfsense-ip> <port>

# or with bash TCP check
timeout 5 bash -c ">/dev/tcp/<pfsense-ip>/<port>" && echo "open" || echo "closed"

Windows PowerShell

Test-NetConnection -ComputerName <pfsense-ip> -Port <port>

If the port shows closed/refused, fix firewall/NAT or update Inspector to use the correct port.

3️⃣ — Run verbose SSH to inspect handshake

From the agent host:

ssh -vvv -p <port> <user>@<pfsense-ip>

Watch for:

DNS delays (try IP instead of hostname to isolate DNS).
Pauses before server banner or key exchange.
Errors like Connection timed out, Connection reset, or authentication failures.

If the banner appears and then it stalls at key exchange — likely device-side performance or rate-limiting.

4️⃣ — Check pfSense service & config

Confirm SSH service is enabled: System → Advanced → Secure Shell (or via console).
Verify SSH port and whether root / admin account is allowed.
Confirm pfSense firewall rules allow the agent host’s IP to reach the management interface.
Review pfSense system logs for SSH connection attempts and errors.

5️⃣ — Check for intermediate device interference

If there are load balancers, NATs, IDS/IPS or VPNs between the agent host and pfSense:

Ensure they forward TCP connections without undue inspection delays.
Check for connection throttling, SYN proxying, or deep-packet inspection that can delay handshakes.

6️⃣ — Consider device health

If pfSense is CPU or I/O bound it may respond slowly:

Check Diagnostics → System Activity or console for CPU/memory load.
If high load is present, investigate running processes, firewall rulesets, or other causes.

7️⃣ — Increase the Inspector/agent `readyTimeout`

If network or device response time is expected to be slow (remote WAN), increase handshake timeout:

Recommended starting value: 30000 ms (30s). If still failing, try 60000 ms (60s).
Edit the Inspector advanced SSH parameter or agent config where readyTimeout is exposed, save, and re-run the inspector in Clear Cache + Debug Mode.

Note: Increasing readyTimeout is a pragmatic workaround; it does not fix underlying network or device performance issues.

8️⃣ — Re-run inspector in Clear Cache + Debug Mode

Run the inspector with Clear Cache + Debug Mode to collect fresh logs.
Download and review the debug log; correlate timestamps with your SSH test outputs.

Troubleshooting Summary 🚀

Symptom	Possible cause	How to confirm	Recommended action
`Timed out while waiting for handshake`	Network latency/packet loss	`ping`, `traceroute` from agent host	Resolve WAN issues, optimize route, engage network team
SSH port closed / refused	Wrong port / firewall block	`Test-NetConnection` / `nc -vz`	Open firewall/NAT, correct port in Inspector
SSH stalls after server banner	pfSense overloaded / rate-limited	`ssh -vvv` shows hang during key exchange; check pfSense CPU	Investigate processes, reboot in maintenance window if needed
Works interactively but inspector times out	`readyTimeout` too low	Manual `ssh` connects; inspector fails	Increase `readyTimeout` (30s→60s) and re-run
No SSH access from agent host	SSH disabled or IP blocked	Login attempts from web UI or logs	Enable SSH, allow agent IP, check ACLs

Recommended commands & snippets 🧑‍🏫

From Agent host (Linux / macOS):

ping -c 5 <pfsense-ip>

traceroute <pfsense-ip>

nc -vz <pfsense-ip> <port>        # check TCP port

ssh -vvv -p <port> <user>@<pfsense-ip>

From Agent host (Windows PowerShell):

Test-Connection -ComputerName <pfsense-ip> -Count 4

tracert <pfsense-ip>

Test-NetConnection -ComputerName <pfsense-ip> -Port <port>
# Use PuTTY/plink for verbose SSH on Windows if needed

Best practices 🌟

Run tests from the agent host to simulate the agent’s view.
Use a dedicated, documented account for Inspector SSH access.
Standardize SSH/management ports to reduce configuration drift.
If inspecting remote sites over WAN, consider placing an on-premises Agent closer to the devices.
Avoid permanently high readyTimeout values — use them as a temporary mitigation while fixing root causes.
Schedule inspections away from maintenance windows or times of peak load.

When to contact Support 🦁

Open a ticket when:

You validated connectivity from the agent host and increased readyTimeout but the inspector still times out.
pfSense logs show the connection attempt but offer no clear rejection reason.
You suspect a pfSense firmware bug or need assistance analyzing inspector debug logs.
Provide the items listed above.

What to collect before contacting Support

Inspector debug log (run inspector in Clear Cache + Debug Mode).
ssh -vvv output captured from the agent host (include timestamps).
ping and traceroute (or Test-NetConnection) outputs from agent host to pfSense.
pfSense system logs showing SSH connection attempts (with timestamps).
pfSense version/build and SSH/management configuration (port, allowed IPs).
Any recent network or device configuration changes.

Attach all items to your ticket for faster triage.

References & external links 📚

Third-Party Link Disclaimer ‼️

We may reference external third-party resources solely as additional guidance.

Liongard does not own, control, or guarantee the accuracy, security, or reliability of third-party sites. Please use them at your own discretion and risk.