Connect Linux Server to Alibaba Cloud VPC via IPsec VPN (Guided)

Scenario Description

Configure IPsec on a Linux server to establish a secure tunnel over the public network connecting to an Alibaba Cloud VPC. Typical use cases: edge servers, lightweight servers, Wuying cloud desktops, and edge nodes establishing secure tunnels via public network to access Alibaba Cloud VPC internal resources.

Architecture: Linux Server (StrongSwan) ←IPsec Dual Tunnel→ VPN Gateway → VPC + VSwitch + Security Group

Preparation

Requirements:

• * Linux server with public IP (NAT supported) and SSH key authentication
• Network: UDP 500/4500, ESP, TCP 22 allowed to this Linux server
• Alibaba Cloud VPC

Resource provisioning is outside this skill's scope.

Pre-checks

1. Aliyun CLI version verification

Pre-check: Aliyun CLI >= 3.3.1 required
Run aliyun version to verify >= 3.3.1. If not installed or version too low, see references/cli-installation-guide.md for installation instructions.
Then run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

CODEBLOCK0

2. Authentication credential verification

Pre-check: Alibaba Cloud Credentials Required
Security Rules:

• - NEVER read, echo, or print AK/SK values
• ONLY use aliyun configure list to check credential status

> aliyun configure list
> 

Check the output for a valid profile (AK, STS, or OAuth identity).
If no valid profile exists, STOP here and configure credentials outside of this session.

Phase 1: Permission Check

Before proceeding, verify that your Alibaba Cloud account has the necessary permissions.

Required APIs: INLINECODE3

Step 1.1: Use ram-permission-diagnose skill

Trigger the ram-permission-diagnose skill to diagnose current user's permissions:

CODEBLOCK2

Step 1.2: Compare against required policies

Refer to references/ram-policies.md for complete permission requirements.

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Phase 2: Guided Parameter Collection

Interaction Principles:

• - Guided & User-Friendly: Collect from basic to specific — start with foundational params (Region → VPC → VSwitch), use each to auto-query dependent options via API, then drill down to detailed configs
• Interactive: All parameters MUST be explicitly confirmed by user. NO auto-selection
• Immutable Once Confirmed: NEVER change a previously confirmed parameter without explicit user request
• WAIT for user confirmation at each step before proceeding

Parameters to Collect

#	Parameter	Source	Depends On
1	RegionId	API query INLINECODE5	—
2

VpcId | API query describe-vpcs | RegionId | | 3 | Bandwidth & Billing | User choice (recommend 10Mbps, 1yr) | — | | 4 | VPN Gateway Name | Auto-suggest ipsec-vpn-{REGION}-{DATE} | RegionId | | 5 | Primary VSwitchId | API query describe-vpn-gateway-available-zones + describe-vswitches | RegionId, VpcId, Bandwidth | | 6 | Backup VSwitchId | Same as above (must be different AZ) | Same as above | | 7 | Server Public IP | User input (validate IPv4, warn if RFC1918) | — | | 8 | SSH Username | User input (default: root) | — | | 9 | SSH Private Key | User input (path to key file, default: ~/.ssh/id_rsa) | — | | 10 | LocalSubnet | Recommend full VPC CIDR from Step 2 | VpcId | | 11 | RemoteSubnet | User input (MUST be internal subnet, NOT public IP, NOT 0.0.0.0/0) | Server info | | 12 | PSK | Auto-generate openssl rand -base64 24 (min 16 chars) | — |

Step 2.1: Select Region

CODEBLOCK3

Highlight recommended regions (cn-beijing, cn-hangzhou, cn-shanghai, cn-shenzhen).

Step 2.2: Select VPC

CODEBLOCK4

Step 2.3: Configure Bandwidth & Billing

Bandwidth: 5/10(recommended)/20/50/100+ Mbps. Duration: 1mo/3mo/6mo/1yr(recommended)/2yr/3yr.

Step 2.4: Select VSwitches (Primary + Backup, must be different AZ)

CODEBLOCK5

Recommend pairs spanning different AZs. Validate: primary and backup MUST be in different AZ.

Step 2.5: Server Information

• - Server Public IP: User input. Validate IPv4 format; warn if RFC1918 private range detected.
• SSH Username: Default root. User can specify other admin user.
• SSH Private Key: Path to private key file (e.g., ~/.ssh/id_rsa).
• SSH IP: Default same as Server Public IP. User can override if SSH uses a different IP/port.

Step 2.6: Network Planning

• - LocalSubnet: Recommend full VPC CIDR {VPC_CIDR} from Step 2.2
• RemoteSubnet: User input. Can SSH to server and run ip addr show to get internal subnet. ⚠️ MUST be internal subnet (e.g., 10.0.0.0/24), NOT public IP or 0.0.0.0/0

Step 2.7: Generate PSK

CODEBLOCK6

⚠️ Save PSK securely. NEVER echo in plain text. Offer: use generated / regenerate / enter custom (min 16 chars).

Phase 3: Server-side Pre-check

SSH to server and collect network info before creating cloud resources:

CODEBLOCK7

Record: Server Internal IP, Local Subnet (e.g., 10.0.0.0/24), Default Gateway, Network Interface.

⚠️ RemoteSubnet in IPsec config must use server's internal subnet, NOT public IP or 0.0.0.0/0.

OS & Privileges: Check OS type, admin privileges, network connectivity, StrongSwan status (which strongswan swanctl). See references/server-precheck.md.

Phase 4: Confirm Configuration

Display collected parameters and ask user to confirm before proceeding. Explain the upcoming steps.

