[tor-commits] [tor/master] Reword FILES section of tor.1.txt
nickm at torproject.org
nickm at torproject.org
Thu Oct 24 15:45:15 UTC 2019
commit e8fe6bd8d6ddfe5df0cd1a67aa4e7a4bf91976cf
Author: Taylor Yu <catalyst at 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/[torspec] 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**::
More information about the tor-commits
mailing list