commit 8b9b51a6cbb37449c6f32205da40b91fa14219f8 Author: Taylor Yu catalyst@torproject.org Date: Mon Oct 21 11:44:49 2019 -0500
Reformat some file names in tor.1.txt
Reformat file name headings in the FILES section of tor.1.txt to display as fixed-width in the HTML version.
Based on a patch by Swati Thacker. Part of #32176. --- doc/tor.1.txt | 95 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 47 insertions(+), 48 deletions(-)
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 97900dc3f..63dc9d92a 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -3391,24 +3391,23 @@ Tor catches the following signals: FILES -----
-**@CONFDIR@/torrc**:: +**`@CONFDIR@/torrc`**:: Default location of the configuration file.
-**$HOME/.torrc**:: +**`$HOME/.torrc`**:: Fallback location for torrc, if @CONFDIR@/torrc is not found.
-**@LOCALSTATEDIR@/lib/tor/**:: +**`@LOCALSTATEDIR@/lib/tor/`**:: The tor process stores keys and other data here.
- -__CacheDirectory__**/cached-certs**:: +__CacheDirectory__/**`cached-certs`**:: 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**:: +__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**:: +__CacheDirectory__/**`cached-descriptors`** and **`cached-descriptors.new`**:: 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 @@ -3416,20 +3415,20 @@ __CacheDirectory__**/cached-descriptors** and **cached-descriptors.new**:: journal; when it gets too large, all entries are merged into a new cached-descriptors file.
-__CacheDirectory__**/cached-extrainfo** and **cached-extrainfo.new**:: +__CacheDirectory__/**`cached-extrainfo`** and **`cached-extrainfo.new`**:: 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**:: +__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 large, all entries are merged into a new cached-microdescs file.
-__DataDirectory__**/state**:: +__DataDirectory__/**`state`**:: Contains a set of persistent key-value mappings. These include: - the current entry guards and their status. - the current bandwidth accounting values. @@ -3438,104 +3437,104 @@ __DataDirectory__**/state**:: - a short history of bandwidth usage, as produced in the server descriptors.
-__DataDirectory__**/sr-state**:: +__DataDirectory__/**`sr-state`**:: _Authority only_. This file is used to record information about the current status of the shared-random-value voting state.
-__CacheDirectory__**/diff-cache**:: +__CacheDirectory__/**`diff-cache`**:: _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**:: +__DataDirectory__/**`bw_accounting`**:: 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**:: +__DataDirectory__/**`control_auth_cookie`**:: 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.
-__DataDirectory__**/lock**:: +__DataDirectory__/**`lock`**:: 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**:: +__DataDirectory__/**`key-pinning-journal`**:: Used by authorities. A line-based file that records mappings between 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**:: +__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 put it in this file.
-__KeyDirectory__**/authority_certificate**:: +__KeyDirectory__/**`authority_certificate`**:: 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**:: +__KeyDirectory__/**`authority_signing_key`**:: 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**:: +__KeyDirectory__/**`legacy_certificate`**:: As authority_certificate; used only when `V3AuthUseLegacyKey` is set. See documentation for V3AuthUseLegacyKey.
-__KeyDirectory__**/legacy_signing_key**:: +__KeyDirectory__/**`legacy_signing_key`**:: As authority_signing_key: used only when `V3AuthUseLegacyKey` is set. See documentation for V3AuthUseLegacyKey.
-__KeyDirectory__**/secret_id_key**:: +__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.
-__KeyDirectory__**/ed25519_master_id_public_key**:: +__KeyDirectory__/**`ed25519_master_id_public_key`**:: The public part of a relay's Ed25519 permanent identity key.
-__KeyDirectory__**/ed25519_master_id_secret_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 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**:: +__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, which in turn authenticates other keys (and router descriptors).
-__KeyDirectory__**/ed25519_signing_cert**:: +__KeyDirectory__/**`ed25519_signing_cert`**:: 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**:: +__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.
-__KeyDirectory__**/secret_onion_key_ntor** and **secret_onion_key_ntor.old**:: +__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.
-__DataDirectory__**/fingerprint**:: +__DataDirectory__/**`fingerprint`**:: Only used by servers. Contains the fingerprint of the server's identity key.
-__DataDirectory__**/hashed-fingerprint**:: +__DataDirectory__/**`hashed-fingerprint`**:: 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**:: +__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 @@ -3544,63 +3543,63 @@ __DataDirectory__**/approved-routers**:: 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**:: +__DataDirectory__/**`v3-status-votes`**:: Only for v3 authoritative directory servers. This file contains status votes from all the authoritative directory servers.
-__CacheDirectory__**/unverified-consensus**:: +__CacheDirectory__/**`unverified-consensus`**:: 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**:: +__CacheDirectory__/**`unverified-microdesc-consensus`**:: 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**:: +__DataDirectory__/**`unparseable-desc`**:: Onion server descriptors that Tor was unable to parse are dumped to this file. Only used for debugging.
-__DataDirectory__**/router-stability**:: +__DataDirectory__/**`router-stability`**:: Only used by authoritative directory servers. Tracks measurements for router mean-time-between-failures so that authorities have a fair idea of how to set their Stable flags.
-__DataDirectory__**/stats/dirreq-stats**:: +__DataDirectory__/**`stats/dirreq-stats`**:: Only used by directory caches and authorities. This file is used to collect directory request statistics.
-__DataDirectory__**/stats/entry-stats**:: +__DataDirectory__/**`stats/entry-stats`**:: Only used by servers. This file is used to collect incoming connection statistics by Tor entry nodes.
-__DataDirectory__**/stats/bridge-stats**:: +__DataDirectory__/**`stats/bridge-stats`**:: Only used by servers. This file is used to collect incoming connection statistics by Tor bridges.
-__DataDirectory__**/stats/exit-stats**:: +__DataDirectory__/**`stats/exit-stats`**:: Only used by servers. This file is used to collect outgoing connection statistics by Tor exit routers.
-__DataDirectory__**/stats/buffer-stats**:: +__DataDirectory__/**`stats/buffer-stats`**:: Only used by servers. This file is used to collect buffer usage history.
-__DataDirectory__**/stats/conn-stats**:: +__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**:: +__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**:: +__DataDirectory__/**networkstatus-bridges`**:: Only used by authoritative bridge directories. Contains information about bridges that have self-reported themselves to the bridge authority.
-__HiddenServiceDirectory__**/hostname**:: +__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. @@ -3611,14 +3610,14 @@ __HiddenServiceDirectory__**/hostname**:: can ask your clients to connect to "www.xyz.onion" or "irc.xyz.onion" for virtual-hosting purposes.
-__HiddenServiceDirectory__**/private_key**:: +__HiddenServiceDirectory__/**`private_key`**:: Contains the private key for this hidden service.
-__HiddenServiceDirectory__**/client_keys**:: +__HiddenServiceDirectory__/**`client_keys`**:: Contains authorization data for a hidden service that is only accessible by authorized clients.
-__HiddenServiceDirectory__**/onion_service_non_anonymous**:: +__HiddenServiceDirectory__/**`onion_service_non_anonymous`**:: This file is present if a hidden service key was created in **HiddenServiceNonAnonymousMode**.