VPN Exit Controller API Documentation¶

Overview¶

The VPN Exit Controller API provides comprehensive management of multi-node VPN exit points with intelligent load balancing, monitoring, and failover capabilities. The system uses FastAPI and runs on port 8080.

Base URL: http://10.10.10.20:8080 (Container IP) or http://100.73.33.11:8080 (Tailscale IP)
API Version: 2.0.0
Interactive Documentation: /docs (Swagger UI) or /redoc (ReDoc)

Authentication¶

All API endpoints require HTTP Basic Authentication.

Default Credentials: - Username: admin - Password: Bl4ckMagic!2345erver

Environment Variables: - ADMIN_USER: Override default username - ADMIN_PASS: Override default password

Authentication Examples¶

# Using curl with basic auth
curl -u admin:Bl4ckMagic!2345erver http://localhost:8080/api/nodes

# Using curl with explicit header
curl -H "Authorization: Basic YWRtaW46Qmw0Y2tNYWdpYyEyMzQ1ZXJ2ZXI=" http://localhost:8080/api/nodes

Core API Endpoints¶

1. Node Management APIs¶

List All Nodes¶

GET /api/nodes

Lists all VPN nodes and their current status.

Response:

[
  {
    "id": "vpn-us-1234567890ab",
    "country": "us",
    "status": "running",
    "vpn_server": "us5063.nordvpn.com",
    "tailscale_hostname": "vpn-us-node-1",
    "started_at": "2025-01-15T10:30:00Z",
    "vpn_connected": true,
    "tailscale_connected": true
  }
]

Start Node¶

POST /api/nodes/{country_code}/start

Starts a new VPN node for the specified country.

Parameters: - country_code (path): ISO 3166-1 alpha-2 country code (e.g., "us", "uk", "de") - server (query, optional): Specific VPN server to use

Example:

curl -X POST -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/nodes/us/start?server=us5063.nordvpn.com"

# Start UK node
curl -X POST -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/nodes/uk/start"

Response:

{
  "status": "starting",
  "node_id": "vpn-us-1234567890ab",
  "country": "us",
  "server": "us5063.nordvpn.com"
}

Stop Node¶

DELETE /api/nodes/{node_id}/stop

Stops and removes a specific VPN node.

Example:

curl -X DELETE -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/nodes/vpn-us-1234567890ab/stop

Restart Node¶

POST /api/nodes/{node_id}/restart

Restarts a specific VPN node.

Example:

curl -X POST -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/nodes/vpn-us-1234567890ab/restart

Get Node Details¶

GET /api/nodes/{node_id}

Gets detailed information about a specific node.

Response:

{
  "id": "vpn-us-1234567890ab",
  "country": "us",
  "status": "running",
  "container_info": {
    "created": "2025-01-15T10:30:00Z",
    "ports": {"1080/tcp": [{"HostPort": "31080"}]},
    "environment": ["COUNTRY=us", "VPN_SERVER=us5063.nordvpn.com"]
  },
  "vpn_connected": true,
  "tailscale_connected": true
}

Get Node Logs¶

GET /api/nodes/{node_id}/logs?lines=100

Retrieves logs from a specific node.

Parameters: - lines (query): Number of log lines to retrieve (1-1000, default: 100)

Check Node Health¶

GET /api/nodes/{node_id}/health

Checks the health status of a specific node.

Response:

{
  "node_id": "vpn-us-1234567890ab",
  "healthy": true,
  "message": "VPN and Tailscale connections active"
}

Cleanup Stopped Containers¶

POST /api/nodes/cleanup

Removes all stopped VPN containers.

Response:

{
  "status": "completed",
  "removed_containers": 3
}

2. Load Balancing APIs¶

Get Load Balancing Statistics¶

GET /api/load-balancer/stats

Returns current load balancing statistics and connection counts.

Response:

{
  "total_nodes": 5,
  "connections_per_node": {
    "vpn-us-1234567890ab": 12,
    "vpn-uk-2345678901bc": 8
  },
  "strategy": "health_score",
  "last_updated": "2025-01-15T10:30:00Z"
}

Get Best Node for Country¶

GET /api/load-balancer/best-node/{country}?strategy=health_score

Selects the optimal node for a country using the specified load balancing strategy.

Parameters: - strategy (query): Load balancing strategy - health_score (default): Best overall health score - least_connections: Fewest active connections - round_robin: Even distribution - weighted_latency: Latency-based with randomization - random: Random selection

Example:

curl -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/load-balancer/best-node/us?strategy=least_connections"

# Get best UK node
curl -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/load-balancer/best-node/uk?strategy=health_score"

Response:

