Simple VPN Manager

A streamlined command-line tool to deploy and manage WireGuard VPN servers on AWS using CloudFormation.

Features

• 🌍 Global Deployment: Deploy VPN servers in any AWS region automatically
• ☁️ CloudFormation-Based: Reliable Infrastructure as Code management
• 🔐 WireGuard Protocol: Fast, secure, modern VPN technology
• 🔑 Secure Key Exchange: Uses AWS SSM Parameter Store
• 🧹 Automatic Cleanup: Built-in resource management and error recovery
• 🛡️ Security First: Minimal permissions and secure defaults
• 💰 Cost Effective: Uses t3.micro instances (~$0.0104/hour)
• 🔄 Multi-Region: Automatically uses latest Ubuntu AMI for each region

Prerequisites

1. AWS Account: You'll need an AWS account with appropriate permissions

2. AWS CLI configured:

   aws configure

   Configure with credentials that have CloudFormation, EC2, IAM, and SSM permissions

3. WireGuard installed locally (for automatic connection):

   # macOS
   brew install wireguard-tools
   
   # Ubuntu/Debian
   sudo apt install wireguard
   
   # Other systems: https://www.wireguard.com/install/

4. Node.js 18+:

   node --version  # Should be 18.0.0 or higher

5. jq (for JSON parsing in setup scripts):

   # macOS
   brew install jq
   
   # Ubuntu/Debian
   sudo apt install jq

Installation

1. Install dependencies:

   npm install

2. Test the installation:

   npm test

3. Validate CloudFormation template:

   npm run validate              # Test multiple regions
   npm run validate us-west-2    # Test specific region

4. Make CLI available globally (optional):

   npm link

Usage

Start the VPN manager:

npm start
# or if linked globally:
vpn

Main Menu Options

• 🚀 Deploy VPN Server: Choose a region and deploy a new VPN server
• 📋 Check Status: View current VPN server and connection status
• 🛑 Disconnect & Cleanup: Terminate the VPN server and clean up resources
• ❌ Exit: Exit the program

Deployment Process

1. Select an AWS region from the list
2. Generate WireGuard encryption keys
3. Deploy CloudFormation stack with EC2 instance
4. Wait for server setup to complete (2-3 minutes)
5. Retrieve server configuration from SSM
6. Connect to the VPN automatically (optional)

Safety Features

• Graceful Shutdown: Pressing Ctrl+C disconnects VPN and preserves server
• Error Recovery: Automatic cleanup of failed deployments
• Resource Management: Prevents resource leaks with proper cleanup
• Secure Credentials: No credentials stored on VPN servers

How It Works

1. CloudFormation Deployment: Uses Infrastructure as Code for reliable deployment
2. Key Generation: Creates WireGuard key pairs for secure communication
3. Stack Creation: Deploys complete infrastructure (EC2, Security Groups, IAM roles)
4. SSM Integration: Secure key exchange via AWS Systems Manager Parameter Store
5. Auto-Configuration: Server configures itself and signals completion to CloudFormation
6. Client Connection: Retrieves server config from SSM and connects automatically

AWS Permissions Required

Your AWS credentials need these permissions:

• CloudFormation: cloudformation:* (for stack management)
• EC2: ec2:* (for instances, security groups, key pairs)
• SSM: ssm:GetParameter, ssm:PutParameter, ssm:DeleteParameter
• IAM: iam:CreateRole, iam:AttachRolePolicy, iam:PassRole

Alternatively, use the PowerUserAccess managed policy for full functionality.

Configuration

Configuration is stored in .config/config.json and includes:

• Recent regions list
• Auto-termination timeout (default: 1 hour)
• Maximum recent regions to remember (default: 5)

Troubleshooting

"AWS credentials not configured"

Run aws configure and enter your AWS access key and secret key.

"WireGuard is not installed"

Install WireGuard tools for your operating system. The server will still be created, but automatic connection won't work.

"Stack failed: VPNInstance creation failed"

This usually means AMI or region issues:

• Ensure you're using the latest version with dynamic AMI resolution
• Try a different region (some regions may have temporary capacity issues)
• Check AWS service status for your region

"Failed to launch instance"

Check that your AWS credentials have the required permissions and that the selected region is available.

Instance not responding

Wait a few minutes for the server to fully initialize. The user-data script needs time to install and configure WireGuard.

Multi-Region Compatibility

The VPN manager now automatically selects the correct Ubuntu 22.04 LTS AMI for each region using AWS Systems Manager Parameter Store. No manual AMI ID updates needed!

Cost Information

• Instance cost: ~$0.005/hour (t3.nano)
• Data transfer: Standard AWS rates apply
• Auto-termination: Prevents forgotten instances from running indefinitely
• Typical session: Less than $0.01 for a 1-hour VPN session

Security Notes

• Uses WireGuard with modern cryptography (Curve25519, ChaCha20, Poly1305)
• Temporary key pairs generated for each session
• Security groups restrict access to VPN port only
• No persistent credentials stored on servers
• Automatic cleanup prevents resource leaks

Manual Connection

If automatic connection fails, you can connect manually:

# The client config is saved to /tmp/vpn-client.conf
sudo wg-quick up /tmp/vpn-client.conf

# To disconnect:
sudo wg-quick down /tmp/vpn-client.conf

Cleanup

To remove the AWS IAM user and policy when you're done:

./scripts/cleanup-aws-user.sh

This will delete:

• The vpn-manager-user IAM user
• The VPNManagerPolicy policy
• All associated access keys

Scripts Reference

• ./scripts/setup-aws-user.sh - Create IAM user and configure AWS CLI
• ./scripts/verify-aws-setup.sh - Verify all prerequisites are installed
• ./scripts/cleanup-aws-user.sh - Remove IAM user and policy
• npm test - Test VPN Manager components
• npm start - Start the VPN Manager CLI

License

MIT License - see LICENSE file for details.