Documentation, improve directory authority server section in man pages
Summary
The current documentation given for directory authority server and related options is a bit confusing and doesn't provide any information about whether or not users can "help the public tor network" by running their own directory server. Also other sources (e.g. search results, including mailing list and blog posts) are not really helpful about this, as there have been some changes and it is not clear if the provided information is still correct. Especially because some sources claim that it isn't used at all in newer tor versions (which is probably either over simplified, a misunderstanding or just wrong). Also the current wording of the explanations for the config options is open for interpretation at some important points and probably needs a minor improvement.
Especially to newer users this situation can be somewhat confusing.
Initially I wanted to directly make a MR with an improved version like this:
DIRECTORY AUTHORITY SERVER OPTIONS The following options enable operation as a directory authority, and control how Tor behaves as a directory authority. You
should not needonly need to adjust any of them ifyou’re running ayou want to have a separate independent
private "fork" of the Tor network (e.g. for a local lab environment) or
if you're one of the trusted operators of one of the hard coded directory authority
servers. These options are NOT needed for running a regular relay or exit server on the public Tor network.AuthoritativeDirectory 0|1 When this option is set to 1, Tor operates as an authoritative directory server. Instead of caching the directory, it generates its own list of good servers, signs it, and sends that to the clients.
Unless the clients already have you listed as a trusted directory, you probably do not want to set this option.See DirAuthority for information about how to configure a client to use and trust this directory server.BridgeAuthoritativeDir 0|1 When this option is set in addition to AuthoritativeDirectory, Tor accepts and serves server descriptors, but it caches and serves the main networkstatus documents rather than generating its own. (Default: 0)
But then I got stuck at the ambiguously for the use and purpose of "BridgeAuthoritativeDir" myself.
Does this mean:
a) when AuthoritativeDirectory
and BridgeAuthoritativeDir
are both enabled a node indeed would "helps the public Tor network" by being part of a kind of "decentralized CDN" serving a copy of the data from the hard coded directory authority servers? If yes, how does e.g. the node discovery work? I.E. how do clients get to know about these? And is this something like Kademlia-DHT, peerlist-exchange with torrents, or a form of rsync/replication? (possible use case to reduce the load on the authoritative directory servers and improve response time by having a big distributed swarm of nodes to choose from)
b) It provides a private/internal authoritative directory, but instead of starting with an empty directory it'll start with a clone of the public one. But won't be known to anything on the public network and needs to be explicitly configured using DirAuthority in the client side configuration. (possible use case could be some service provider style hidden service deployment or something)
c) Something else entirely?
A would make sense. But having it disabled by default and no mention within the relay operators guide kinda speaks against it. It could be B, but it would be an odd design choice compared to using A.
But what still doesn't add up is some sources are talking about all directory authority servers being selected and governed by a distributed decentralized consensus based system. But I simultaneously other sources say that the authoritative directory servers for the public Tor network are hard coded, so...
Also the man page for the FallbackDir
option implies that Tor has some kind of discovery algorithm for such cache nodes. But then why wouldn't it be mentioned in the relay operators guide at all?
Tl;Dr: I still don't quite understand this config item. Could someone please help to reword it to something less confusing?