Lyubomir Georgiev x Zippi

Migrating OPNsense IPsec from Legacy Tunnel Settings to Modern Connections (swanctl)

·

,
batezippi Avatar
batezippi

OPNsense has deprecated the traditional IPsec Tunnel Settings (based on the legacy ipsec.conf format) in favor of the modern Connections interface powered by swanctl. The legacy system is now marked as deprecated, and migration to the new interface is strongly recommended for long-term support and improved maintainability.

This guide provides a complete, step-by-step process to migrate a site-to-site IPsec tunnel using Pre-Shared Key (PSK) authentication from the legacy Tunnel Settings to the new Connections system. The instructions are based on real-world testing on OPNsense 25.7 and newer.

Prerequisites

  • OPNsense version 25.7 or later.
  • A full configuration backup (System > Configuration > Backups).
  • Document your existing legacy configuration:
    • Phase 1 (IKE) settings
    • Phase 2 (ESP) settings
    • Pre-Shared Key
    • Local and Remote Identifiers
    • Local and remote protected subnets
  • Ensure the legacy tunnel is still operational for reference and rollback if needed.

Important Safety Note: Disable the legacy tunnel before enabling the new connection to prevent UDP port conflicts on ports 500 and 4500.

Step-by-Step Migration

Step 1: Create the New IPsec Connection

  1. Go to VPN > IPsec > Connections.
  2. Click the + button to add a new connection.
  3. Enable Advanced Mode (toggle usually located at the top of the edit page).

General Settings:

  • Enabled: Check after successful testing
  • Description: Provide a clear name for the tunnel (e.g., “Site-to-Site Tunnel”)
  • Key Exchange Version: IKEv2 (recommended)
  • Interface: Select your WAN (or appropriate outbound) interface
  • Remote Gateway: Enter the remote peer’s public IP address or hostname

Step 2: Configure Authentication and Identifiers

Correct identifier configuration is one of the most common sources of authentication failures after migration.

Local Authentication:

  • Authentication: Pre-Shared Key
  • ID (Local ID): Choose a consistent identifier — preferably a hostname or your public IP address

Remote Authentication:

  • Authentication: Pre-Shared Key
  • ID (Remote ID): The identifier used by the remote peer (its public IP or hostname)

Step 3: Add a Child Configuration (Phase 2)

In the Children section, click + to add a new child:

  • Description: Descriptive name (e.g., “LAN-to-RemoteLAN”)
  • Local Network: Your internal protected subnet
  • Remote Network: The remote internal protected subnet
  • Protocol: ESP

Step 4: Configure Proposals

Remove any default proposals to avoid mismatches.

IKE Proposals (Connection level):

  • Encryption: AES / 256 bits (CBC) or AES-GCM-256
  • Hash / Integrity: SHA256
  • DH Key Group: 14 (modp2048)

ESP Proposals (Child level):

  • Encryption: AES / 256 bits or AES-GCM-256
  • Hash: SHA256 (leave empty when using GCM)
  • PFS Group: 14 (modp2048)

Performance Note: On systems with AES-NI hardware acceleration (common on Intel CPUs), AES-GCM proposals offer excellent performance. If the remote peer rejects GCM, fall back to AES-CBC-256 + SHA256 + modp2048 for maximum compatibility.

Step 5: Configure the Pre-Shared Key

  1. Navigate to VPN > IPsec > Pre-Shared Keys.
  2. Add a new entry with the following settings:
    • Local Identifier: Must exactly match the Local ID configured in Step 2
    • Remote Identifier: Must exactly match the Remote ID configured in Step 2
    • Pre-Shared Key: Enter the exact same secret used in the legacy tunnel
    • Type: PSK

Step 6: Apply Changes and Test

  1. Disable the legacy tunnel under VPN > IPsec > Tunnel Settings [legacy].
  2. Save and apply all changes in the Connections section.
  3. Restart the IPsec service from VPN > IPsec > Status.
  4. Temporarily increase logging to Debug level for detailed output (VPN > IPsec > Log File).
  5. Generate test traffic across the tunnel or allow the remote side to initiate the connection.
  6. Verify tunnel status under VPN > IPsec > Status or the Connections overview. The status should show as “Established”.

Common Issues and Troubleshooting

  • NO_PROPOSAL_CHOSEN The remote peer does not accept the offered algorithms. Start with the more compatible AES-CBC-256 + SHA256 + modp2048 combination. Once confirmed working, you can test stronger AES-GCM proposals.
  • “no shared key found for … – ‘%any’” This is the most frequent error after migration. Ensure the Local ID, Remote ID, and the Pre-Shared Key entry match exactly on both firewalls. Using hostnames as identifiers is often more reliable than raw IP addresses.
  • Half-open IKE_SA deleted after timeout Indicates a proposal mismatch or failed authentication. Review the charon logs carefully and verify that proposals and identifiers are identical on both ends.

Final Recommendations

  • Keep the legacy tunnel configuration disabled (but not deleted) until the new tunnel has proven stable for at least 48 hours.
  • Test connectivity thoroughly with real traffic (ping, file transfers, or application flows) after migration.
  • Prefer AES-GCM proposals on modern hardware with AES-NI once compatibility with the remote peer is confirmed.
  • For complex setups (multiple tunnels, road-warrior clients, or route-based VTI interfaces), refer to the official documentation.

Reference: Official OPNsense IPsec documentation: https://docs.opnsense.org/manual/vpnet.html

Migrating to the new Connections interface brings your IPsec configuration in line with current StrongSwan best practices and ensures continued support in future OPNsense releases.

Other Posts