Phase 5: Create Cloud Resources

Step 5.1: Create VPN Gateway

CODEBLOCK8

Wait for activation (5-10 minutes), then get dual-tunnel IPs:

CODEBLOCK9

Common Error Handling

If you encounter InvalidVSwitchId.SecondVswitchNotSupport error when create vpn gateway, after double check the existance of this VSwitch, it means the availability zone of the backup VSwitch does not support VPN deployment.

Solution: Query VPN-supported availability zones and select a VSwitch in a suitable zone within the same VPC.

Note: Always use dual-tunnel mode. Do not fallback to single-tunnel mode.

Step 5.2: Create Customer Gateway

CODEBLOCK10

Record CustomerGatewayId.

Step 5.3: Create IPsec Connection (Dual-tunnel Mode)

Important: Current CLI version has limited support for --tunnel-options-specification parameter in plugin mode. Must use RPC style command with --method POST --force parameters.

CODEBLOCK11

Note: This command uses RPC API style (traditional format) because the current plugin mode create-vpn-connection command has compatibility issues when handling --tunnel-options-specification parameter for dual-tunnel mode. Recommend reporting to Alibaba Cloud CLI team to improve plugin mode support.

Record VpnConnectionId.

Phase 6: Add VPC Routes

⚠️ Important: Manual route addition may be required even with --auto-config-route=true.

CODEBLOCK12

Expected: Status = Available, next hop = VPN Gateway.

Phase 7: Server-side StrongSwan Configuration

See references/strongswan-config.md for complete StrongSwan configuration procedures including:

• - MUST read and follow the referenced document before proceeding
• Pre-configuration backup and validation steps
• Installation commands (Ubuntu/Debian/CentOS)
• INLINECODE26 template with dual-tunnel setup using VICI
• INLINECODE27 configuration with VICI plugin
• Firewall rules (UDP 500/4500, ESP protocol)
• Kernel parameter setup (net.ipv4.ip_forward)
• Connection initiation and rollback procedures

Note: Must use the VICI (Versatile IKE Configuration Interface) method with swanctl.conf instead of the legacy ipsec.conf format. This allows both tunnels to be UP simultaneously using priority-based routing.

Quick Steps:

1. 1. Backup existing configuration:

CODEBLOCK13

1. 2. Install and configure StrongSwan (see strongswan-config.md for details)

1. 3. Validate and load configuration:

CODEBLOCK14

Note: If swanctl command not found, read strongswan-config.md and ensure strongswan-swanctl package is installed. NEVER fallback to legacy ipsec.conf.

1. 4. Initiate both tunnels:

CODEBLOCK15

1. 5. Verify tunnel status:

CODEBLOCK16

Phase 8: Verification & Diagnostics

Perform real verification (no simulated data):

Step 8.1: Check Aliyun Tunnel Status

CODEBLOCK17

Expected: Both tunnels have:

• - State = INLINECODE34
• INLINECODE35 = ipsec_sa_established (after StrongSwan is configured and started)

Step 8.2: Check Server-side StrongSwan Status

Run on server:

CODEBLOCK18

Expected: Both tunnels show ESTABLISHED.

Alternative detailed view:
CODEBLOCK19

Step 8.3: Real Connectivity Test

CODEBLOCK20

Expected: All packets received with reasonable latency.

Step 8.4: Troubleshooting if Failed

See references/troubleshooting.md for detailed diagnosis:

• - Check firewall rules (UDP 500/4500, ESP)
• Verify PSK matching
• Check IKE/IPsec parameter consistency
• Review tunnel logs on both sides

Full verification procedures: references/verification-method.md.

Phase 9: Success Criteria

Success criteria:

• - ✅ VPN Gateway status = INLINECODE38
• ✅ Dual tunnels both show INLINECODE39
• ✅ Server-side StrongSwan both tunnels INLINECODE40
• ✅ Bidirectional ping successful (Server ↔ VPC ECS)

Phase 10: Cleanup (Optional)

Delete resources in order (requires explicit user confirmation):

CODEBLOCK21

Best Practices

1. 1. Security: Use strong PSK (min 16 chars, mixed case, numbers, special chars). Rotate regularly.
2. High Availability: Deploy dual-tunnel mode with VSwitches across different AZs.
3. Encryption Standard: IKEv2 + AES256 + SHA256 + DH Group14 (modp2048).
4. Parameter Consistency: All IKE/IPsec params on Aliyun and server side MUST match exactly.
5. Firewall Rules: Critical! Allow UDP 500 (IKE), UDP 4500 (NAT-T), ESP protocol (#50).
6. Route Management: Always verify routes added after IPsec creation; auto-config may fail.
7. Log Analysis: Check both Aliyun tunnel logs and server-side StrongSwan logs when troubleshooting.
8. NAT Traversal: If server behind NAT, configure local_addrs=%defaultroute and encap=yes in swanctl.conf.
9. Dual-Tunnel Mode: Use priority parameter in swanctl.conf to allow both tunnels UP simultaneously (priority=100 for master, priority=200 for slave).

Reference Documentation

Document	Description
references/cli-installation-guide.md	Aliyun CLI installation & configuration
references/ram-policies.md

RAM permission policies | | references/server-precheck.md | Server-side pre-check procedures | | references/strongswan-config.md | Complete StrongSwan VICI/swanctl config | | references/verification-method.md | Verification steps & diagnostics | | references/acceptance-criteria.md | Acceptance test criteria | | references/troubleshooting.md | Common issues & solutions | | references/related-apis.md | Related APIs & CLI commands |