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.

aliyun version

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: [vpc:DescribeRegions, vpc:DescribeVpcs, vpc:DescribeVswitches, vpc:CreateRouteEntry, vpc:CreateVpnGateway, vpc:DeleteVpnGateway, vpc:CreateCustomerGateway, vpc:DeleteCustomerGateway, vpc:CreateVpnConnection, vpc:DeleteVpnConnection]

Step 1.1: Use ram-permission-diagnose skill

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

# Trigger: ram-permission-diagnose
diagnose permissions for 

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

Step 2.1: Select Region

aliyun vpc describe-regions --cli-query 'Regions.Region[].{RegionId:RegionId,LocalName:LocalName}' --user-agent AlibabaCloud-Agent-Skills

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

Step 2.2: Select VPC

aliyun vpc describe-vpcs --region {REGION_ID} --biz-region-id {REGION_ID} --cli-query 'Vpcs.Vpc[].{VpcId:VpcId,VpcName:VpcName,CidrBlock:CidrBlock}' --user-agent AlibabaCloud-Agent-Skills

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)

aliyun vpc describe-vpn-gateway-available-zones --region {REGION_ID} --biz-region-id {REGION_ID} --spec {BANDWIDTH}M --user-agent AlibabaCloud-Agent-Skills
aliyun vpc describe-vswitches --region {REGION_ID} --vpc-id {VPC_ID} --cli-query 'VSwitches.VSwitch[].{VSwitchId:VSwitchId,VSwitchName:VSwitchName,ZoneId:ZoneId,CidrBlock:CidrBlock,AvailableIpAddressCount:AvailableIpAddressCount}' --user-agent AlibabaCloud-Agent-Skills

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

PSK=$(openssl rand -base64 24 | tr -d '/+=' | head -c 20)

⚠️ 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:

ssh -o StrictHostKeyChecking=no -i {SSH_KEY_PATH} {SSH_USER}@{SSH_IP}
ip addr show && ip route show

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

aliyun vpc create-vpn-gateway \
  --region {REGION_ID} --biz-region-id {REGION_ID} \
  --vpc-id {VPC_ID} --name {VPN_NAME} --bandwidth {BANDWIDTH} --enable-ipsec true \
  --vswitch-id {PRIMARY_VSWITCH_ID} --disaster-recovery-vswitch-id {BACKUP_VSWITCH_ID} \
  --instance-charge-type PREPAY --period {PERIOD_MONTHS} --auto-pay true \
  --user-agent AlibabaCloud-Agent-Skills

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

aliyun vpc describe-vpn-gateway --region {REGION_ID} --biz-region-id {REGION_ID} --vpn-gateway-id {VPN_GATEWAY_ID} --cli-query '{PrimaryIp:InternetIp,BackupIp:DisasterRecoveryInternetIp}' --user-agent AlibabaCloud-Agent-Skills

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

aliyun vpc create-customer-gateway --region {REGION_ID} --biz-region-id {REGION_ID} --ip-address {SERVER_PUBLIC_IP} --name cgw-{VPN_NAME} --user-agent AlibabaCloud-Agent-Skills

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.

aliyun vpc CreateVpnConnection \
  --RegionId {REGION_ID} \
  --VpnGatewayId {VPN_GATEWAY_ID} \
  --LocalSubnet {LOCAL_SUBNET} \
  --RemoteSubnet {REMOTE_SUBNET} \
  --Name ipsec-{VPN_NAME} \
  --EffectImmediately true \
  --AutoConfigRoute true \
  \
  --TunnelOptionsSpecification.1.CustomerGatewayId {CGW_ID} \
  --TunnelOptionsSpecification.1.Role master \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.IkeVersion ikev2 \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.IkeMode main \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.IkeAuthAlg sha256 \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.IkeEncAlg aes256 \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.IkeLifetime 86400 \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.IkePfs group14 \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.LocalId {VPN_GW_IP_1} \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.RemoteId {SERVER_PUBLIC_IP} \
  --TunnelOptionsSpecification.1.TunnelIkeConfig.Psk {PSK} \
  --TunnelOptionsSpecification.1.TunnelIpsecConfig.IpsecAuthAlg sha256 \
  --TunnelOptionsSpecification.1.TunnelIpsecConfig.IpsecEncAlg aes256 \
  --TunnelOptionsSpecification.1.TunnelIpsecConfig.IpsecLifetime 86400 \
  --TunnelOptionsSpecification.1.TunnelIpsecConfig.IpsecPfs group14 \
  \
  --TunnelOptionsSpecification.2.CustomerGatewayId {CGW_ID} \
  --TunnelOptionsSpecification.2.Role slave \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.IkeVersion ikev2 \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.IkeMode main \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.IkeAuthAlg sha256 \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.IkeEncAlg aes256 \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.IkeLifetime 86400 \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.IkePfs group14 \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.LocalId {VPN_GW_IP_2} \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.RemoteId {SERVER_PUBLIC_IP} \
  --TunnelOptionsSpecification.2.TunnelIkeConfig.Psk {PSK} \
  --TunnelOptionsSpecification.2.TunnelIpsecConfig.IpsecAuthAlg sha256 \
  --TunnelOptionsSpecification.2.TunnelIpsecConfig.IpsecEncAlg aes256 \
  --TunnelOptionsSpecification.2.TunnelIpsecConfig.IpsecLifetime 86400 \
  --TunnelOptionsSpecification.2.TunnelIpsecConfig.IpsecPfs group14 \
  \
  --method POST \
  --force \
  --user-agent AlibabaCloud-Agent-Skills

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.

