mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-06 19:41:15 +01:00
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.
This commit is contained in:
Taylor Yu
+89
-92
@@ -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**::
|
||||
|
||||
Reference in New Issue
Block a user