Skip to content

Page in progress

This page is being refreshed for v0.5. The conceptual diagrams (data flow, AWS components, routing) are still accurate; some of the inline wsctl commands describe the older v0.4 CLI flow rather than the v0.5 TUI. The Console tour and CLI section are the current sources of truth for day-to-day operations.

System Overview

Waveshift is deployed and managed through the wsctl TUI, which creates a complete AWS-based infrastructure for secure VPN services, containerised workspaces, and GL.iNet router integration.

Architecture Components

Control plane (AWS private subnet)

Orchestrator (t3a.small in v0.5; was t3a.medium in v0.4)

The single EC2 instance that runs the control plane. Responsible for the orchestration API, user management, authentication, and the Web Console.

  • Services: orchestration API, user management, authentication, Web Console
  • Database: PostgreSQL for user data and configuration
  • DNS: waveshift.internal for VPC-internal access
  • Storage: 20 GB EBS volume
  • Network: private subnet

Kasm Workspaces (m6a.2xlarge)

  • Services: Containerized desktop environments
  • Container Runtime: Docker with Kasm containers
  • DNS: kasm.internal for web interface access
  • Storage: 150 GB EBS volume for containers and user data
  • Network: Private subnet (10.0.2.0/24)

Network Infrastructure

VPC Configuration

  • CIDR: 10.0.0.0/16
  • Public Subnet: 10.0.1.0/24 (NAT Gateway, future WireGuard server)
  • Private Subnet: 10.0.2.0/24 (Waveshift, Kasm instances)
  • Internet Gateway: Public subnet internet access
  • NAT Gateway: Private subnet outbound access

DNS and Service Discovery

  • Route53 Private Zone: waveshift.internal
  • Internal Records:
  • waveshift.internal → Waveshift Controller IP
  • kasm.internal → Kasm Workspaces IP
  • VPC DNS: Enabled for internal resolution

Security and Access Control

IAM Roles and Policies

  • Waveshift Controller Role: Comprehensive AWS permissions
  • EC2, IAM, Route53, S3, SSM, VPC full access
  • Kasm Role: EC2 and SSM access for container management
  • Instance Profiles: Attached to respective EC2 instances

Security Groups

  • Waveshift SG: Internal communication, SSH access
  • Kasm SG: Web interface access, internal communication
  • Private SG: Default private subnet security group

API Authentication

  • Generated API Keys: Cryptographically secure keys
  • SSM Storage: Secure parameter store for configuration
  • Service-to-Service: API key-based authentication

Site Network Architecture

Site Configuration

Each site created with wsctl sites includes:

Network Allocation

  • Site 0: 10.8.0.0/24 (Gateway: 10.8.0.1)
  • Site 1: 10.8.1.0/24 (Gateway: 10.8.1.1)
  • Site N: 10.8.N.0/24 (Gateway: 10.8.N.1)

WireGuard Configuration

  • Private/Public Key Pair: Generated per site
  • VPN Tunnel: Site router to Waveshift infrastructure
  • Routing: Site networks routed through Waveshift

GL.iNet Router Integration

Router Configuration (via wsctl configure-hub)

  • DHCP Server: Configured for site network (10.8.X.0/24)
  • WireGuard Client: Connects to Waveshift VPN server
  • Device Scanner: Periodic network scanning and reporting
  • DNS Settings: Points to Waveshift internal DNS

Supported Models

  • GL.iNet Slate (GL-AR750S) - Site routers
  • GL.iNet Brume2 (GL-MT6000) - Main hub routers
  • Other OpenWrt-compatible GL.iNet models

Deployment Flow

Phase 1: Infrastructure Setup (wsctl deploy)

graph TD
    A[wsctl deploy] --> B[VPC Creation]
    B --> C[Subnet Configuration]
    C --> D[Internet/NAT Gateways]
    D --> E[Security Groups]
    E --> F[IAM Roles & Policies]
    F --> G[Route53 Private Zone]
    G --> H[EC2 Instance Launch]
    H --> I[Service Initialisation]
    I --> J[Health Verification]

Phase 2: Site Management (wsctl sites)

graph TD
    A[wsctl sites --add N] --> B[API Registration]
    B --> C[WireGuard Key Generation]
    C --> D[Network Allocation]
    D --> E[Configuration Storage]
    E --> F[Site Ready for Router Config]

Phase 3: Router Configuration (wsctl configure-hub)

graph TD
    A[wsctl configure-hub] --> B[SSH Connection]
    B --> C[DHCP Configuration]
    C --> D[WireGuard Setup]
    D --> E[Device Scanner Install]
    E --> F[Router Reboot]
    F --> G[Site Online]

Data Flow

User Access Pattern

