How Tor Hidden Service Mirrors Are Rotated, From the Operator’s Side

A Tor service that publishes more than one onion address is doing something that looks routine and is, in practice, the result of a small set of operator decisions made over time. This page is about those decisions: what it actually takes to introduce a new address into a published set, retire an old one, and avoid breaking the users who treated the old one as permanent. The user-side habit that follows from these mechanics is the last section, but the mechanics come first because they explain why the habit is what it is.

The descriptor model

Every onion service publishes a small piece of data called a descriptor. The descriptor lists the rendezvous points the service is currently using, signed with the service’s long-term key. Clients fetch the descriptor from a small set of relays called hidden service directories, or HSDirs, which have been elected to that role by the consensus. The HSDirs that hold a given service’s descriptor change over time, by design, so no single set of relays sees the same descriptor for very long.

This descriptor model is what makes mirror rotation possible. To run two onion addresses for the same back end, an operator runs two long-term keypairs, publishes two descriptors, and points the rendezvous points in both descriptors at the same internal service. Two addresses, two descriptors, one service. The clients do not know or care.

The operator’s view of “one back end”

When an operator says “all of our mirrors point to the same back end,” what they usually mean is that the same application process, with the same database, handles requests that come in through any of the published onion addresses. The Tor daemon on the server is configured with multiple HiddenServiceDir entries, each holding a separate keypair, each publishing its own descriptor. Inbound rendezvous connections from any of those keys terminate on the same backend.

For a buyer this means the simple thing: your account, your balance, your message history, your order history is the same no matter which address you came in through. For the operator it means the more involved thing: each address is a separate identity on the Tor network, with its own HSDir publication schedule, its own descriptor revisions, and its own exposure surface. When something goes wrong with one address, it tends to go wrong only on that address.

Why operators rotate

Three pressures push operators to rotate the published set.

The first is sustained denial of service. When one address is under continuous flood, the rendezvous points and the guard relays around it are pressed harder than the others. Latency rises, descriptor publication occasionally fails, the user experience degrades. The healthy path is to spin up a new address on a fresh keypair, publish its descriptor, add it to the published set, and quietly let traffic drift to it as users refresh their bookmarks.

The second is exposure management. Addresses accumulate references over time. They appear in old forum threads, in pasted snippets, in screenshots, in archived versions of indexes. When an operator wants to reduce the surface their service is searchable on, they rotate to a new address and stop publishing the old one. Old references then point at an address that no longer resolves, which is, from the operator’s perspective, exactly what they want.

The third is operational hygiene. Periodically rotating keypairs is a small but real defence against the slow leakage of side-channel information about a service’s infrastructure. It is the kind of practice that does not pay off visibly in any single event and pays off invisibly over the long run.

The staged rotation procedure

A clean rotation is not a single switch. It is a sequence.

The new keypair is generated and the new Tor service is configured. The descriptor publishes. The new address is added to the published mirror set on the operator’s clearnet directory. Existing addresses continue to publish their descriptors normally.

Users see the directory updated. Some of them pick up the new address immediately. Most of them continue using their existing copy of the Primary, because that is what they bookmarked. The new address takes traffic gradually as people refresh.

After some time, the operator declares an address retired. It is removed from the published set on the directory. Its descriptor continues to publish for a grace period, so any user who was mid-session is not abruptly cut off. After the grace period, the service stops accepting rendezvous on that key, and the descriptor publication is allowed to lapse.

The net effect is that the published set always reflects the currently supported addresses, the retiring address has time to drain, and the new address has time to warm up. No user gets stranded as long as they were following the published set.

What goes wrong

The thing that breaks rotation, almost always, is a user who treated a single onion address as permanent. They bookmarked the Primary six months ago. They never visited the published directory after that. They show up after a rotation has completed, paste their saved address, see that it does not resolve, and conclude that the service is down. From the operator’s side, this is the expected price of running an address rotation, and it is the reason every published mirror directory contains a small note telling users to bookmark the directory rather than any individual onion.

A maintained directory that publishes the current set, refreshes when the rotation moves, and clearly labels each entry is the operator’s bridge across this gap. For a worked example of that shape, the Nexus Market directory publishes the current onion set on a single page and updates it as the rotation moves.

The user-side habit that follows

Two habits make all of the above invisible.

First, bookmark the directory, not any individual onion. The directory tracks the rotation. You do not have to.

Second, when an address times out, do not assume the service is down. Open the directory, copy the next address in the published set, and try that one. The site behind each address is the same, and a different network path will often connect when the first one will not.

These two habits absorb the entire mechanics of mirror rotation into a flow that takes seconds. They turn an opaque operator decision into a routine user step. That asymmetry is the whole point of publishing a set rather than a single address: the operator can rotate without coordination, and the user does not have to know anything about the protocol to keep up.

How Tor Hidden Service Mirrors Are Rotated, From the Operator's Side

What it actually takes to introduce a new onion address into a published mirror set, retire an old one, and keep continuity for users. The operator-side mechanics and what they imply for the user-side habit.