Load Balancing Tor Hidden Services

OnionBalance runs an aggregated hidden service that distributes connections across multiple backend hidden service instances. Each backend runs its own Tor hidden service. OnionBalance publishes a combined descriptor that combines introduction points from all backends, effectively routing incoming connections to whichever backend's introduction point is selected. Setup: deploy 2-3 backend servers, each running a Tor hidden service. Install OnionBalance on a separate management server (which does not need to be publicly accessible). Configure OnionBalance with the backend .onion addresses. OnionBalance fetches introduction points from each backend and publishes a combined HSv3 descriptor. Clients connecting to the OnionBalance .onion address are routed to one of the backends. Failover: if a backend goes offline, its introduction points are removed from the combined descriptor on the next refresh cycle (typically 10-30 minutes). New connections route to healthy backends. Existing connections to the failed backend are dropped but clients reconnect automatically.

For a single-server setup with multiple application instances, HAProxy distributes connections at the application level. nginx or Tor delivers connections to HAProxy (localhost:80), and HAProxy distributes to backend application instances (localhost:3001, localhost:3002, localhost:3003). HAProxy configuration: frontend section listens on localhost:80, backend section defines upstream servers with health checks. HAProxy supports multiple load balancing algorithms: round-robin (default), least-connections (better for variable request duration), and source-based (uses client IP, but in Tor context all clients appear as 127.0.0.1 - not useful). Use least-connections for HTTP APIs with variable response times. HAProxy provides detailed statistics via a stats page (bind on localhost:8404, accessible via localhost only). Monitor backend health: configure health checks that HAProxy sends to each backend instance to detect failures and remove unhealthy backends from rotation.

Nginx's built-in upstream module provides load balancing without additional software. For multiple application instances on different ports: define an upstream block with multiple server entries: upstream myapp { server 127.0.0.1:3001; server 127.0.0.1:3002; server 127.0.0.1:3003; } and proxy_pass http://myapp in the server block. Nginx supports the least_conn directive for least-connections load balancing. Enable health checks with the nginx_upstream_check_module (community module) or use nginx's commercial-only upstream health check. For open-source nginx: implement health checks via a separate script that monitors backend health and updates nginx's configuration dynamically (nginx -s reload after configuration updates). Nginx upstream configuration is simpler than HAProxy for basic use cases but less feature-rich for complex health check requirements.

Session affinity (sticky sessions) routes a client's repeated requests to the same backend instance, enabling server-side session storage on a single instance. Standard sticky session methods use client IP hash - but all Tor clients appear as 127.0.0.1 (via localhost delivery from Tor), making IP-based affinity useless. Solutions: (1) Cookie-based affinity: nginx's sticky module or HAProxy's cookie-based persistence inserts a cookie identifying the backend instance. The client's cookie routes future requests to the same backend. This works if the client accepts cookies and Tor Browser does not clear cookies between requests. (2) Shared session store: store sessions in a shared Redis instance (localhost) accessible by all backend instances. No affinity needed - any backend can handle any request by looking up the session in Redis. Option 2 is strongly preferred: it is more resilient (backend can change without losing session) and works regardless of client cookie behavior.

Load balancing enables zero-downtime deployments. With 3 backend instances: remove instance-1 from the load balancer rotation (send minimal traffic or mark as draining in HAProxy/nginx), deploy new code to instance-1, verify instance-1 is healthy, return instance-1 to rotation, repeat for instance-2 and instance-3. This process ensures at least 2 of 3 instances serve traffic during the deployment. Implementation with HAProxy: use the admin socket to dynamically mark servers as drain or maint mode (echo disable server myapp/server1 | socat unix-connect:/var/run/haproxy/admin.sock -). With nginx: remove a server from the upstream block and reload nginx (nginx -s reload, a zero-downtime operation). For OnionBalance multi-server: update one backend server at a time, verifying health after each update before proceeding to the next.