sequenceDiagram
    participant U as User Device
    participant R as GL.iNet Router
    participant W as Waveshift Controller
    participant K as Kasm Workspaces

    U->>R: Connect to Site Network
    R->>W: WireGuard VPN Tunnel
    U->>W: Access waveshift.internal
    U->>K: Access kasm.internal
    K->>W: Authentication via API
    W->>K: User Authorisation

Device Discovery Flow

sequenceDiagram
    participant R as GL.iNet Router
    participant D as Device Scanner
    participant W as Waveshift API

    R->>D: Cron Job Trigger
    D->>D: Network Scan (nmap)
    D->>W: Report Devices (API)
    W->>W: Update Device Inventory

Service Communication

Internal API Communication

Authentication Flow

  • All API calls use generated API key
  • API key stored in SSM Parameter Store
  • Services authenticate via header: X-API-Key

Service Endpoints

  • Orchestration API: https://waveshift.internal/api/
  • User Management: https://waveshift.internal/users/
  • Authentication: https://waveshift.internal/auth/
  • Kasm Interface: https://kasm.internal/

Database Integration

PostgreSQL Configuration

  • Host: Waveshift Controller instance
  • Database: waveshift
  • Tables: Users, Sites, Devices, Sessions
  • Backup: EBS snapshots for persistence

Scalability Considerations

Horizontal Scaling

Multi-Region Deployment 

# Deploy to multiple regions using separate directories
mkdir ~/waveshift-us ~/waveshift-eu ~/waveshift-asia

cd ~/waveshift-us
wsctl init --identity-provider my-provider --profile my-profile --region us-east-1
wsctl deploy

cd ~/waveshift-eu
wsctl init --identity-provider my-provider --profile my-profile --region eu-west-1
wsctl deploy

cd ~/waveshift-asia
wsctl init --identity-provider my-provider --profile my-profile --region ap-southeast-1
wsctl deploy

Site Capacity

  • Maximum Sites: 256 per deployment (10.8.0.0/16)
  • Devices per Site: 254 devices (10.8.X.0/24)
  • Total Device Capacity: ~65,000 devices per region

Vertical Scaling

Instance Type Optimisation 

# Larger Kasm instance for more concurrent users
wsctl deploy --kasm-instance-type m6a.4xlarge

# High-memory instance for large user bases
wsctl deploy --kasm-instance-type r6a.2xlarge

Security Architecture

Network Security

Traffic Isolation

  • Private subnets for all services
  • NAT Gateway for outbound-only access
  • Security groups restrict inter-service communication
  • WireGuard encryption for site connections

Access Control

  • No direct internet access to services
  • VPN required for all user access
  • API key authentication for service communication
  • SSH key-based router access (recommended)

Data Security

Encryption

  • In Transit: HTTPS/TLS for all API communication
  • At Rest: EBS volume encryption available
  • VPN: WireGuard encryption for site tunnels
  • Configuration: SSM Parameter Store encryption

Key Management

  • API Keys: Generated cryptographically secure
  • WireGuard Keys: Per-site key pairs
  • SSH Keys: Router access (user-managed)
  • TLS Certificates: Self-signed for internal services

Monitoring and Observability

Health Monitoring

Service Health Checks

  • HTTP endpoints for service status
  • Database connectivity verification
  • Container runtime status
  • Resource utilisation monitoring

Infrastructure Monitoring

  • EC2 instance health and status
  • VPC network connectivity
  • Route53 DNS resolution
  • Security group compliance

Logging

Service Logs

  • Systemd journal logs for services
  • Docker container logs
  • API access logs
  • Authentication audit logs

Infrastructure Logs

  • CloudTrail for AWS API calls
  • VPC Flow Logs (optional)
  • Route53 query logs (optional)

Disaster Recovery

Backup Strategy

Configuration Backup

  • wsctl.json configuration files
  • Site and user data export
  • WireGuard key backup
  • Database dumps

Infrastructure Recovery

# Restore configuration
cd ~/waveshift-backup
cp backup-wsctl.json wsctl.json

# Redeploy infrastructure
wsctl deploy

# Restore sites
wsctl infrastructure-servers --add N
wsctl sites --add N

# Reconfigure routers
for site in {0..N}; do
  wsctl configure-hub --site $site
done

High Availability Options

Multi-AZ Deployment (Future Enhancement)

  • Deploy across multiple availability zones
  • Load balancer for service distribution
  • Database replication for redundancy

Cross-Region Failover

  • Maintain configurations in multiple regions
  • DNS-based failover routing
  • Automated backup synchronisation

This architecture provides a robust, scalable foundation for secure VPN services with comprehensive management through the wsctl CLI tool.