Skip to content

Under Construction

This section is currently being developed and may be incomplete/outdated.

System Overview

Waveshift is deployed and managed through the wavectl CLI tool, which creates a complete AWS-based infrastructure for secure VPN services, containerized workspaces, and GL.iNet router integration.

Architecture Components

Control Plane (AWS Private Subnet)

Waveshift Controller (t3a.medium)

  • Services: Orchestration API, User Management, Authentication
  • Database: PostgreSQL for user data and configuration
  • DNS: waveshift.internal for internal access
  • Storage: 20 GB EBS volume
  • Network: Private subnet (10.0.2.0/24)

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 wavectl 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 wavectl 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 (wavectl deploy)

graph TD
    A[wavectl 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 (wavectl sites)

graph TD
    A[wavectl 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 (wavectl configure-hub)

graph TD
    A[wavectl 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
wavectl init --identity-provider my-provider --profile my-profile --region us-east-1
wavectl deploy

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

cd ~/waveshift-asia
wavectl init --identity-provider my-provider --profile my-profile --region ap-southeast-1
wavectl 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
wavectl deploy --kasm-instance-type m6a.4xlarge

# High-memory instance for large user bases
wavectl 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

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

Infrastructure Recovery

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

# Redeploy infrastructure
wavectl deploy

# Restore sites
wavectl access-servers --add N
wavectl sites --add N

# Reconfigure routers
for site in {0..N}; do
  wavectl 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 wavectl CLI tool.