Merge remote-tracking branch 'tor-github/pr/1437'

1 files changed, 150 insertions, 158 deletions

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 7947ec8846..3c74e6d794 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -3396,256 +3396,248 @@ Tor catches the following signals:
 FILES
 -----
 
-**@CONFDIR@/torrc**::
-    The configuration file, which contains "option value" pairs.
+**`@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`**::
+    Contains downloaded directory key certificates that are used to verify
+    authenticity of documents generated by the Tor directory authorities.
 
-__CacheDirectory__**/cached-certs**::
-    This file holds downloaded directory key certificates that are used to
-    verify authenticity of documents generated by 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**::
-    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.
-
-__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.
-
-__CacheDirectory__**/cached-microdescs** and **cached-microdescs.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
+    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`**::
+    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.
-
-__DataDirectory__**/sr-state**::
-    Authority only. State file used to record information about the current
+__DataDirectory__/**`state`**::
+    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_. 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.
-
-__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.
-
-__DataDirectory__**/control_auth_cookie**::
-    Used for cookie authentication with the controller. Location can be
-    overridden by the CookieAuthFile config option. Regenerated on startup. See
+__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`**::
+    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`**::
+    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.
+__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 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**::
+__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.
+__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**::
-    A v3 directory authority's signing key, used to sign votes and consensuses.
-    Only directory authorities use this file.  Corresponds to the
+__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**::
-    As authority_certificate: used only when V3AuthUseLegacyKey is set.
-    See documentation for V3AuthUseLegacyKey.
+__KeyDirectory__/**`legacy_certificate`**::
+    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.
+__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.
+    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**::
-    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.
+__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, 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.
+__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.
+    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.
+    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.
+__DataDirectory__/**`fingerprint`**::
+    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
+__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**::
-    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.
-
-__DataDirectory__**/v3-status-votes**::
-    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.
-
-__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.
-
-__DataDirectory__**/unparseable-desc**::
+__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
+    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.
+
+__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`**::
+    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
     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 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**::
+__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.
 
-__DataDirectory__**/approved-routers**::
-    Authorities only. This file is used to configure which relays are
-    known to be valid, invalid, and so forth.
-
-__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.
- +
-    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.
+__HiddenServiceDirectory__/**`private_key`**::
+    Contains the private key for this hidden service.
 
-__HiddenServiceDirectory__**/client_keys**::
-    Authorization data for a hidden service that is only accessible by
+__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**.
 
 SEE ALSO
 --------
-**torsocks**(1), **torify**(1) +
-
-**https://www.torproject.org/**
 
-**torspec: https://spec.torproject.org **
+For more information, refer to the Tor project at https://www.torproject.org/
+and the Tor spec at https://spec.torproject.org. See also **torsocks**(1) and
+**torify**(1).
 
 BUGS
 ----
 
-Plenty, probably. Tor is still in development. Please report them at https://trac.torproject.org/.
+Because Tor is still under development, there may be plenty of bugs. Please
+report them at https://trac.torproject.org/.
 
 AUTHORS
 -------