Migrate from deprecated stroke interface to modern VICI/swanctl for StrongSwan management

[dguido]

Summary

StrongSwan's stroke interface (used by ipsec commands and ipsec.conf) is officially deprecated in favor of the modern VICI interface (used by swanctl). Algo should migrate to the modern interface to stay aligned with upstream development and prepare for future Ubuntu LTS versions.

Background

Current State:

• Algo uses ipsec.conf + ipsec.secrets (stroke-based configuration)
• Management via ipsec statusall and similar stroke-based commands
• Works perfectly but relies on deprecated interfaces

StrongSwan Direction:

• stroke interface: ❌ Deprecated (maintained for backward compatibility)
• VICI/swanctl interface: ✅ Modern standard (active development focus)
• StrongSwan documentation states stroke "had never been designed to get automated"

Ubuntu LTS Roadmap Impact

Ubuntu LTS	StrongSwan Version	Default Interface	Status
20.04	5.8.2	stroke	Current
22.04	5.9.5	stroke	Current
24.04	5.9.13	stroke	Current
26.04 (2026)	~6.0+	Likely swanctl	Future risk

Technical Advantages of VICI/swanctl

1. Better Automation: Designed specifically for scripting and automation
2. Enhanced Security: More granular permission controls and validation
3. Modern Protocol: Stable IPC interface with multiple language bindings
4. Configuration Atomicity: Avoids race conditions present in stroke
5. Future-Proof: All new StrongSwan features target VICI first

Migration Scope

Files to Migrate

• ipsec.conf → swanctl.conf
• ipsec.secrets → swanctl certificate/key structure
• Client configuration generation templates
• Management/monitoring scripts (Ansible tasks)
• Documentation and user guides

Estimated Effort

• Configuration Templates: 2-3 days
• Client Generation Logic: 1-2 days
• Testing & Validation: 3-4 days
• Documentation Updates: 1 day
• Total: ~1-2 weeks for complete migration

Recommended Implementation Strategy

Phase 1: Preparation (3.0 Release)

# Always install swanctl alongside current stroke interface
- name: Install swanctl for future compatibility
  apt:
    name: strongswan-swanctl
    state: present

# Ensure both management interfaces work (requires AF_UNIX in SystemD restrictions)
RestrictAddressFamilies=AF_INET AF_INET6 AF_NETLINK AF_PACKET AF_UNIX

Phase 2: Hybrid Support (3.x)

• Generate both ipsec.conf and swanctl.conf configurations
• Add swanctl-based management commands alongside stroke
• Provide migration documentation for existing deployments

Phase 3: Default Migration (Future)

• Default to swanctl configuration (with stroke fallback option)
• Align with Ubuntu 26.04 LTS expectations

Benefits

1. Future-Proofing: Ready for Ubuntu 26.04+ direction
2. Better Security: Enhanced validation and permission controls
3. Improved Automation: Modern interface designed for scripting
4. Reduced Technical Debt: Align with upstream development focus
5. Competitive Advantage: Ready when other VPN projects need to catch up

Risks of Delaying

• Ubuntu 26.04 Impact: May be caught off-guard if Ubuntu defaults change
• Upstream Divergence: New StrongSwan features may not support stroke
• Maintenance Burden: Deprecated interfaces become harder to maintain

Implementation Notes

• Both interfaces can coexist during transition
• No immediate functionality impact (stroke remains supported)
• Migration can be gradual with user choice
• Maintains Algo's reliability-first approach

Definition of Done

• [ ] strongswan-swanctl package installed by default
• [ ] VICI socket functional (requires AF_UNIX address family)
• [ ] swanctl configuration templates created
• [ ] Client configuration generation supports swanctl
• [ ] Management scripts updated to use swanctl
• [ ] Documentation updated with modern interface examples
• [ ] Migration guide for existing deployments
• [ ] CI/CD tests validate both interfaces work

References

• StrongSwan VICI Documentation
• Ubuntu StrongSwan Package Evolution
• Related: Recent SystemD security hardening work that ensured both interfaces are functional

[dguido]

Research Findings: Ground Truth Verification

I've thoroughly researched this issue against official StrongSwan documentation and upstream sources. Here's what I found:

✅ Claims Verified

Claim	Status	Evidence
stroke is deprecated	✅ VERIFIED	Official docs state "legacy stroke...no longer built by default"
StrongSwan 6.0 disabled stroke by default	✅ VERIFIED	6.0.0 release notes (Dec 2024) confirm this
swanctl is recommended	✅ VERIFIED	StrongSwan maintainer explicitly recommends swanctl.conf

⚠️ Nuance on Ubuntu 26.04 Risk

The claim that "Ubuntu 26.04 will break Algo" is overstated:

• Ubuntu will likely continue shipping strongswan-starter package (stroke interface) even after 26.04
• The two approaches use separate packages that cannot coexist (they compete for same ports):
  • Legacy: strongswan-starter + strongswan-charon → strongswan-starter.service → ipsec.conf
  • Modern: charon-systemd + strongswan-swanctl → strongswan.service → swanctl.conf
• The risk is that stroke becomes a secondary/optional package, not that it disappears

🔴 Critical Migration Risks

Full migration carries significant risk that should not be underestimated:

1. Different defaults between ipsec.conf and swanctl.conf:

   • uniqueids=yes → unique=no (can cause duplicate session issues)
   • keyingtries=3 → keyingtries=1
   • Lifetime parameters interpret differently

2. Certificate paths change completely:

   • /etc/ipsec.d/certs/ → /etc/swanctl/x509/
   • /etc/ipsec.d/private/ → /etc/swanctl/private/
   • /etc/ipsec.d/cacerts/ → /etc/swanctl/x509ca/

3. CRL handling differs: No ipsec rereadcrls equivalent - swanctl auto-loads from /etc/swanctl/x509crl/

4. pfSense migration (2019) reported post-reboot tunnel failures

5. 35+ files would need changes including templates, tasks, handlers, client configs, and documentation

📦 Preparatory Work Completed

I've made a single, zero-risk preparatory change:

# roles/strongswan/templates/100-CustomLimitations.conf.j2
-RestrictAddressFamilies=AF_INET AF_INET6 AF_NETLINK AF_PACKET
+# AF_UNIX required for VICI socket communication (swanctl/modern StrongSwan interface)
+RestrictAddressFamilies=AF_INET AF_INET6 AF_NETLINK AF_PACKET AF_UNIX

This:

• Is backward-compatible (doesn't affect stroke interface)
• Enables future VICI socket communication via /var/run/charon.vici
• Prepares for eventual migration without committing to it now

📋 Recommendation: Phased Approach

Given that:

• Ubuntu 24.04 works perfectly and is supported until 2029
• Ubuntu 26.04 is 18 months away
• Full migration is high-risk with complex behavioral differences

I recommend:

1. Now (Done): AF_UNIX preparatory work ✅
2. 2025 Q4: Begin parallel swanctl.conf generation for testing
3. Ubuntu 26.04 release: Full migration with OS-version detection

This follows Algo's "stability over features" philosophy while ensuring we're not caught off-guard.

---

🤖 Generated with Claude Code