Skip to main content
RunBook Academy

← All runbooks in OPNsense

low riskinformational~30 min

Runbook: Packet Capture Investigation

1 · Prerequisites

Confirm every item is in place before any state change.

  • Console or SSH access to the firewall
  • Known source and destination addresses for the test traffic
  • Knowledge of which interface the traffic should enter and leave

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

  • · Identify the smallest interface that can answer the question (LAN, WAN, VLAN, tunnel)
  • · Identify the source and destination IP and port the test traffic will use
  • · Confirm there is no on-path encryption that would obscure the trace (TLS, IPsec, WireGuard)
  • · Capture the current count of bytes and packets on the interface as a baseline

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

  1. 1From the GUI, navigate to Reporting > Live View and use the dropdown to select the interface under investigation
  2. 2Set the BPF filter to the narrowest expression that still captures the failing flow, e.g. host 10.10.10.5 and host 10.20.20.5 and tcp port 443
  3. 3Start the capture and reproduce the failing flow once
  4. 4Stop the capture after a few seconds and open the saved .pcap file in Wireshark
  5. 5If the GUI is unavailable, run tcpdump -ni em0 -w /tmp/cap.pcap host 10.10.10.5 and host 10.20.20.5 from the shell and inspect the file from a remote host
  6. 6Read the trace from the top: was the packet seen entering the chosen interface at all? If not, the problem is upstream of the firewall
  7. 7If the packet enters but does not leave, capture on the egress interface and check whether the packet is dropped or forwarded
  8. 8Cross-reference the trace with the firewall live log on the interface to confirm whether the packet matched a pass rule or a block rule
  9. 9For tunnel traffic, confirm the inner payload is the expected protocol before drawing conclusions about the outer headers
  10. 10Save the capture file with a timestamped name under /root for inclusion in the incident record

4 · Verification

Confirm the procedure actually fixed the problem.

  • ✓The capture is reproducible and the file opens cleanly in Wireshark
  • ✓The trace contains both directions of the test flow
  • ✓The firewall live log and the trace agree on the action taken for each packet
  • ✓The incident record contains a copy of the capture file with a clear filename

5 · Rollback

If verification fails, undo the procedure in reverse order.

  • ↶Stop the live capture and remove temporary BPF filters
  • ↶Delete the saved .pcap if it contains sensitive payload data
  • ↶If a temporary firewall rule was added during troubleshooting, remove it after the investigation

6 · Escalation

When the runbook isn't enough, contact:

  • · If the trace shows no packet entering the firewall, escalate to the upstream network team
  • · If the trace shows the packet entering but the firewall log shows a block, escalate to the policy owner before changing rules
  • · If the trace shows asymmetric routing, escalate to the network team with the source and destination addresses

Purpose

Use a packet capture, either from the GUI live view or from the shell with tcpdump, to determine whether traffic is reaching the firewall, being forwarded, and matching the expected rules.

When to use this runbook

Use this runbook when a flow is failing and the firewall log alone cannot explain why. Common scenarios include asymmetric routing, MTU problems, NAT translation errors, VPN encapsulation issues, and rule precedence disputes.

Pre-checks

Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.

Procedure

Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.

Verification

After the procedure, the structured verification items from the frontmatter are rendered as a checklist.

Rollback

If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.

Escalation

The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.

References

  1. OPNsense documentation — packet capture
  2. Wireshark — display filters
  3. tcpdump(8) — manual page