diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 323 |
1 files changed, 136 insertions, 187 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 1665cfe947..2459969f98 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -153,6 +153,13 @@ values. To split one configuration entry into multiple lines, use a single backslash character (\) before the end of the line. Comments can be used in such multiline entries, but they must start at the beginning of a line. +Configuration options can be imported from files or folders using the %include +option with the value being a path. If the path is a file, the options from the +file will be parsed as if they were written where the %include option is. If +the path is a folder, all files on that folder will be parsed following lexical +order. Files starting with a dot are ignored. Files on subfolders are ignored. +The %include option can be used recursively. + By default, an option on the command line overrides an option found in the configuration file, and an option in a configuration file overrides one in the defaults file. @@ -185,6 +192,9 @@ GENERAL OPTIONS course, more is better; we recommend at least 250 KBytes (2 mbits) if possible. (Default: 1 GByte) + + + Note that this option, and other bandwidth-limiting options, apply to TCP + data only: They do not count TCP headers or DNS traffic. + + + With this option, and in other options that take arguments in bytes, KBytes, and so on, other formats are also supported. Notably, "KBytes" can also be written as "kilobytes" or "kb"; "MBytes" can be written as @@ -338,14 +348,6 @@ GENERAL OPTIONS Unix domain sockets only: Do not insist that the directory that holds the socket be read-restricted. -[[ControlListenAddress]] **ControlListenAddress** __IP__[:__PORT__]:: - Bind the controller listener to this address. If you specify a port, bind - to this port rather than the one specified in ControlPort. We strongly - recommend that you leave this alone unless you know what you're doing, - since giving attackers access to your control listener is really - dangerous. This directive can be specified multiple - times to bind to multiple addresses/ports. (Default: 127.0.0.1) - [[ControlSocket]] **ControlSocket** __Path__:: Like ControlPort, but listens on a Unix domain socket, rather than a TCP socket. '0' disables ControlSocket (Unix and Unix-like systems only.) @@ -391,7 +393,9 @@ GENERAL OPTIONS [[DataDirectory]] **DataDirectory** __DIR__:: Store working data in DIR. Can not be changed while tor is running. - (Default: @LOCALSTATEDIR@/lib/tor) + (Default: ~/.tor if your home directory is not /; otherwise, + @LOCALSTATEDIR@/lib/tor. On Windows, the default is + your ApplicationData folder.) [[DataDirectoryGroupReadable]] **DataDirectoryGroupReadable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read the @@ -641,18 +645,19 @@ GENERAL OPTIONS (127.0.0.0/8 and ::1). [[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__:: - Make all outbound non-exit (=relay and other) connections originate from the IP - address specified. This option overrides **OutboundBindAddress** for the same - IP version. This option may be used twice, once with an IPv4 address and once - with an IPv6 address. This setting will be ignored for connections to the - loopback addresses (127.0.0.0/8 and ::1). + Make all outbound non-exit (relay and other) connections + originate from the IP address specified. This option overrides + **OutboundBindAddress** for the same IP version. This option may + be used twice, once with an IPv4 address and once with an IPv6 + address. This setting will be ignored for connections to the loopback + addresses (127.0.0.0/8 and ::1). [[OutboundBindAddressExit]] **OutboundBindAddressExit** __IP__:: - Make all outbound exit connections originate from the IP address specified. This - option overrides **OutboundBindAddress** for the same IP version. This option - may be used twice, once with an IPv4 address and once with an IPv6 address. This - setting will be ignored for connections to the loopback addresses (127.0.0.0/8 - and ::1). + Make all outbound exit connections originate from the IP address + specified. This option overrides **OutboundBindAddress** for the + same IP version. This option may be used twice, once with an IPv4 + address and once with an IPv6 address. This setting will be ignored + for connections to the loopback addresses (127.0.0.0/8 and ::1). [[PidFile]] **PidFile** __FILE__:: On startup, write our PID to FILE. On clean shutdown, remove @@ -663,12 +668,6 @@ GENERAL OPTIONS following the Tor specification. Otherwise, they are logged with severity \'info'. (Default: 0) -[[PredictedPortsRelevanceTime]] **PredictedPortsRelevanceTime** __NUM__:: - Set how long, after the client has made an anonymized connection to a - given port, we will try to make sure that we build circuits to - exits that support that port. The maximum value for this option is 1 - hour. (Default: 1 hour) - [[RunAsDaemon]] **RunAsDaemon** **0**|**1**:: If 1, Tor forks and daemonizes to the background. This option has no effect on Windows; instead you should use the --service command-line option. @@ -767,22 +766,6 @@ CLIENT OPTIONS The following options are useful only for clients (that is, if **SocksPort**, **TransPort**, **DNSPort**, or **NATDPort** is non-zero): -[[AllowInvalidNodes]] **AllowInvalidNodes** **entry**|**exit**|**middle**|**introduction**|**rendezvous**|**...**:: - If some Tor servers are obviously not working right, the directory - authorities can manually mark them as invalid, meaning that it's not - recommended you use them for entry or exit positions in your circuits. You - can opt to use them in some circuit positions, though. The default is - "middle,rendezvous", and other choices are not advised. - -[[ExcludeSingleHopRelays]] **ExcludeSingleHopRelays** **0**|**1**:: - This option controls whether circuits built by Tor will include relays with - the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set - to 0, these relays will be included. Note that these relays might be at - higher risk of being seized or observed, so they are not normally - included. Also note that relatively few clients turn off this option, - so using these relays might make your client stand out. - (Default: 1) - [[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]:: When set along with UseBridges, instructs Tor to use the relay at "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" @@ -796,7 +779,12 @@ The following options are useful only for clients (that is, if rather than connecting to the bridge directly. Some transports use a transport-specific method to work out the remote address to connect to. These transports typically ignore the "IP:ORPort" specified in the bridge - line. + line. + + + + Tor passes any "key=val" settings to the pluggable transport proxy as + per-connection arguments when connecting to the bridge. Consult + the documentation of the pluggable transport for details of what + arguments it supports. [[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**:: If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) @@ -809,13 +797,15 @@ The following options are useful only for clients (that is, if LearnCircuitBuildTimeout is 0, this value is the only value used. (Default: 60 seconds) -[[CircuitIdleTimeout]] **CircuitIdleTimeout** __NUM__:: - If we have kept a clean (never used) circuit around for NUM seconds, then - close it. This way when the Tor client is entirely idle, it can expire all - of its circuits, and then expire its TLS connections. Also, if we end up - making a circuit that is not useful for exiting any of the requests we're - receiving, it won't forever take up a slot in the circuit list. (Default: 1 - hour) +[[CircuitsAvailableTimeout]] **CircuitsAvailableTimeout** __NUM__:: + Tor will attempt to keep at least one open, unused circuit available for + this amount of time. This option governs how long idle circuits are kept + open, as well as the amount of time Tor will keep a circuit open to each + of the recently used ports. This way when the Tor client is entirely + idle, it can expire all of its circuits, and then expire its TLS + connections. Note that the actual timeout value is uniformly randomized + from the specified value to twice that amount. (Default: 30 minutes; + Max: 24 hours) [[CircuitStreamTimeout]] **CircuitStreamTimeout** __NUM__:: If non-zero, this option overrides our internal timeout schedule for how @@ -832,6 +822,22 @@ The following options are useful only for clients (that is, if and fast enough. The current behavior is simply that Tor is a client unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0) +[[ConnectionPadding]] **ConnectionPadding** **0**|**1**|**auto**:: + This option governs Tor's use of padding to defend against some forms of + traffic analysis. If it is set to 'auto', Tor will send padding only + if both the client and the relay support it. If it is set to 0, Tor will + not send any padding cells. If it is set to 1, Tor will still send padding + for client connections regardless of relay support. Only clients may set + this option. This option should be offered via the UI to mobile users + for use where bandwidth may be expensive. + (Default: auto) + +[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: + If set to 1, Tor will not not hold OR connections open for very long, + and will send less padding on these connections. Only clients may set + this option. This option should be offered via the UI to mobile users + for use where bandwidth may be expensive. (Default: 0) + [[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to avoid when building a circuit. Country codes are @@ -974,24 +980,6 @@ The following options are useful only for clients (that is, if services can be configured to require authorization using the **HiddenServiceAuthorizeClient** option. -[[CloseHSClientCircuitsImmediatelyOnTimeout]] **CloseHSClientCircuitsImmediatelyOnTimeout** **0**|**1**:: - If 1, Tor will close unfinished hidden service client circuits - which have not moved closer to connecting to their destination - hidden service when their internal state has not changed for the - duration of the current circuit-build timeout. Otherwise, such - circuits will be left open, in the hope that they will finish - connecting to their destination hidden services. In either case, - another set of introduction and rendezvous circuits for the same - destination hidden service will be launched. (Default: 0) - -[[CloseHSServiceRendCircuitsImmediatelyOnTimeout]] **CloseHSServiceRendCircuitsImmediatelyOnTimeout** **0**|**1**:: - If 1, Tor will close unfinished hidden-service-side rendezvous - circuits after the current circuit-build timeout. Otherwise, such - circuits will be left open, in the hope that they will finish - connecting to their destinations. In either case, another - rendezvous circuit for the same destination client will be - launched. (Default: 0) - [[LongLivedPorts]] **LongLivedPorts** __PORTS__:: A list of ports for services that tend to have long-running connections (e.g. chat and interactive shells). Circuits for streams that use these @@ -1050,7 +1038,8 @@ The following options are useful only for clients (that is, if but never attach a new stream to a circuit that is too old. For hidden services, this applies to the __last__ time a circuit was used, not the first. Circuits with streams constructed with SOCKS authentication via - SocksPorts that have **KeepAliveIsolateSOCKSAuth** ignore this value. + SocksPorts that have **KeepAliveIsolateSOCKSAuth** also remain alive + for MaxCircuitDirtiness seconds after carrying the last such stream. (Default: 10 minutes) [[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__:: @@ -1112,8 +1101,9 @@ The following options are useful only for clients (that is, if Don't share circuits with streams targeting a different destination address. **KeepAliveIsolateSOCKSAuth**;; - If **IsolateSOCKSAuth** is enabled, keep alive circuits that have - streams with SOCKS authentication set indefinitely. + If **IsolateSOCKSAuth** is enabled, keep alive circuits while they have + at least one stream with SOCKS authentication active. After such a circuit + is idle for more than MaxCircuitDirtiness seconds, it can be closed. **SessionGroup=**__INT__;; If no other isolation rules would prevent it, allow streams on this port to share circuits with streams from every other @@ -1190,16 +1180,6 @@ The following options are useful only for clients (that is, if line is used, and all earlier flags are ignored. No error is issued for conflicting flags. -[[SocksListenAddress]] **SocksListenAddress** __IP__[:__PORT__]:: - Bind to this address to listen for connections from Socks-speaking - applications. (Default: 127.0.0.1) You can also specify a port (e.g. - 192.168.0.1:9100). This directive can be specified multiple times to bind - to multiple addresses/ports. (DEPRECATED: As of 0.2.3.x-alpha, you can - now use multiple SocksPort entries, and provide addresses for SocksPort - entries, so SocksListenAddress no longer has a purpose. For backward - compatibility, SocksListenAddress is only allowed when SocksPort is just - a port number.) - [[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: Set an entrance policy for this server, to limit who can connect to the SocksPort and DNSPort ports. The policies have the same form as exit @@ -1267,16 +1247,16 @@ The following options are useful only for clients (that is, if [[NumEntryGuards]] **NumEntryGuards** __NUM__:: If UseEntryGuards is set to 1, we will try to pick a total of NUM routers - as long-term entries for our circuits. If NUM is 0, we try to learn - the number from the NumEntryGuards consensus parameter, and default - to 3 if the consensus parameter isn't set. (Default: 0) + as long-term entries for our circuits. If NUM is 0, we try to learn the + number from the guard-n-primary-guards-to-use consensus parameter, and + default to 1 if the consensus parameter isn't set. (Default: 0) [[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__:: - If UseEntryGuardsAsDirectoryGuards is enabled, we try to make sure we - have at least NUM routers to use as directory guards. If this option - is set to 0, use the value from the NumDirectoryGuards consensus - parameter, falling back to the value from NumEntryGuards if the - consensus parameter is 0 or isn't set. (Default: 0) + If UseEntryGuardsAsDirectoryGuards is enabled, we try to make sure we have + at least NUM routers to use as directory guards. If this option is set to + 0, use the value from the guard-n-primary-dir-guards-to-use consensus + parameter, and default to 3 if the consensus parameter isn't set. + (Default: 0) [[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**:: If nonzero, and UseEntryGuards is set, minimum time to keep a guard before @@ -1298,12 +1278,6 @@ The following options are useful only for clients (that is, if helps to determine whether an application using Tor is possibly leaking DNS requests. (Default: 0) -[[WarnUnsafeSocks]] **WarnUnsafeSocks** **0**|**1**:: - When this option is enabled, Tor will warn whenever a request is - received that only contains an IP address instead of a hostname. Allowing - applications to do DNS resolves themselves is usually a bad idea and - can leak your location to attackers. (Default: 1) - [[VirtualAddrNetworkIPv4]] **VirtualAddrNetworkIPv4** __Address__/__bits__ + [[VirtualAddrNetworkIPv6]] **VirtualAddrNetworkIPv6** [__Address__]/__bits__:: @@ -1335,18 +1309,6 @@ The following options are useful only for clients (that is, if the node "foo". Disabled by default since attacking websites and exit relays can use it to manipulate your path selection. (Default: 0) -[[FastFirstHopPK]] **FastFirstHopPK** **0**|**1**|**auto**:: - When this option is disabled, Tor uses the public key step for the first - hop of creating circuits. Skipping it is generally safe since we have - already used TLS to authenticate the relay and to establish forward-secure - keys. Turning this option off makes circuit building a little - slower. Setting this option to "auto" takes advice from the authorities - in the latest consensus about whether to use this feature. + - + - Note that Tor will always use the public key step for the first hop if it's - operating as a relay, and it will never use the public key step if it - doesn't yet know the onion key of the first hop. (Default: auto) - [[TransPort]] **TransPort** \['address':]__port__|**auto** [_isolation flags_]:: Open this port to listen for transparent proxy connections. Set this to 0 if you don't want to allow transparent proxy connections. Set the port @@ -1357,17 +1319,7 @@ The following options are useful only for clients (that is, if TransPort requires OS support for transparent proxies, such as BSDs' pf or Linux's IPTables. If you're planning to use Tor as a transparent proxy for a network, you'll want to examine and change VirtualAddrNetwork from the - default setting. You'll also want to set the TransListenAddress option for - the network you'd like to proxy. (Default: 0) - -[[TransListenAddress]] **TransListenAddress** __IP__[:__PORT__]:: - Bind to this address to listen for transparent proxy connections. (Default: - 127.0.0.1). This is useful for exporting a transparent proxy server to an - entire network. (DEPRECATED: As of 0.2.3.x-alpha, you can - now use multiple TransPort entries, and provide addresses for TransPort - entries, so TransListenAddress no longer has a purpose. For backward - compatibility, TransListenAddress is only allowed when TransPort is just - a port number.) + default setting. (Default: 0) [[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**:: TransProxyType may only be enabled when there is transparent proxy listener @@ -1375,9 +1327,7 @@ The following options are useful only for clients (that is, if + Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module to transparently proxy connections that are configured using the TransPort - option. This setting lets the listener on the TransPort accept connections - for all addresses, even when the TransListenAddress is configured for an - internal address. Detailed information on how to configure the TPROXY + option. Detailed information on how to configure the TPROXY feature can be found in the Linux kernel source tree in the file Documentation/networking/tproxy.txt. + + @@ -1405,13 +1355,6 @@ The following options are useful only for clients (that is, if + This option is only for people who cannot use TransPort. (Default: 0) -[[NATDListenAddress]] **NATDListenAddress** __IP__[:__PORT__]:: - Bind to this address to listen for NATD connections. (DEPRECATED: As of - 0.2.3.x-alpha, you can now use multiple NATDPort entries, and provide - addresses for NATDPort entries, so NATDListenAddress no longer has a - purpose. For backward compatibility, NATDListenAddress is only allowed - when NATDPort is just a port number.) - [[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**:: When this option is enabled, and we get a request to resolve an address that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an @@ -1432,13 +1375,6 @@ The following options are useful only for clients (that is, if addresses/ports. See SocksPort for an explanation of isolation flags. (Default: 0) -[[DNSListenAddress]] **DNSListenAddress** __IP__[:__PORT__]:: - Bind to this address to listen for DNS connections. (DEPRECATED: As of - 0.2.3.x-alpha, you can now use multiple DNSPort entries, and provide - addresses for DNSPort entries, so DNSListenAddress no longer has a - purpose. For backward compatibility, DNSListenAddress is only allowed - when DNSPort is just a port number.) - [[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**:: If true, Tor does not believe any anonymously retrieved DNS answer that tells it that an address resolves to an internal address (like 127.0.0.1 or @@ -1468,11 +1404,6 @@ The following options are useful only for clients (that is, if Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor will instead refuse to make the connection. (Default: None) -[[AllowSingleHopCircuits]] **AllowSingleHopCircuits** **0**|**1**:: - When this option is set, the attached Tor controller can use relays - that have the **AllowSingleHopExits** option turned on to build - one-hop Tor connections. (Default: 0) - [[OptimisticData]] **OptimisticData** **0**|**1**|**auto**:: When this option is set, and Tor is using an exit node that supports the feature, it will try optimistically to send data to the exit node @@ -1665,13 +1596,6 @@ is non-zero): Tor client binds to. To bind to a different address, use the *ListenAddress and OutboundBindAddress options. -[[AllowSingleHopExits]] **AllowSingleHopExits** **0**|**1**:: - This option controls whether clients can use this server as a single hop - proxy. If set to 1, clients can use this server as an exit even if it is - the only hop in the circuit. Note that most clients will refuse to use - servers that set this option, since most clients have - ExcludeSingleHopRelays set. (Default: 0) - [[AssumeReachable]] **AssumeReachable** **0**|**1**:: This option is used when bootstrapping a new Tor network. If set to 1, don't do self-reachability testing; just upload your server descriptor @@ -1806,14 +1730,18 @@ is non-zero): If we have more onionskins queued for processing than we can process in this amount of time, reject new ones. (Default: 1750 msec) -[[MyFamily]] **MyFamily** __node__,__node__,__...__:: - Declare that this Tor server is controlled or administered by a group or - organization identical or similar to that of the other servers, defined by - their identity fingerprints. When two servers both declare - that they are in the same \'family', Tor clients will not use them in the - same circuit. (Each server only needs to list the other servers in its - family; it doesn't need to list itself, but it won't hurt.) Do not list - any bridge relay as it would compromise its concealment. + +[[MyFamily]] **MyFamily** __fingerprint__,__fingerprint__,...:: + Declare that this Tor relay is controlled or administered by a group or + organization identical or similar to that of the other relays, defined by + their (possibly $-prefixed) identity fingerprints. + This option can be repeated many times, for + convenience in defining large families: all fingerprints in all MyFamily + lines are merged into one list. + When two relays both declare that they are in the + same \'family', Tor clients will not use them in the same circuit. (Each + relay only needs to list the other servers in its family; it doesn't need to + list itself, but it won't hurt if it does.) Do not list any bridge relay as it would + compromise its concealment. + + When listing a node, it's better to list it by fingerprint than by nickname: fingerprints are more reliable. @@ -1855,15 +1783,6 @@ is non-zero): For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and IPv4Only and IPv6Only are mutually exclusive. -[[ORListenAddress]] **ORListenAddress** __IP__[:__PORT__]:: - Bind to this IP address to listen for connections from Tor clients and - servers. If you specify a port, bind to this port rather than the one - specified in ORPort. (Default: 0.0.0.0) This directive can be specified - multiple times to bind to multiple addresses/ports. + - + - This option is deprecated; you can get the same behavior with ORPort now - that it supports NoAdvertise and explicit addresses. - [[PortForwarding]] **PortForwarding** **0**|**1**:: Attempt to automatically forward the DirPort and ORPort on a NAT router connecting this Tor server to the Internet. If set, Tor will try both @@ -2015,12 +1934,6 @@ is non-zero): [[GeoIPv6File]] **GeoIPv6File** __filename__:: A filename containing IPv6 GeoIP data, for use with by-country statistics. -[[TLSECGroup]] **TLSECGroup** **P224**|**P256**:: - What EC group should we try to use for incoming TLS connections? - P224 is faster, but makes us stand out more. Has no effect if - we're a client, or if our OpenSSL version lacks support for ECDHE. - (Default: P256) - [[CellStatistics]] **CellStatistics** **0**|**1**:: Relays only. When this option is enabled, Tor collects statistics about cell @@ -2031,6 +1944,14 @@ is non-zero): If ExtraInfoStatistics is enabled, it will published as part of extra-info document. (Default: 0) +[[PaddingStatistics]] **PaddingStatistics** **0**|**1**:: + Relays only. + When this option is enabled, Tor collects statistics for padding cells + sent and received by this relay, in addition to total cell counts. + These statistics are rounded, and omitted if traffic is low. This + information is important for load balancing decisions related to padding. + (Default: 1) + [[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: Relays and bridges only. When this option is enabled, a Tor directory writes statistics on the @@ -2139,15 +2060,6 @@ details.) + The same flags are supported here as are supported by ORPort. -[[DirListenAddress]] **DirListenAddress** __IP__[:__PORT__]:: - Bind the directory service to this address. If you specify a port, bind to - this port rather than the one specified in DirPort. (Default: 0.0.0.0) - This directive can be specified multiple times to bind to multiple - addresses/ports. + - + - This option is deprecated; you can get the same behavior with DirPort now - that it supports NoAdvertise and explicit addresses. - [[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__:: Set an entrance policy for this server, to limit who can connect to the directory ports. The policies have the same form as exit policies above, @@ -2775,7 +2687,8 @@ FILES __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. Mostly obsolete. + identity key fingerprints of the directory authorities. Obsolete; + no longer in use. __DataDirectory__**/cached-certs**:: This file holds downloaded directory key certificates that are used to @@ -2791,6 +2704,13 @@ __DataDirectory__**/cached-descriptors** and **cached-descriptors.new**:: 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**:: + 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**:: These files hold downloaded microdescriptors. Lines beginning with @-signs are annotations that contain more information about a given @@ -2805,18 +2725,27 @@ __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 (unused so far; see - below). + - 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 + status of the shared-random-value voting state. + +__DataDirectory__**/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 + decribing 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 as well. Only - used when bandwidth accounting is enabled. + 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 @@ -2829,6 +2758,13 @@ __DataDirectory__**/lock**:: 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. + __DataDirectory__**/keys/***:: Only used by servers. Holds identity keys and onion keys. @@ -2879,13 +2815,17 @@ __DataDirectory__**/keys/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**:: +__DataDirectory__**/keys/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. + 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**:: +__DataDirectory__**/keys/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. + 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. @@ -2940,11 +2880,20 @@ __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**:: + 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**:: 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**:: The <base32-encoded-fingerprint>.onion domain name for this hidden service. If the hidden service is restricted to authorized clients only, this file |