medium riskservice affecting~60 min

Runbook: Troubleshoot IPsec

1 · Prerequisites

Confirm every item is in place before any state change.

IPsec tunnel was previously working or freshly configured
Access to the strongSwan log under System > Log Files > Core
Peer endpoint operator available for proposal alignment

2 · Pre-checks

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

· Capture the current tunnel state with ipsec status from the OPNsense shell
· Capture the most recent log lines from the IPsec tab on System > Log Files > Core
· Confirm the WAN interface has a stable address and is reachable from the peer
· Confirm the local time is within a few seconds of the peer (clock skew breaks certificate-based IPsec)

3 · Procedure

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

1If the IKE SA does not reach ESTABLISHED, check the strongSwan log for NO_PROPOSAL_CHOSEN, AUTHENTICATION_FAILED, or INVALID_ID_INFORMATION
2For NO_PROPOSAL_CHOSEN, align Phase 1 proposals (encryption, integrity, DH group, lifetime) between the two peers
3For AUTHENTICATION_FAILED, re-verify the pre-shared key or the local and remote certificate chains match the configured peer IDs
4For INVALID_ID_INFORMATION, confirm the local and remote identifier types are identical and the values match what the peer has configured
5If the IKE SA is ESTABLISHED but no child SA appears, validate the Phase 2 local and remote networks and the Phase 2 proposals
6Run ipsec statusall from the shell to view the full set of installed SAs and their child selectors
7If the child SA is installed but traffic does not pass, open Firewall > Rules > IPsec and confirm a pass rule covers the source and destination subnets
8Capture on the IPsec interface (Reporting > Live View filtered to IPsec) and confirm ESP packets are counted when test traffic is sent
9If the WAN path is suspected, capture on the WAN interface and confirm ESP, UDP 500, and UDP 4500 are arriving
10Restart the strongSwan service from the shell with configctl ipsec reload after a configuration change rather than a full reboot

4 · Verification

Confirm the procedure actually fixed the problem.

✓ipsec status shows the IKE SA as ESTABLISHED and the child SA as installed
✓Packet counters on the child SA increment when test traffic is sent
✓Firewall live log shows permitted traffic on the IPsec interface
✓No further error messages appear in the strongSwan log after a successful test

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶Disable the Phase 1 entry to stop negotiation attempts
↶Revert the configuration to the last known-good backup under System > Configuration > Backups
↶Remove temporary permit-any rules added during troubleshooting

6 · Escalation

When the runbook isn't enough, contact:

· Escalate to the network team if ESP, UDP 500, or UDP 4500 is being dropped on the WAN path
· Engage the peer operator with the strongSwan log excerpt and the peer identifier configuration
· If the issue is certificate-based, escalate to the PKI owner with the certificate serial numbers and expiry dates

Purpose

Diagnose and restore an IPsec tunnel that has failed to establish, has lost its SA, or is established but not passing traffic between the protected subnets.

When to use this runbook

Use this runbook when an IPsec tunnel that used to work is broken, when a newly configured tunnel does not come up, or when traffic that previously traversed the tunnel is now dropped. Also use when the strongSwan log shows recurring errors.

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.