[tor-commits] [tor/master] Update the manpage to describe {Cache, Key}Directory
nickm at torproject.org
nickm at torproject.org
Wed Dec 6 00:53:09 UTC 2017
commit 02cbf2ffc18d4babbc9ed15b87cf040595bb2285
Author: Nick Mathewson <nickm at torproject.org>
Date: Tue Nov 14 18:24:15 2017 -0500
Update the manpage to describe {Cache,Key}Directory
Also, explain which files should be put in which.
---
doc/tor.1.txt | 71 +++++++++++++++++++++++++++++++++++------------------------
1 file changed, 42 insertions(+), 29 deletions(-)
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 725baaa64..17bdaeb0d 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -415,6 +415,16 @@ GENERAL OPTIONS
DataDirectory. If the option is set to 1, make the DataDirectory readable
by the default GID. (Default: 0)
+[[CacheDirectory]] **CacheDirectory** __DIR__::
+ Store cached directory data in DIR. Can not be changed while tor is
+ running.
+ (Default: uses the value of DataDirectory.)
+
+[[CacheDirectoryGroupReadable]] **CacheDirectoryGroupReadable** **0**|**1**::
+ If this option is set to 0, don't allow the filesystem group to read the
+ CacheDirectory. If the option is set to 1, make the CacheDirectory readable
+ by the default GID. (Default: 0)
+
[[FallbackDir]] **FallbackDir** __ipv4address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__] [ipv6=**[**__ipv6address__**]**:__orport__]::
When we're unable to connect to any directory cache for directory info
(usually because we don't know about any yet) we try a directory authority.
@@ -2219,6 +2229,17 @@ is non-zero):
ed25519 master identity key, as well as the corresponding temporary
signing keys and certificates. (Default: 0)
+[[KeyDirectory]] **KeyDirectory** __DIR__::
+ Store secret keys in DIR. Can not be changed while tor is
+ running.
+ (Default: the "keys" subdirectory of DataDirectory.)
+
+[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**::
+ If this option is set to 0, don't allow the filesystem group to read the
+ KeywDirectory. If the option is set to 1, make the KeyDirectory readable
+ by the default GID. (Default: 0)
+
+
DIRECTORY SERVER OPTIONS
------------------------
@@ -2883,40 +2904,35 @@ FILES
**@LOCALSTATEDIR@/lib/tor/**::
The tor process stores keys and other data here.
-__DataDirectory__**/cached-status/**::
- The most recently downloaded network status document for each authority.
- Each file holds one such document; the filenames are the hexadecimal
- identity key fingerprints of the directory authorities. Obsolete;
- no longer in use.
-__DataDirectory__**/cached-certs**::
+__CacheDirectory__**/cached-certs**::
This file holds downloaded directory key certificates that are used to
verify authenticity of documents generated by Tor directory authorities.
-__DataDirectory__**/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.
-__DataDirectory__**/cached-descriptors** and **cached-descriptors.new**::
+__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.
-__DataDirectory__**/cached-extrainfo** and **cached-extrainfo.new**::
+__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.
-__DataDirectory__**/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__**/cached-routers** and **cached-routers.new**::
+__CacheDirectory__**/cached-routers** and **cached-routers.new**::
Obsolete versions of cached-descriptors and cached-descriptors.new. When
Tor can't find the newer files, it looks here instead.
@@ -2934,7 +2950,7 @@ __DataDirectory__**/sr-state**::
Authority only. State file used to record information about the current
status of the shared-random-value voting state.
-__DataDirectory__**/diff-cache**::
+__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
@@ -2964,63 +2980,60 @@ __DataDirectory__**/key-pinning-journal**::
or factoring the RSA1024 key will no longer let an attacker impersonate
the relay.
-__DataDirectory__**/keys/***::
- Only used by servers. Holds identity keys and onion keys.
-
-__DataDirectory__**/keys/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.
-__DataDirectory__**/keys/authority_certificate**::
+__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.
-__DataDirectory__**/keys/authority_signing_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
**authority_certificate** cert.
-__DataDirectory__**/keys/legacy_certificate**::
+__KeyDirectory__**/legacy_certificate**::
As authority_certificate: used only when V3AuthUseLegacyKey is set.
See documentation for V3AuthUseLegacyKey.
-__DataDirectory__**/keys/legacy_signing_key**::
+__KeyDirectory__**/legacy_signing_key**::
As authority_signing_key: used only when V3AuthUseLegacyKey is set.
See documentation for V3AuthUseLegacyKey.
-__DataDirectory__**/keys/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.
-__DataDirectory__**/keys/ed25519_master_id_public_key**::
+__KeyDirectory__**/ed25519_master_id_public_key**::
The public part of a relay's Ed25519 permanent identity key.
-__DataDirectory__**/keys/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 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.
-__DataDirectory__**/keys/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
authenticates other keys (and router descriptors).
-__DataDirectory__**/keys/ed25519_signing_cert**::
+__KeyDirectory__**/ed25519_signing_cert**::
The certificate which authenticates "ed25519_signing_secret_key" as
having been signed by the Ed25519 master key.
-__DataDirectory__**/keys/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.
-__DataDirectory__**/keys/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
@@ -3047,11 +3060,11 @@ __DataDirectory__**/v3-status-votes**::
Only for v3 authoritative directory servers. This file contains
status votes from all the authoritative directory servers.
-__DataDirectory__**/unverified-consensus**::
+__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.
-__DataDirectory__**/unverified-microdesc-consensus**::
+__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.
More information about the tor-commits
mailing list