{
  "selected_node": {
    "id": "vpn-us-1234567890ab",
    "country": "us",
    "proxy_url": "socks5://10.10.10.20:31080",
    "health_score": 95.2,
    "connections": 5
  },
  "strategy": "least_connections",
  "country": "us"
}

Scale Up Country¶

POST /api/load-balancer/scale-up/{country}

Starts additional nodes if needed based on current load.

Scale Down Country¶

POST /api/load-balancer/scale-down/{country}

Stops excess nodes if load is low.

Get Available Strategies¶

GET /api/load-balancer/strategies

Lists all available load balancing strategies with descriptions.

3. Speed Testing APIs¶

Test Node Speed¶

POST /api/speed-test/{node_id}?test_size=1MB&run_in_background=false

Runs a speed test on a specific node.

Parameters: - test_size (query): Test size ("1MB" or "10MB") - run_in_background (query): Run asynchronously (default: false)

Example:

curl -X POST -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/speed-test/vpn-us-1234567890ab?test_size=10MB"

Response:

{
  "node_id": "vpn-us-1234567890ab",
  "success": true,
  "download_mbps": 95.2,
  "upload_mbps": 45.6,
  "latency_ms": 23.4,
  "test_size": "10MB",
  "duration_seconds": 12.3,
  "tested_at": "2025-01-15T10:30:00Z"
}

Test All Nodes¶

POST /api/speed-test/all?test_size=1MB&run_in_background=true

Runs speed tests on all active nodes.

Get Latest Speed Test¶

GET /api/speed-test/{node_id}/latest

Gets the most recent speed test result for a node.

Get Speed Test History¶

GET /api/speed-test/{node_id}/history?hours=24

Gets speed test history for a node.

Parameters: - hours (query): Hours of history to retrieve (1-168, default: 24)

Get Speed Test Summary¶

GET /api/speed-test/summary

Gets a summary of all speed test results across all nodes.

Get Country Speed Tests¶

GET /api/speed-test/country/{country}

Gets latest speed test results for all nodes in a specific country.

Response:

{
  "country": "us",
  "node_count": 3,
  "tested_nodes": 3,
  "successful_tests": 2,
  "avg_download_mbps": 87.5,
  "avg_latency_ms": 25.2,
  "results": {
    "vpn-us-1234567890ab": {
      "success": true,
      "download_mbps": 95.2,
      "latency_ms": 23.4
    }
  }
}

Clear Speed Test Results¶

DELETE /api/speed-test/{node_id}/results

Clears stored speed test results for a node.

4. Metrics and Monitoring APIs¶

Get Node Metrics¶

GET /api/metrics/{node_id}?period=1h

Gets historical metrics for a specific node.

Parameters: - period (query): Time period ("1h", "6h", "24h", "7d")

Response:

[
  {
    "timestamp": "2025-01-15T10:30:00Z",
    "cpu_percent": 15.2,
    "memory_mb": 256.8,
    "network_rx_mb": 12.4,
    "network_tx_mb": 8.9,
    "active_connections": 5,
    "vpn_connected": true
  }
]

Get Current Node Metrics¶

GET /api/metrics/{node_id}/current

Gets current real-time metrics for a specific node.

Get All Metrics¶

GET /api/metrics/

Gets current metrics for all active nodes.

Trigger Metrics Collection¶

POST /api/metrics/collect

Manually triggers metrics collection across all nodes.

Get Metrics Summary¶

GET /api/metrics/stats/summary

Gets aggregated statistics across all nodes.

Response:

{
  "total_nodes": 5,
  "healthy_nodes": 4,
  "unhealthy_nodes": 1,
  "total_cpu_percent": 62.8,
  "avg_cpu_percent": 12.6,
  "total_memory_mb": 1280.4,
  "avg_memory_mb": 256.1,
  "total_network_rx_mb": 45.6,
  "total_network_tx_mb": 32.1,
  "timestamp": "2025-01-15T10:30:00Z"
}

5. Proxy Management APIs¶

Get All Proxy URLs¶

GET /api/proxy/urls

Gets all available proxy URLs organized by country.

Response:

id=__codelineno-17-1 name=__codelineno-17-1 href=#__codelineno-17-1>{ "us": [ { "node_id": "vpn-us-1234567890ab", "tailscale_ip": "100.86.140.98", "proxy_urls": { "http": "http://100.86.140.98:3128", "socks5": "socks5://100.86.140.98:1080", "health": "http://100.86.140.98:8080/health" }, "health_score": 95.2 } ], "uk": [ { "node_id": "vpn-uk-2345678901bc", "tailscale_ip": "100.125.27.111", "proxy_urls": { "http": "http://100.125.27.111:3128", "socks5": "socks5://100.125.27.111:1080", "health": "http://100.125.27.111:8080/health" }, "health_score": 88.1 } ] class=p>}

