[tor-commits] [tor/master] Document more files in the datadirectory.

[nickm at torproject.org]

commit 5641e27ffbd1016ed88e05f10319a2b041b5e167
Author: Nick Mathewson <nickm at torproject.org>
Date:   Mon Jun 19 09:57:57 2017 -0400

    Document more files in the datadirectory.
    
    This improved list comes from the ls -R results that weasel and ln5
    sent me.  Thanks!
---
 changes/more-files |  5 +++--
 doc/tor.1.txt      | 31 ++++++++++++++++++++++++++-----
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/changes/more-files b/changes/more-files
index f416201..861d6a3 100644
--- a/changes/more-files
+++ b/changes/more-files
@@ -1,3 +1,4 @@
   o Documentation:
-    - Document the "sr-random" file and "diff-cache" directory in the Tor
-      data directory.
\ No newline at end of file
+    - Document more of the files in the Tor data directory, including
+      cached-extrainfo, secret_onion_key{,_ntor}.old, hidserv-stats,
+      approved-routers, sr-random, and diff-cache.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 9fd8a97..ff9fba7 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -2687,7 +2687,8 @@ FILES
 __DataDirectory__**/cached-status/**::
     The most recently downloaded network status document for each authority.
     Each file holds one such document; the filenames are the hexadecimal
-    identity key fingerprints of the directory authorities.  Mostly obsolete.
+    identity key fingerprints of the directory authorities.  Obsolete;
+    no longer in use.
 
 __DataDirectory__**/cached-certs**::
     This file holds downloaded directory key certificates that are used to
@@ -2703,6 +2704,13 @@ __DataDirectory__**/cached-descriptors** and **cached-descriptors.new**::
     a given router. The ".new" file is an append-only journal; when it gets
     too large, all entries are merged into a new cached-descriptors file.
 
+__DataDirectory__**/cached-extrainfo** and **cached-extrainfo.new**::
+   As "cached-descriptors", but holds optionally-downloaded "extra-info"
+   documents. Relays use these documents to send inessential information
+   about statistics, bandwidth history, and network health to the
+   authorities. They aren't fetched by default; see the DownloadExtraInfo
+   option for more info.
+
 __DataDirectory__**/cached-microdescs** and **cached-microdescs.new**::
     These files hold downloaded microdescriptors.  Lines beginning with
     @-signs are annotations that contain more information about a given
@@ -2809,13 +2817,17 @@ __DataDirectory__**/keys/ed25519_signing_cert**::
     The certificate which authenticates "ed25519_signing_secret_key" as
     having been signed by the Ed25519 master key.
 
-__DataDirectory__**/keys/secret_onion_key**::
+__DataDirectory__**/keys/secret_onion_key** and **secret_onion_key.old**::
     A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP")
-    circuit extension requests.
+    circuit extension requests. The ".old" file holds the previously
+    generated key, which the relay uses to handle any requests that were
+    made by clients that didn't have the new one.
 
-__DataDirectory__**/keys/secret_onion_key_ntor**::
+__DataDirectory__**/keys/secret_onion_key_ntor** and **secret_onion_key_ntor.old**::
     A relay's Curve25519 short-term onion key. Used to handle modern ("ntor")
-    circuit extension requests.
+    circuit extension requests. The ".old" file holds the previously
+    generated key, which the relay uses to handle any requests that were
+    made by clients that didn't have the new one.
 
 __DataDirectory__**/fingerprint**::
     Only used by servers. Holds the fingerprint of the server's identity key.
@@ -2870,11 +2882,20 @@ __DataDirectory__**/stats/conn-stats**::
     Only used by servers. This file is used to collect approximate connection
     history (number of active connections over time).
 
+__DataDirectory__**/stats/hidserv-stats**::
+    Only used by servers. This file is used to collect approximate counts
+    of what fraction of the traffic is hidden service rendezvous traffic, and
+    approximately how many hidden services the relay has seen.
+
 __DataDirectory__**/networkstatus-bridges**::
     Only used by authoritative bridge directories. Contains information
     about bridges that have self-reported themselves to the bridge
     authority.
 
+__DataDirectory__**/approved-routers**::
+    Authorities only. This file is used to configure which relays are
+    known to be valid, invalid, and so forth.
+
 __HiddenServiceDirectory__**/hostname**::
     The <base32-encoded-fingerprint>.onion domain name for this hidden service.
     If the hidden service is restricted to authorized clients only, this file