mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-06 19:41:15 +01:00
Merge remote-tracking branch 'tor-github/pr/1437'
This commit is contained in:
Nick Mathewson
@@ -0,0 +1,4 @@
|
||||
o Documentation (manpage):
|
||||
- In the tor(1) manpage, reword and improve formatting of the
|
||||
FILES, SEE ALSO, and BUGS sections. Closes ticket 32176. Based
|
||||
on work by Swati Thacker as part of Google Season of Docs.
|
||||
+141
-149
@@ -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-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**::
|
||||
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-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
|
||||
**`@`**-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__/**`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. State file used to record information about the current
|
||||
__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.
|
||||
__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**::
|
||||
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__/**`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**::
|
||||
Used for cookie authentication with the controller. Location can be
|
||||
overridden by the CookieAuthFile config option. Regenerated on startup. See
|
||||
__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__/**`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.
|
||||
__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-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**::
|
||||
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.
|
||||
__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 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
|
||||
-------
|
||||
|
||||
Reference in New Issue
Block a user