Get Country Proxy URLs¶

GET /api/proxy/urls/{country}

Gets proxy URLs for a specific country.

Get Optimal Proxy¶

GET /api/proxy/optimal/{country}?strategy=health_score

Gets the optimal proxy endpoint for a country using load balancing.

Response:

{
  "node_id": "vpn-us-1234567890ab",
  "country": "us",
  "tailscale_ip": "100.86.140.98",
  "proxy_urls": {
    "http": "http://100.86.140.98:3128",
    "socks5": "socks5://100.86.140.98:1080",
    "health": "http://100.86.140.98:8080/health"
  },
  "health_score": 95.2,
  "connections": 5,
  "strategy": "health_score"
}

Release Proxy Connection¶

POST /api/proxy/release/{node_id}

Decrements the connection count for a proxy (for connection tracking).

Get Proxy Statistics¶

GET /api/proxy/stats

Gets proxy system statistics and usage information.

Update HAProxy Configuration¶

POST /api/proxy/config/update

Updates and reloads HAProxy configuration based on current nodes.

Generate HAProxy Configuration¶

GET /api/proxy/config/generate

Generates HAProxy configuration preview without applying changes.

Check Proxy Health¶

GET /api/proxy/health

Comprehensive health check of the proxy system and all nodes.

6. Failover Management APIs¶

Get Failover Status¶

GET /api/failover/status

Gets current failover status and history.

Response:

{
  "enabled": true,
  "total_failovers": 12,
  "last_failover": "2025-01-15T09:45:00Z",
  "failover_history": {
    "vpn-us-1234567890ab": [
      {
        "timestamp": "2025-01-15T09:45:00Z",
        "reason": "VPN connection lost",
        "action": "restart",
        "success": true
      }
    ]
  }
}

Trigger Failover¶

POST /api/failover/{node_id}/trigger?reason=Manual+trigger

Manually triggers failover for a specific node.

Check All Nodes¶

POST /api/failover/check-all

Checks all nodes and triggers failover for unhealthy ones.

Get Node Failover History¶

GET /api/failover/history/{node_id}

Gets failover history for a specific node.

7. Configuration APIs¶

Get Available Countries¶

GET /api/config/countries

Lists all countries with available VPN configurations.

Response:

["us", "uk", "de", "jp", "ca", "au", "nl", "ch", "sg", "fr", "it", "es", "pl"]

Get Country Servers¶

GET /api/config/servers/{country_code}

Gets all available VPN servers for a specific country.

Response:

[
  {
    "hostname": "us5063.nordvpn.com",
    "country": "us",
    "health_score": 95.2,
    "last_tested": "2025-01-15T10:00:00Z",
    "avg_latency": 23.4,
    "is_blacklisted": false
  }
]

Get All Servers¶

GET /api/config/servers

Gets all available servers grouped by country.

Health Check Server¶

POST /api/config/servers/{hostname}/health-check

Runs a health check on a specific VPN server.

Health Check All Servers¶

POST /api/config/servers/health-check-all?country_code=us

Runs health checks on all servers (optionally filtered by country).

Blacklist Server¶

POST /api/config/servers/{hostname}/blacklist?duration_hours=1

Temporarily blacklists a server from being used.

Get Server Statistics¶

GET /api/config/server-stats

Gets statistics about available servers and their health.

8. Event System APIs¶

Get Recent Events¶

GET /api/events?count=50

Gets recent system events.

Parameters: - count (query): Number of events to retrieve (1-500, default: 50)

Response:

[
  {
    "timestamp": "2025-01-15T10:30:00Z",
    "type": "node_started",
    "node_id": "vpn-us-1234567890ab",
    "country": "us",
    "message": "VPN node started successfully"
  },
  {
    "timestamp": "2025-01-15T10:25:00Z",
    "type": "speed_test_completed",
    "node_id": "vpn-uk-2345678901bc",
    "result": "95.2 Mbps download"
  }
]

Get Events by Type¶

GET /api/events/types/{event_type}?count=20

Gets recent events of a specific type.

Event Types: - node_started - node_stopped - node_failed - speed_test_completed - failover_triggered - health_check_failed

Get Container Events¶

GET /api/events/container/{container_id}?count=20

Gets recent events for a specific container/node.

9. Authentication APIs¶

POST /api/auth/login

Authenticates and returns a JWT token (uses HTTP Basic Auth).

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-01-16T10:30:00Z",
  "user": "admin"
}

10. System APIs¶

Root Dashboard¶

GET /

Returns an HTML dashboard for managing VPN nodes through a web interface.

Health Check¶

GET /health

Basic health check endpoint.

Response:

{
  "status": "healthy",
  "version": "2.0.0"
}

Error Handling¶

The API uses standard HTTP status codes:

