Skip to main content
RunBook Academy

← All runbooks in OPNsense

high riskservice affecting~60 min

Runbook: Configure an IPsec Site-to-Site Tunnel

1 · Prerequisites

Confirm every item is in place before any state change.

  • Both peer endpoints reachable on UDP 500, UDP 4500, and protocol 50 (ESP)
  • Pre-shared key or certificate chain already provisioned
  • IKE and Phase 2 proposals agreed with the remote peer
  • Maintenance window scheduled

2 · Pre-checks

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

  • · Confirm both WAN interfaces pass traffic between them (ping from firewall to firewall)
  • · Confirm the chosen IKE version (IKEv2 is preferred) matches on both ends
  • · Confirm the local and remote ID types are consistent (typically IP address or FQDN)
  • · Identify the local and remote protected subnets and confirm they do not overlap

3 · Procedure

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

  1. 1Navigate to VPN > IPsec > Tunnel Settings and click Add P1 to create the Phase 1 entry
  2. 2Set Authentication method to Mutual PSK and paste the shared key
  3. 3Set the proposal to a single strong DH group (14, 15, 16, or 20) and cipher (AES-256-GCM preferred)
  4. 4Set the local and remote identifier types and values to match the peer exactly
  5. 5Save the Phase 1 entry and then click Add P2 to add a Phase 2 entry
  6. 6Set the local and remote networks to the protected subnets and choose a matching Phase 2 proposal (AES-256-GCM is acceptable; PFS group recommended)
  7. 7Click Apply changes to push the configuration to the strongSwan daemon
  8. 8Open Firewall > Rules > IPsec and add a pass rule from the local subnet to the remote subnet and vice versa
  9. 9On the WAN interface, ensure ESP, UDP 500, and UDP 4500 are permitted (typically the default WAN rules already permit IPsec)
  10. 10From the shell, run ipsec status and confirm the tunnel shows as established
  11. 11From a host behind the firewall, ping a host on the remote subnet and confirm the SA counters increment

4 · Verification

Confirm the procedure actually fixed the problem.

  • ✓ipsec status reports the child SA as installed and the IKE SA as ESTABLISHED
  • ✓Firewall live log shows permitted traffic on the IPsec interface
  • ✓A bidirectional ping or traceroute across the tunnel completes
  • ✓No "no proposal chosen" or "CHILD_SA not found" errors appear in the strongSwan log

5 · Rollback

If verification fails, undo the procedure in reverse order.

  • ↶Disable the Phase 1 entry to drop the tunnel without removing configuration
  • ↶Remove the IPsec firewall rules on the IPsec interface and WAN if traffic should be blocked
  • ↶Revert the configuration to the last known-good backup under System > Configuration > Backups

6 · Escalation

When the runbook isn't enough, contact:

  • · If phase 1 fails, capture the strongSwan log via System > Log Files > Core and share with the peer operator
  • · If phase 2 fails with NO_PROPOSAL_CHOSEN, align the proposal sets on both sides before retrying
  • · Engage the network or carrier team if UDP 500 or 4500 is dropped between the two endpoints

Purpose

Stand up or replace an IPsec site-to-site tunnel with OPNsense as one endpoint, with proposals that match the peer and rules that permit the actual traffic.

When to use this runbook

Use this runbook when greenfielding a site-to-site IPsec tunnel, replacing an end-of-life tunnel, or revising proposals for security posture. Also use when an existing tunnel must be re-keyed against new policies.

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 — IPsec
  2. OPNsense documentation — IPsec site-to-site
  3. strongSwan documentation