# Step 6.1: Query Route Tables
aliyun vpc describe-route-table-list --region {REGION_ID} --biz-region-id {REGION_ID} --vpc-id {VPC_ID}  --user-agent AlibabaCloud-Agent-Skills
# Step 6.2: Add Route Entries (for each route table)
aliyun vpc create-route-entry --region {REGION_ID} --biz-region-id {REGION_ID} --route-table-id {ROUTE_TABLE_ID} --destination-cidr-block {REMOTE_SUBNET} --next-hop-id {VPN_GATEWAY_ID} --next-hop-type VpnGateway --user-agent AlibabaCloud-Agent-Skills
# Step 6.3: Verify Routes
aliyun vpc describe-route-entry-list --region {REGION_ID} --biz-region-id {REGION_ID} --route-table-id {ROUTE_TABLE_ID} --destination-cidr-block {REMOTE_SUBNET} --user-agent AlibabaCloud-Agent-Skills

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)
• /etc/swanctl/swanctl.conf template with dual-tunnel setup using VICI
• /etc/strongswan.conf 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:

• Backup existing configuration:

   cp /etc/swanctl/swanctl.conf /etc/swanctl/swanctl.conf.bak.$(date +%Y%m%d) 2>/dev/null || true
   cp /etc/strongswan.conf /etc/strongswan.conf.bak.$(date +%Y%m%d) 2>/dev/null || true
   

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

• Validate and load configuration:

   swanctl --load-all
   

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

• Initiate both tunnels:

   swanctl --initiate --child aliyun-vpn-master-child
   swanctl --initiate --child aliyun-vpn-slave-child
   

• Verify tunnel status:

   swanctl --list-sas
   

Phase 8: Verification & Diagnostics

Perform real verification (no simulated data):

Step 8.1: Check Aliyun Tunnel Status

aliyun vpc describe-vpn-connections --region {REGION_ID} --biz-region-id {REGION_ID} --vpn-connection-id {VCO_ID} --cli-query 'VpnConnections.VpnConnection[].TunnelOptionsSpecification.TunnelOptions[].{TunnelId:TunnelId,Status:Status,State:State}' --user-agent AlibabaCloud-Agent-Skills
# Or view full output
aliyun vpc describe-vpn-connections --region {REGION_ID} --biz-region-id {REGION_ID} --vpn-connection-id {VCO_ID} --user-agent AlibabaCloud-Agent-Skills

Expected: Both tunnels have:

• State = active
• Status = ipsec_sa_established (after StrongSwan is configured and started)

Step 8.2: Check Server-side StrongSwan Status

Run on server:

sudo swanctl --list-sas

Expected: Both tunnels show ESTABLISHED.

Alternative detailed view:

sudo swanctl --stats

Step 8.3: Real Connectivity Test

ping -c 5 {VPC_ECS_PRIVATE_IP}

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 = active
• ✅ Dual tunnels both show sa_established
• ✅ Server-side StrongSwan both tunnels ESTABLISHED
• ✅ Bidirectional ping successful (Server ↔ VPC ECS)

Phase 10: Cleanup (Optional)

Delete resources in order (requires explicit user confirmation):

# Step 1: Stop StrongSwan on server
sudo swanctl --terminate --ike aliyun-vpn-master
sudo swanctl --terminate --ike aliyun-vpn-slave
# Step 2: Delete IPsec connection
aliyun vpc delete-vpn-connection --region {REGION_ID} --biz-region-id {REGION_ID} --vpn-connection-id {VCO_ID} --user-agent AlibabaCloud-Agent-Skills
# Step 3: Delete customer gateway
aliyun vpc delete-customer-gateway --region {REGION_ID} --biz-region-id {REGION_ID} --customer-gateway-id {CGW_ID} --user-agent AlibabaCloud-Agent-Skills
# Step 4: Delete VPN gateway
aliyun vpc delete-vpn-gateway --region {REGION_ID} --biz-region-id {REGION_ID} --vpn-gateway-id {VPN_GATEWAY_ID} --user-agent AlibabaCloud-Agent-Skills

Best Practices

• Security: Use strong PSK (min 16 chars, mixed case, numbers, special chars). Rotate regularly.
• High Availability: Deploy dual-tunnel mode with VSwitches across different AZs.
• Encryption Standard: IKEv2 + AES256 + SHA256 + DH Group14 (modp2048).
• Parameter Consistency: All IKE/IPsec params on Aliyun and server side MUST match exactly.
• Firewall Rules: Critical! Allow UDP 500 (IKE), UDP 4500 (NAT-T), ESP protocol (#50).
• Route Management: Always verify routes added after IPsec creation; auto-config may fail.
• Log Analysis: Check both Aliyun tunnel logs and server-side StrongSwan logs when troubleshooting.
• NAT Traversal: If server behind NAT, configure local_addrs=%defaultroute and encap=yes in swanctl.conf.
• 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