200: Success
400: Bad Request (invalid parameters)
401: Unauthorized (authentication required)
404: Not Found (resource doesn't exist)
500: Internal Server Error

Error Response Format:

{
  "detail": "Error message describing what went wrong"
}

Rate Limiting¶

No explicit rate limiting is currently implemented, but it's recommended to: - Limit speed tests to avoid system overload - Space out health checks appropriately - Use background execution for long-running operations

WebSocket Endpoints¶

Currently, no WebSocket endpoints are implemented. All communication is via REST API with periodic polling recommended for real-time updates.

Practical Use Cases¶

Starting a VPN Node¶

# Start a US node
curl -X POST -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/nodes/us/start

# Start a UK node
curl -X POST -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/nodes/uk/start

# Check if they're running
curl -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/nodes

Using Modern Proxy Architecture¶

# Get best US proxy using health score
curl -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/proxy/optimal/us?strategy=health_score"

# Get best UK proxy
curl -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/proxy/optimal/uk?strategy=health_score"

# Example response with new proxy ports:
# {
#   "node_id": "vpn-us-1234567890ab",
#   "country": "us",
#   "tailscale_ip": "100.86.140.98",
#   "proxy_urls": {
#     "http": "http://100.86.140.98:3128",
#     "socks5": "socks5://100.86.140.98:1080",
#     "health": "http://100.86.140.98:8080/health"
#   },
#   "strategy": "health_score"
# }

# Use the returned proxy URLs with your application:
curl -x http://100.86.140.98:3128 http://ipinfo.io/ip
curl --socks5 100.86.140.98:1080 http://ipinfo.io/ip

# UK proxy usage example:
curl -x http://100.125.27.111:3128 http://ipinfo.io/ip
curl --socks5 100.125.27.111:1080 http://ipinfo.io/ip

Monitoring System Health¶

# Check overall system metrics
curl -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/metrics/stats/summary

# Get recent events
curl -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/events

# Check proxy system health
curl -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/proxy/health

Running Performance Tests¶

# Test all nodes in background
curl -X POST -u admin:Bl4ckMagic!2345erver \
  "http://localhost:8080/api/speed-test/all?run_in_background=true"

# Check results later
curl -u admin:Bl4ckMagic!2345erver \
  http://localhost:8080/api/speed-test/summary

Development Notes¶

The API is built with FastAPI and includes automatic OpenAPI documentation
All endpoints require HTTP Basic Authentication
Background tasks are used for long-running operations like speed tests
Redis is used for caching metrics and events
Docker SDK is used for container management
HAProxy integration provides load balancing capabilities

For interactive API exploration, visit /docs or /redoc endpoints after authentication.

VPN Exit Controller API Documentation¶

Overview¶

Authentication¶

Authentication Examples¶

Core API Endpoints¶

1. Node Management APIs¶

List All Nodes¶

Start Node¶

Stop Node¶

Restart Node¶

Get Node Details¶

Get Node Logs¶

Check Node Health¶

Cleanup Stopped Containers¶

2. Load Balancing APIs¶

Get Load Balancing Statistics¶

Get Best Node for Country¶

Scale Up Country¶

Scale Down Country¶

Get Available Strategies¶

3. Speed Testing APIs¶

Test Node Speed¶

Test All Nodes¶

Get Latest Speed Test¶

Get Speed Test History¶

Get Speed Test Summary¶

Get Country Speed Tests¶

Clear Speed Test Results¶

4. Metrics and Monitoring APIs¶

Get Node Metrics¶

Get Current Node Metrics¶

Get All Metrics¶

Trigger Metrics Collection¶

Get Metrics Summary¶

5. Proxy Management APIs¶

Get All Proxy URLs¶

Get Country Proxy URLs¶

Get Optimal Proxy¶

Release Proxy Connection¶

Get Proxy Statistics¶

Update HAProxy Configuration¶

Generate HAProxy Configuration¶

Check Proxy Health¶

6. Failover Management APIs¶

Get Failover Status¶

Trigger Failover¶

Check All Nodes¶

Get Node Failover History¶

7. Configuration APIs¶

Get Available Countries¶

Get Country Servers¶

Get All Servers¶

Health Check Server¶

Health Check All Servers¶

Blacklist Server¶

Get Server Statistics¶

8. Event System APIs¶

Get Recent Events¶

Get Events by Type¶

Get Container Events¶

9. Authentication APIs¶

Login¶

10. System APIs¶

Root Dashboard¶

Health Check¶

Error Handling¶

Rate Limiting¶

WebSocket Endpoints¶

Practical Use Cases¶

Starting a VPN Node¶

Using Modern Proxy Architecture¶

Monitoring System Health¶

Running Performance Tests¶

Development Notes¶