Tor Hidden Service Descriptor Publishing and Reachability Verification

When a hidden service starts, it establishes introduction point circuits to introduction point relays. It then builds a descriptor - a signed document containing the introduction point information and the service's public key - and publishes this descriptor to approximately 20 hidden service directory (HSDir) relays. The specific HSDirs chosen are determined by the service's address and the current consensus, using a distributed hash table approach. Clients looking up a .onion address query the same HSDirs to retrieve the descriptor, learn the introduction points, and build a rendezvous circuit. The entire process happens automatically, but failures at any step make the service unreachable.

Check Tor logs for successful descriptor publication: look for 'Introduction circuit established' messages followed by 'Uploaded rendezvous descriptor successfully' at the INFO log level. In torrc, set Log notice file /var/log/tor/tor.log; set SafeLogging to 0 temporarily during debugging. Use the stem Python library to query the control port: circuit status should show IS_circuits (Introduction circuit) in the BUILT state. Online tools like Onion Check (onioncheck.onion.ly) can verify if a descriptor is reachable from the public Tor network. For v3 hidden services, the descriptor is hosted on 20 HSDirs with periodic rotation - verification should confirm at least 1-2 of these are responding with valid descriptors.

Descriptor publication failures have several common causes. Clock skew: if the server's system clock is more than 60 seconds off, descriptor signatures are rejected by HSDirs. Configure NTP (ntpd or chrony) on the server. Firewall blocking Tor's outbound connections: Tor needs to reach relays on port 9001/443 and HSDirs. Test with curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org/. Insufficient relays in consensus: if the Tor daemon cannot load a consensus, it cannot determine which HSDirs to publish to. Check bootstrap status with GETINFO status/bootstrap-phase. v2 vs v3 descriptor versions: ensure you are running a current Tor version that supports v3 descriptors (v2 is deprecated and removed in Tor 0.4.6+).

Introduction point circuits are the persistent connection between your hidden service and its introduction points. Each v3 hidden service maintains 3-10 introduction points (configurable with HiddenServiceNumIntroductionPoints). Introduction circuits are rebuilt periodically and when the introduction point relay changes status. A healthy service maintains all configured introduction points active simultaneously. Monitor introduction circuit count through the control port. If introduction circuits repeatedly fail to establish, check: whether the target relays are online (consult Tor Metrics), whether your network allows outbound connections to arbitrary Tor relays, and whether the Tor process has sufficient file descriptors.

During Tor daemon startup, bootstrap must complete before descriptor publishing begins. The bootstrap process fetches directory information and builds initial circuits - this takes 30-120 seconds under normal conditions. If bootstrap fails or takes extremely long, descriptor publishing is delayed. Check bootstrap status with control port command GETINFO status/bootstrap-phase - it should reach 100% quickly. Persistent bootstrap issues suggest network connectivity problems (firewalls blocking Tor ports), clock skew preventing valid consensus acceptance, or DNS resolution failures preventing Tor from reaching bootstrap servers. Using configured bridges (if in a censored environment) requires the bridge to be responsive before bootstrap completes.