commit e8fe6bd8d6ddfe5df0cd1a67aa4e7a4bf91976cf Author: Taylor Yu catalyst@torproject.org Date: Mon Oct 21 15:40:18 2019 -0500
Reword FILES section of tor.1.txt
Reword the FILES section of tor.1.txt. Based on a patch by Swati Thacker.
Part of #32176. --- doc/tor.1.txt | 181 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 89 insertions(+), 92 deletions(-)
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 750c7fbe0..97900dc3f 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -3392,7 +3392,7 @@ FILES -----
**@CONFDIR@/torrc**:: - The configuration file, which contains "option value" pairs. + Default location of the configuration file.
**$HOME/.torrc**:: Fallback location for torrc, if @CONFDIR@/torrc is not found. @@ -3402,164 +3402,160 @@ FILES
__CacheDirectory__**/cached-certs**:: - This file holds downloaded directory key certificates that are used to - verify authenticity of documents generated by Tor directory authorities. + Contains downloaded directory key certificates that are used to verify + authenticity of documents generated by the Tor directory authorities.
__CacheDirectory__**/cached-consensus** and/or **cached-microdesc-consensus**:: The most recent consensus network status document we've downloaded.
__CacheDirectory__**/cached-descriptors** and **cached-descriptors.new**:: - These files hold downloaded router statuses. Some routers may appear more - than once; if so, the most recently published descriptor is used. Lines - beginning with @-signs are annotations that contain more information about - 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. + These files contain the downloaded router statuses. Some routers may appear + more than once; if so, the most recently published descriptor is + used. Lines beginning with **`@`**-signs are annotations that contain more + information about 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.
__CacheDirectory__**/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. + Similar to **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 information.
__CacheDirectory__**/cached-microdescs** and **cached-microdescs.new**:: These files hold downloaded microdescriptors. Lines beginning with - @-signs are annotations that contain more information about a given - router. The ".new" file is an append-only journal; when it gets too + **`@`**-signs are annotations that contain more information about a given + router. The **`.new`** file is an append-only journal; when it gets too large, all entries are merged into a new cached-microdescs file.
__DataDirectory__**/state**:: - A set of persistent key-value mappings. These are documented in - the file. These include: - - The current entry guards and their status. - - The current bandwidth accounting values. - - When the file was last written - - What version of Tor generated the state file - - A short history of bandwidth usage, as produced in the server - descriptors. + Contains a set of persistent key-value mappings. These include: + - the current entry guards and their status. + - the current bandwidth accounting values. + - when the file was last written + - what version of Tor generated the state file + - a short history of bandwidth usage, as produced in the server + descriptors.
__DataDirectory__**/sr-state**:: - Authority only. State file used to record information about the current + _Authority only_. This file is used to record information about the current status of the shared-random-value voting state.
__CacheDirectory__**/diff-cache**:: - Directory cache only. Holds older consensuses, and diffs from older - consensuses to the most recent consensus of each type, compressed - in various ways. Each file contains a set of key-value arguments - describing its contents, followed by a single NUL byte, followed by the - main file contents. + _Directory cache only_. Holds older consensuses and diffs from oldest to + the most recent consensus of each type compressed in various ways. Each + file contains a set of key-value arguments describing its contents, + followed by a single NUL byte, followed by the main file contents.
__DataDirectory__**/bw_accounting**:: - Used to track bandwidth accounting values (when the current period starts - and ends; how much has been read and written so far this period). This file - is obsolete, and the data is now stored in the 'state' file instead. + This file is obsolete and the data is now stored in the **`state`** file + instead. Used to track bandwidth accounting values (when the current period + starts and ends; how much has been read and written so far this period).
__DataDirectory__**/control_auth_cookie**:: - Used for cookie authentication with the controller. Location can be - overridden by the CookieAuthFile config option. Regenerated on startup. See + This file can be used only when cookie authentication is enabled. Used for + cookie authentication with the controller. Location can be overridden by + the `CookieAuthFile` configuration option. Regenerated on startup. See control-spec.txt in https://spec.torproject.org/%5Btorspec] for details. - Only used when cookie authentication is enabled.
__DataDirectory__**/lock**:: - This file is used to prevent two Tor instances from using same data - directory. If access to this file is locked, data directory is already - in use by Tor. + This file is used to prevent two Tor instances from using the same data + directory. If access to this file is locked, data directory is already in + use by Tor.
__DataDirectory__**/key-pinning-journal**:: Used by authorities. A line-based file that records mappings between - RSA1024 identity keys and Ed25519 identity keys. Authorities enforce - these mappings, so that once a relay has picked an Ed25519 key, stealing - or factoring the RSA1024 key will no longer let an attacker impersonate - the relay. + RSA1024 and Ed25519 identity keys. Authorities enforce these mappings, so + that once a relay has picked an Ed25519 key, stealing or factoring the + RSA1024 key will no longer let an attacker impersonate the relay.
__KeyDirectory__**/authority_identity_key**:: A v3 directory authority's master identity key, used to authenticate its signing key. Tor doesn't use this while it's running. The tor-gencert - program uses this. If you're running an authority, you should keep this - key offline, and not actually put it here. + program uses this. If you're running an authority, you should keep this key + offline, and not put it in this file.
__KeyDirectory__**/authority_certificate**:: - A v3 directory authority's certificate, which authenticates the authority's - current vote- and consensus-signing key using its master identity key. - Only directory authorities use this file. + Only directory authorities use this file. A v3 directory authority's + certificate which authenticates the authority's current vote- and + consensus-signing key using its master identity key.
__KeyDirectory__**/authority_signing_key**:: - A v3 directory authority's signing key, used to sign votes and consensuses. - Only directory authorities use this file. Corresponds to the + Only directory authorities use this file. A v3 directory authority's + signing key that is used to sign votes and consensuses. Corresponds to the **authority_certificate** cert.
__KeyDirectory__**/legacy_certificate**:: - As authority_certificate: used only when V3AuthUseLegacyKey is set. - See documentation for V3AuthUseLegacyKey. + As authority_certificate; used only when `V3AuthUseLegacyKey` is set. See + documentation for V3AuthUseLegacyKey.
__KeyDirectory__**/legacy_signing_key**:: - As authority_signing_key: used only when V3AuthUseLegacyKey is set. - See documentation for V3AuthUseLegacyKey. + As authority_signing_key: used only when `V3AuthUseLegacyKey` is set. See + documentation for V3AuthUseLegacyKey.
__KeyDirectory__**/secret_id_key**:: A relay's RSA1024 permanent identity key, including private and public - components. Used to sign router descriptors, and to sign other keys. + components. Used to sign router descriptors, and to sign other keys.
__KeyDirectory__**/ed25519_master_id_public_key**:: The public part of a relay's Ed25519 permanent identity key.
__KeyDirectory__**/ed25519_master_id_secret_key**:: - The private part of a relay's Ed25519 permanent identity key. This key - is used to sign the medium-term ed25519 signing key. This file can be - kept offline, or kept encrypted. If so, Tor will not be able to generate - new signing keys itself; you'll need to use tor --keygen yourself to do - so. + The private part of a relay's Ed25519 permanent identity key. This key is + used to sign the medium-term ed25519 signing key. This file can be kept + offline or encrypted. If so, Tor will not be able to generate new signing + keys automatically; you'll need to use `tor --keygen` to do so.
__KeyDirectory__**/ed25519_signing_secret_key**:: The private and public components of a relay's medium-term Ed25519 signing - key. This key is authenticated by the Ed25519 master key, in turn + key. This key is authenticated by the Ed25519 master key, which in turn authenticates other keys (and router descriptors).
__KeyDirectory__**/ed25519_signing_cert**:: - The certificate which authenticates "ed25519_signing_secret_key" as - having been signed by the Ed25519 master key. + The certificate which authenticates "ed25519_signing_secret_key" as having + been signed by the Ed25519 master key.
__KeyDirectory__**/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. 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. + 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.
__KeyDirectory__**/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. 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. + 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. + Only used by servers. Contains the fingerprint of the server's identity key.
__DataDirectory__**/hashed-fingerprint**:: - Only used by bridges. Holds the hashed fingerprint of the bridge's + Only used by bridges. Contains the hashed fingerprint of the bridge's identity key. (That is, the hash of the hash of the identity key.)
__DataDirectory__**/approved-routers**:: - Only used by authoritative directory servers. This file lists - the status of routers by their identity fingerprint. - Each line lists a status and a fingerprint separated by - whitespace. See your **fingerprint** file in the __DataDirectory__ for an - example line. If the status is **!reject** then descriptors from the - given identity (fingerprint) are rejected by this server. If it is - **!invalid** then descriptors are accepted but marked in the directory as - not valid, that is, not recommended. + Only used by authoritative directory servers. This file lists the status of + routers by their identity fingerprint. Each line lists a status and a + fingerprint separated by whitespace. See your **`fingerprint`** file in the + __DataDirectory__ for an example line. If the status is **!reject**, then + the descriptors from the given identity (fingerprint) are rejected by this + server. If it is **!invalid**, then the descriptors are accepted but marked + in the directory as not valid, that is, not recommended.
__DataDirectory__**/v3-status-votes**:: - Only for v3 authoritative directory servers. This file contains - status votes from all the authoritative directory servers. + Only for v3 authoritative directory servers. This file contains status + votes from all the authoritative directory servers.
__CacheDirectory__**/unverified-consensus**:: - This file contains a network consensus document that has been downloaded, - but which we didn't have the right certificates to check yet. + Contains a network consensus document that has been downloaded, but which + we didn't have the right certificates to check yet.
__CacheDirectory__**/unverified-microdesc-consensus**:: - This file contains a microdescriptor-flavored network consensus document - that has been downloaded, but which we didn't have the right certificates - to check yet. + Contains a microdescriptor-flavored network consensus document that has + been downloaded, but which we didn't have the right certificates to check + yet.
__DataDirectory__**/unparseable-desc**:: Onion server descriptors that Tor was unable to parse are dumped to this @@ -3567,7 +3563,7 @@ __DataDirectory__**/unparseable-desc**::
__DataDirectory__**/router-stability**:: Only used by authoritative directory servers. Tracks measurements for - router mean-time-between-failures so that authorities have a good idea of + router mean-time-between-failures so that authorities have a fair idea of how to set their Stable flags.
__DataDirectory__**/stats/dirreq-stats**:: @@ -3608,17 +3604,18 @@ __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 also contains authorization data for all clients. - + - Note that clients will ignore any extra subdomains prepended to a hidden - service hostname. So if you have "xyz.onion" as your hostname, you - can tell clients to connect to "www.xyz.onion" or "irc.xyz.onion" ++ +[NOTE] + The clients will ignore any extra subdomains prepended to a hidden + service hostname. Supposing you have "xyz.onion" as your hostname, you + can ask your clients to connect to "www.xyz.onion" or "irc.xyz.onion" for virtual-hosting purposes.
__HiddenServiceDirectory__**/private_key**:: - The private key for this hidden service. + Contains the private key for this hidden service.
__HiddenServiceDirectory__**/client_keys**:: - Authorization data for a hidden service that is only accessible by + Contains authorization data for a hidden service that is only accessible by authorized clients.
__HiddenServiceDirectory__**/onion_service_non_anonymous**::