OnionBalance Advanced Configuration: Scaling Hidden Services

OnionBalance runs as a management service that aggregates introduction points from multiple backend hidden services into a single descriptor published under the master .onion address. Each backend runs a full Tor instance with its own hidden service address, and OnionBalance fetches their introduction points, combines them, and publishes under the primary address. Clients connecting to the primary address receive introduction points that may route them to any backend. The key insight is that each backend has its own introduction points - OnionBalance selects a subset across backends to include in the aggregated descriptor. The selection algorithm (random, round-robin, or health-weighted) determines load distribution.

OnionBalance does not natively perform health checks on backends. Production deployments need external health checking that feeds into OnionBalance's backend selection. Implement a health check sidecar that periodically checks each backend's .onion address (through a local Tor client) and marks it as healthy or unhealthy. OnionBalance can be controlled through its management interface to add/remove backends dynamically. An alternative pattern is to keep all backends in OnionBalance configuration but ensure unhealthy backends' Tor instances stop advertising their hidden services - if a backend's Tor daemon is stopped, its introduction points expire from the descriptor within minutes, automatically removing them from aggregation.

HTTPS for a hidden service accessed through OnionBalance requires consistent TLS configuration across all backends. Each backend must present the same TLS certificate for the service domain (if using a domain alongside the .onion address) or a self-signed certificate with the .onion address as the subject (supported by Let's Encrypt's ACME for .onion addresses with appropriate verification). Self-signed certificates work for .onion-only services where clients know they're connecting to a trusted .onion address and don't verify clearnet CA trust chains. For services presenting both a clearnet domain and a .onion address, wildcard certificates or SAN certificates covering both are required.

HTTP sessions and stateful applications face a challenge with load-balanced hidden services: different requests from the same user may route to different backends. Solutions include: shared session storage (Redis cluster accessible by all backends), sticky sessions based on a session identifier cookie (configured in Nginx upstream), or stateless application design where all state is client-side (JWT tokens, cookie-based state). For stateless APIs, load balancing across backends works without modification. For stateful applications (shopping carts, authenticated sessions), shared Redis session storage is the most common solution. Configure Redis with appropriate persistence (AOF or RDB) to prevent session loss on Redis restart.

Updating backend software without downtime requires rolling deployments compatible with OnionBalance's architecture. Update one backend at a time: take a backend out of rotation (stop its Tor daemon to allow its introduction points to expire), perform the update, verify the backend is healthy, then re-add it to OnionBalance rotation. This process takes approximately 5-10 minutes per backend due to introduction point expiry times. For zero-downtime deployments with more than 3 backends, the impact on total capacity is acceptable. For critical changes (database schema changes requiring all backends to run the same version), plan maintenance windows or deploy read-only mode during migrations.