[tor-commits] [tor/maint-0.4.3] Alphabetized Server Options and Directory Server Options
nickm at torproject.org
nickm at torproject.org
Wed Feb 12 18:49:03 UTC 2020
commit 725b0528e3c0d65c5b76dcf7ade7162d666290f8
Author: swati <swati.thacker at oracle.com>
Date: Tue Feb 11 01:41:43 2020 +0530
Alphabetized Server Options and Directory Server Options
---
doc/tor.1.txt | 632 ++++++++++++++++++++++++++++++----------------------------
1 file changed, 322 insertions(+), 310 deletions(-)
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index a9b9852b7..84ff5841f 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -2060,9 +2060,58 @@ different from other Tor clients:
== SERVER OPTIONS
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
The following options are useful only for servers (that is, if ORPort
is non-zero):
+[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**::
+ Limits the max number of bytes sent and received within a set time period
+ using a given calculation rule (see: AccountingStart, AccountingRule).
+ Useful if you need to stay under a specific bandwidth. By default, the
+ number used for calculation is the max of either the bytes sent or
+ received. For example, with AccountingMax set to 1 TByte, a server
+ could send 900 GBytes and receive 800 GBytes and continue running.
+ It will only hibernate once one of the two reaches 1 TByte. This can
+ be changed to use the sum of the both bytes received and sent by setting
+ the AccountingRule option to "sum" (total bandwidth in/out). When the
+ number of bytes remaining gets low, Tor will stop accepting new connections
+ and circuits. When the number of bytes is exhausted, Tor will hibernate
+ until some time in the next accounting period. To prevent all servers
+ from waking at the same time, Tor will also wait until a random point
+ in each period before waking up. If you have bandwidth cost issues,
+ enabling hibernation is preferable to setting a low bandwidth, since
+ it provides users with a collection of fast servers that are up some
+ of the time, which is more useful than a set of slow servers that are
+ always "available". +
+ +
+ Note that (as also described in the Bandwidth section) Tor uses
+ powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
+ one billion. Be careful: some internet service providers might count
+ GBytes differently.
+
+[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**::
+ How we determine when our AccountingMax has been reached (when we
+ should hibernate) during a time interval. Set to "max" to calculate
+ using the higher of either the sent or received bytes (this is the
+ default functionality). Set to "sum" to calculate using the sent
+ plus received bytes. Set to "in" to calculate using only the
+ received bytes. Set to "out" to calculate using only the sent bytes.
+ (Default: max)
+
+[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
+ Specify how long accounting periods last. If **month** is given,
+ each accounting period runs from the time __HH:MM__ on the __dayth__ day of one
+ month to the same day and time of the next. The relay will go at full speed,
+ use all the quota you specify, then hibernate for the rest of the period. (The
+ day must be between 1 and 28.) If **week** is given, each accounting period
+ runs from the time __HH:MM__ of the __dayth__ day of one week to the same day
+ and time of the next week, with Monday as day 1 and Sunday as day 7. If **day**
+ is given, each accounting period runs from the time __HH:MM__ each day to the
+ same time on the next day. All times are local, and given in 24-hour time.
+ (Default: "month 1 0:00")
+
[[Address]] **Address** __address__::
The IPv4 address of this server, or a fully qualified domain name of
this server that resolves to an IPv4 address. You can leave this
@@ -2088,6 +2137,15 @@ is non-zero):
Note: make sure that no MyFamily lines are present in your torrc when
relay is configured in bridge mode.
+//Out of order because it logically belongs after BridgeRelay.
+[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**::
+ When this option is enabled and BridgeRelay is also enabled, and we have
+ GeoIP data, Tor keeps a per-country count of how many client
+ addresses have contacted it so that it can help the bridge authority guess
+ which countries have blocked access to it. If ExtraInfoStatistics is
+ enabled, it will be published as part of extra-info document. (Default: 1)
+
+//Out of order because it logically belongs after BridgeRelay.
[[BridgeDistribution]] **BridgeDistribution** __string__::
If set along with BridgeRelay, Tor will include a new line in its
bridge descriptor which indicates to the BridgeDB service how it
@@ -2108,21 +2166,11 @@ is non-zero):
relay or bridge. (Really, everybody running a relay or bridge should set
it.)
-
-[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**::
- Tells Tor whether to run as an exit relay. If Tor is running as a
- non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to
- exit according to the ExitPolicy option, the ReducedExitPolicy option,
- or the default ExitPolicy (if no other exit policy option is specified). +
- +
- If ExitRelay is set to 0, no traffic is allowed to exit, and the
- ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. +
- +
- If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
- ReducedExitPolicy, and IPv6Exit options. If at least one of these options
- is set, Tor behaves as if ExitRelay were set to 1. If none of these exit
- policy options are set, Tor behaves as if ExitRelay were set to 0.
- (Default: auto)
+[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**::
+ This option disables the code that closes connections when Tor notices
+ that it is running low on sockets. Right now, it is on by default,
+ since the existing out-of-sockets mechanism tends to kill OR connections
+ more than it should. (Default: 1)
[[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__::
Set an exit policy for this server. Each policy is of the form
@@ -2205,12 +2253,6 @@ is non-zero):
Since the default exit policy uses accept/reject *, it applies to both
IPv4 and IPv6 addresses.
-[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**::
- Reject all private (local) networks, along with the relay's advertised
- public IPv4 and IPv6 addresses, at the beginning of your exit policy.
- See above entry on ExitPolicy.
- (Default: 1)
-
[[ExitPolicyRejectLocalInterfaces]] **ExitPolicyRejectLocalInterfaces** **0**|**1**::
Reject all IPv4 and IPv6 addresses that the relay knows about, at the
beginning of your exit policy. This includes any OutboundBindAddress, the
@@ -2223,6 +2265,168 @@ is non-zero):
to disclose.
(Default: 0)
+[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**::
+ Reject all private (local) networks, along with the relay's advertised
+ public IPv4 and IPv6 addresses, at the beginning of your exit policy.
+ See above entry on ExitPolicy.
+ (Default: 1)
+
+[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**::
+ Tells Tor whether to run as an exit relay. If Tor is running as a
+ non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to
+ exit according to the ExitPolicy option, the ReducedExitPolicy option,
+ or the default ExitPolicy (if no other exit policy option is specified). +
+ +
+ If ExitRelay is set to 0, no traffic is allowed to exit, and the
+ ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. +
+ +
+ If ExitRelay is set to "auto", then Tor checks the ExitPolicy,
+ ReducedExitPolicy, and IPv6Exit options. If at least one of these options
+ is set, Tor behaves as if ExitRelay were set to 1. If none of these exit
+ policy options are set, Tor behaves as if ExitRelay were set to 0.
+ (Default: auto)
+
+[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**::
+ When this option is enabled, Tor will connect to relays on localhost,
+ RFC1918 addresses, and so on. In particular, Tor will make direct OR
+ connections, and Tor routers allow EXTEND requests, to these private
+ addresses. (Tor will always allow connections to bridges, proxies, and
+ pluggable transports configured on private addresses.) Enabling this
+ option can create security issues; you should probably leave it off.
+ (Default: 0)
+
+[[GeoIPFile]] **GeoIPFile** __filename__::
+ A filename containing IPv4 GeoIP data, for use with by-country statistics.
+
+[[GeoIPv6File]] **GeoIPv6File** __filename__::
+ A filename containing IPv6 GeoIP data, for use with by-country statistics.
+
+[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**::
+ Log a heartbeat message every **HeartbeatPeriod** seconds. This is
+ a log level __notice__ message, designed to let you know your Tor
+ server is still alive and doing useful things. Settings this
+ to 0 will disable the heartbeat. Otherwise, it must be at least 30
+ minutes. (Default: 6 hours)
+
+[[IPv6Exit]] **IPv6Exit** **0**|**1**::
+ If set, and we are an exit node, allow clients to use us for IPv6 traffic.
+ When this option is set and ExitRelay is auto, we act as if ExitRelay
+ is 1. (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**|**auto**::
+ If this option is set to 0, don't allow the filesystem group to read the
+ KeyDirectory. If the option is set to 1, make the KeyDirectory readable
+ by the default GID. If the option is "auto", then we use the
+ setting for DataDirectoryGroupReadable when the KeyDirectory is the
+ same as the DataDirectory, and 0 otherwise. (Default: auto)
+
+[[MainloopStats]] **MainloopStats** **0**|**1**::
+ Log main loop statistics every **HeartbeatPeriod** seconds. This is a log
+ level __notice__ message designed to help developers instrumenting Tor's
+ main event loop. (Default: 0)
+
+[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]::
+ If we have more onionskins queued for processing than we can process in
+ this amount of time, reject new ones. (Default: 1750 msec)
+
+[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**::
+ This option configures a threshold above which Tor will assume that it
+ needs to stop queueing or buffering data because it's about to run out of
+ memory. If it hits this threshold, it will begin killing circuits until
+ it has recovered at least 10% of this memory. Do not set this option too
+ low, or your relay may be unreliable under load. This option only
+ affects some queues, so the actual process size will be larger than
+ this. If this option is set to 0, Tor will try to pick a reasonable
+ default based on your system's physical memory. (Default: 0)
+
+[[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. +
+ +
+ If you run more than one relay, the MyFamily option on each relay
+ **must** list all other relays, as described above. +
+ +
+ Note: do not use MyFamily when configuring your Tor instance as a
+ brigde.
+
+[[Nickname]] **Nickname** __name__::
+ Set the server's nickname to \'name'. Nicknames must be between 1 and 19
+ characters inclusive, and must contain only the characters [a-zA-Z0-9].
+ If not set, **Unnamed** will be used. Relays can always be uniquely identified
+ by their identity fingerprints.
+
+[[NumCPUs]] **NumCPUs** __num__::
+ How many processes to use at once for decrypting onionskins and other
+ parallelizable operations. If this is set to 0, Tor will try to detect
+ how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0)
+
+[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**::
+ If non-zero, the Tor relay will never generate or load its master secret
+ key. Instead, you'll have to use "tor --keygen" to manage the permanent
+ ed25519 master identity key, as well as the corresponding temporary
+ signing keys and certificates. (Default: 0)
+
+[[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]::
+ Advertise this port to listen for connections from Tor clients and
+ servers. This option is required to be a Tor server.
+ Set it to "auto" to have Tor pick a port for you. Set it to 0 to not
+ run an ORPort at all. This option can occur more than once. (Default: 0) +
+ +
+ Tor recognizes these flags on each ORPort:
+ **NoAdvertise**;;
+ By default, we bind to a port and tell our users about it. If
+ NoAdvertise is specified, we don't advertise, but listen anyway. This
+ can be useful if the port everybody will be connecting to (for
+ example, one that's opened on our firewall) is somewhere else.
+ **NoListen**;;
+ By default, we bind to a port and tell our users about it. If
+ NoListen is specified, we don't bind, but advertise anyway. This
+ can be useful if something else (for example, a firewall's port
+ forwarding configuration) is causing connections to reach us.
+ **IPv4Only**;;
+ If the address is absent, or resolves to both an IPv4 and an IPv6
+ address, only listen to the IPv4 address.
+ **IPv6Only**;;
+ If the address is absent, or resolves to both an IPv4 and an IPv6
+ address, only listen to the IPv6 address.
+
+// Anchor only for formatting, not visible in the man page.
+[[ORPortFlagsExclusive]]::
+ For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and
+ IPv4Only and IPv6Only are mutually exclusive.
+
+[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**::
+ This option specifies which descriptors Tor will publish when acting as
+ a relay. You can
+ choose multiple arguments, separated by commas. +
+ +
+ If this option is set to 0, Tor will not publish its
+ descriptors to any directories. (This is useful if you're testing
+ out your server, or if you're using a Tor controller that handles
+ directory publishing for you.) Otherwise, Tor will publish its
+ descriptors of all type(s) specified. The default is "1", which
+ means "if running as a relay or bridge, publish descriptors to the
+ appropriate authorities". Other possibilities are "v3", meaning
+ "publish as if you're a relay", and "bridge", meaning "publish as
+ if you're a bridge".
+
[[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**::
If set, use a reduced exit policy rather than the default one. +
+
@@ -2316,167 +2520,45 @@ is non-zero):
(Default: 0)
-[[IPv6Exit]] **IPv6Exit** **0**|**1**::
- If set, and we are an exit node, allow clients to use us for IPv6 traffic.
- When this option is set and ExitRelay is auto, we act as if ExitRelay
- is 1. (Default: 0)
+[[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**::
+ Prevent nodes that don't appear in the consensus from exiting using this
+ relay. If the option is 1, we always block exit attempts from such
+ nodes; if it's 0, we never do, and if the option is "auto", then we do
+ whatever the authorities suggest in the consensus (and block if the consensus
+ is quiet on the issue). (Default: auto)
-[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]::
- 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** __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. +
- +
- If you run more than one relay, the MyFamily option on each relay
- **must** list all other relays, as described above. +
- +
- Note: do not use MyFamily when configuring your Tor instance as a
- brigde.
-
-[[Nickname]] **Nickname** __name__::
- Set the server's nickname to \'name'. Nicknames must be between 1 and 19
- characters inclusive, and must contain only the characters [a-zA-Z0-9].
- If not set, **Unnamed** will be used. Relays can always be uniquely identified
- by their identity fingerprints.
-
-[[NumCPUs]] **NumCPUs** __num__::
- How many processes to use at once for decrypting onionskins and other
- parallelizable operations. If this is set to 0, Tor will try to detect
- how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0)
-
-[[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]::
- Advertise this port to listen for connections from Tor clients and
- servers. This option is required to be a Tor server.
- Set it to "auto" to have Tor pick a port for you. Set it to 0 to not
- run an ORPort at all. This option can occur more than once. (Default: 0) +
- +
- Tor recognizes these flags on each ORPort:
- **NoAdvertise**;;
- By default, we bind to a port and tell our users about it. If
- NoAdvertise is specified, we don't advertise, but listen anyway. This
- can be useful if the port everybody will be connecting to (for
- example, one that's opened on our firewall) is somewhere else.
- **NoListen**;;
- By default, we bind to a port and tell our users about it. If
- NoListen is specified, we don't bind, but advertise anyway. This
- can be useful if something else (for example, a firewall's port
- forwarding configuration) is causing connections to reach us.
- **IPv4Only**;;
- If the address is absent, or resolves to both an IPv4 and an IPv6
- address, only listen to the IPv4 address.
- **IPv6Only**;;
- If the address is absent, or resolves to both an IPv4 and an IPv6
- address, only listen to the IPv6 address.
-
-// Anchor only for formatting, not visible in the man page.
-[[ORPortFlagsExclusive]]::
- For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and
- IPv4Only and IPv6Only are mutually exclusive.
-
-[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**::
- This option specifies which descriptors Tor will publish when acting as
- a relay. You can
- choose multiple arguments, separated by commas. +
- +
- If this option is set to 0, Tor will not publish its
- descriptors to any directories. (This is useful if you're testing
- out your server, or if you're using a Tor controller that handles
- directory publishing for you.) Otherwise, Tor will publish its
- descriptors of all type(s) specified. The default is "1", which
- means "if running as a relay or bridge, publish descriptors to the
- appropriate authorities". Other possibilities are "v3", meaning
- "publish as if you're a relay", and "bridge", meaning "publish as
- if you're a bridge".
-
-[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__::
- When we get a SIGINT and we're a server, we begin shutting down:
- we close listeners and start refusing new circuits. After **NUM**
- seconds, we exit. If we get a second SIGINT, we exit immediately.
- (Default: 30 seconds)
-
-[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**::
- When creating a link certificate for our outermost SSL handshake,
- set its lifetime to this amount of time. If set to 0, Tor will choose
- some reasonable random defaults. (Default: 0)
-
-[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**::
- Log a heartbeat message every **HeartbeatPeriod** seconds. This is
- a log level __notice__ message, designed to let you know your Tor
- server is still alive and doing useful things. Settings this
- to 0 will disable the heartbeat. Otherwise, it must be at least 30
- minutes. (Default: 6 hours)
-
-[[MainloopStats]] **MainloopStats** **0**|**1**::
- Log main loop statistics every **HeartbeatPeriod** seconds. This is a log
- level __notice__ message designed to help developers instrumenting Tor's
- main event loop. (Default: 0)
+[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
+ Tells an authority, or other node tracking node reliability and history,
+ that fine-grained information about nodes can be discarded when it hasn't
+ changed for a given amount of time. (Default: 24 hours)
-[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**::
- Limits the max number of bytes sent and received within a set time period
- using a given calculation rule (see: AccountingStart, AccountingRule).
- Useful if you need to stay under a specific bandwidth. By default, the
- number used for calculation is the max of either the bytes sent or
- received. For example, with AccountingMax set to 1 TByte, a server
- could send 900 GBytes and receive 800 GBytes and continue running.
- It will only hibernate once one of the two reaches 1 TByte. This can
- be changed to use the sum of the both bytes received and sent by setting
- the AccountingRule option to "sum" (total bandwidth in/out). When the
- number of bytes remaining gets low, Tor will stop accepting new connections
- and circuits. When the number of bytes is exhausted, Tor will hibernate
- until some time in the next accounting period. To prevent all servers
- from waking at the same time, Tor will also wait until a random point
- in each period before waking up. If you have bandwidth cost issues,
- enabling hibernation is preferable to setting a low bandwidth, since
- it provides users with a collection of fast servers that are up some
- of the time, which is more useful than a set of slow servers that are
- always "available". +
- +
- Note that (as also described in the Bandwidth section) Tor uses
- powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not
- one billion. Be careful: some internet service providers might count
- GBytes differently.
+[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**::
+ If this option is false, Tor exits immediately if there are problems
+ parsing the system DNS configuration or connecting to nameservers.
+ Otherwise, Tor continues to periodically retry the system nameservers until
+ it eventually succeeds. (Default: 1)
-[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**::
- How we determine when our AccountingMax has been reached (when we
- should hibernate) during a time interval. Set to "max" to calculate
- using the higher of either the sent or received bytes (this is the
- default functionality). Set to "sum" to calculate using the sent
- plus received bytes. Set to "in" to calculate using only the
- received bytes. Set to "out" to calculate using only the sent bytes.
- (Default: max)
+[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
+ When this option is disabled, Tor does not try to resolve hostnames
+ containing illegal characters (like @ and :) rather than sending them to an
+ exit node to be resolved. This helps trap accidental attempts to resolve
+ URLs and so on. This option only affects name lookups that your server does
+ on behalf of clients. (Default: 0)
-[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
- Specify how long accounting periods last. If **month** is given,
- each accounting period runs from the time __HH:MM__ on the __dayth__ day of one
- month to the same day and time of the next. The relay will go at full speed,
- use all the quota you specify, then hibernate for the rest of the period. (The
- day must be between 1 and 28.) If **week** is given, each accounting period
- runs from the time __HH:MM__ of the __dayth__ day of one week to the same day
- and time of the next week, with Monday as day 1 and Sunday as day 7. If **day**
- is given, each accounting period runs from the time __HH:MM__ each day to the
- same time on the next day. All times are local, and given in 24-hour time.
- (Default: "month 1 0:00")
+[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**::
+ When this option is set to 1, we will test periodically to determine
+ whether our local nameservers have been configured to hijack failing DNS
+ requests (usually to an advertising site). If they are, we will attempt to
+ correct this. This option only affects name lookups that your server does
+ on behalf of clients. (Default: 1)
-[[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**::
- Prevent nodes that don't appear in the consensus from exiting using this
- relay. If the option is 1, we always block exit attempts from such
- nodes; if it's 0, we never do, and if the option is "auto", then we do
- whatever the authorities suggest in the consensus (and block if the consensus
- is quiet on the issue). (Default: auto)
+[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**::
+ When this option is set, Tor sets the case of each character randomly in
+ outgoing DNS requests, and makes sure that the case matches in DNS replies.
+ This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
+ For more information, see "Increased DNS Forgery Resistance through
+ 0x20-Bit Encoding". This option only affects name lookups that your server
+ does on behalf of clients. (Default: 1)
[[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__::
Overrides the default DNS configuration with the configuration in
@@ -2486,12 +2568,6 @@ is non-zero):
(Defaults to use the system DNS configuration or a localhost DNS service
in case no nameservers are found in a given configuration.)
-[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**::
- If this option is false, Tor exits immediately if there are problems
- parsing the system DNS configuration or connecting to nameservers.
- Otherwise, Tor continues to periodically retry the system nameservers until
- it eventually succeeds. (Default: 1)
-
[[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**::
If set to 1, then we will search for addresses in the local search domain.
For example, if this system is configured to believe it is in
@@ -2499,13 +2575,6 @@ is non-zero):
connected to "www.example.com". This option only affects name lookups that
your server does on behalf of clients. (Default: 0)
-[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**::
- When this option is set to 1, we will test periodically to determine
- whether our local nameservers have been configured to hijack failing DNS
- requests (usually to an advertising site). If they are, we will attempt to
- correct this. This option only affects name lookups that your server does
- on behalf of clients. (Default: 1)
-
[[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __hostname__,__hostname__,__...__::
When we're detecting DNS hijacking, make sure that these __valid__ addresses
aren't getting redirected. If they are, then our DNS is completely useless,
@@ -2513,33 +2582,32 @@ is non-zero):
name lookups that your server does on behalf of clients. (Default:
"www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org")
-[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
- When this option is disabled, Tor does not try to resolve hostnames
- containing illegal characters (like @ and :) rather than sending them to an
- exit node to be resolved. This helps trap accidental attempts to resolve
- URLs and so on. This option only affects name lookups that your server does
- on behalf of clients. (Default: 0)
+[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__::
+ When we get a SIGINT and we're a server, we begin shutting down:
+ we close listeners and start refusing new circuits. After **NUM**
+ seconds, we exit. If we get a second SIGINT, we exit immediately.
+ (Default: 30 seconds)
-[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**::
- When this option is enabled and BridgeRelay is also enabled, and we have
- GeoIP data, Tor keeps a per-country count of how many client
- addresses have contacted it so that it can help the bridge authority guess
- which countries have blocked access to it. If ExtraInfoStatistics is
- enabled, it will be published as part of extra-info document. (Default: 1)
+[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**::
+ For how long should each Ed25519 signing key be valid? Tor uses a
+ permanent master identity key that can be kept offline, and periodically
+ generates new "signing" keys that it uses online. This option
+ configures their lifetime.
+ (Default: 30 days)
-[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**::
- When this option is set, Tor sets the case of each character randomly in
- outgoing DNS requests, and makes sure that the case matches in DNS replies.
- This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
- For more information, see "Increased DNS Forgery Resistance through
- 0x20-Bit Encoding". This option only affects name lookups that your server
- does on behalf of clients. (Default: 1)
+[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**::
+ When creating a link certificate for our outermost SSL handshake,
+ set its lifetime to this amount of time. If set to 0, Tor will choose
+ some reasonable random defaults. (Default: 0)
-[[GeoIPFile]] **GeoIPFile** __filename__::
- A filename containing IPv4 GeoIP data, for use with by-country statistics.
+== STATISTICS OPTIONS
-[[GeoIPv6File]] **GeoIPv6File** __filename__::
- A filename containing IPv6 GeoIP data, for use with by-country statistics.
+// These options are in alphabetical order, with exceptions as noted.
+// Please keep them that way!
+
+Relays publish most statistics in a document called the
+extra-info document. The following options describe the different
+types of statistics that Tor collects and writes:
[[CellStatistics]] **CellStatistics** **0**|**1**::
Relays only.
@@ -2551,14 +2619,14 @@ is non-zero):
If ExtraInfoStatistics is enabled, it will published as part of
extra-info document. (Default: 0)
-[[PaddingStatistics]] **PaddingStatistics** **0**|**1**::
- Relays and bridges 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.
- If ExtraInfoStatistics is enabled, it will be published
- as a part of extra-info document. (Default: 1)
+[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**::
+ Relays only.
+ When this option is enabled, Tor writes statistics on the amounts of
+ traffic it passes between itself and other relays to disk every 24
+ hours. Enables relay operators to monitor how much their relay is
+ being used as middle node in the circuit. If ExtraInfoStatistics is
+ enabled, it will be published as part of extra-info document.
+ (Default: 0)
[[DirReqStatistics]] **DirReqStatistics** **0**|**1**::
Relays and bridges only.
@@ -2587,23 +2655,6 @@ is non-zero):
is enabled, it will be published as part of extra-info document.
(Default: 0)
-[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**::
- Relays only.
- When this option is enabled, Tor writes statistics on the amounts of
- traffic it passes between itself and other relays to disk every 24
- hours. Enables relay operators to monitor how much their relay is
- being used as middle node in the circuit. If ExtraInfoStatistics is
- enabled, it will be published as part of extra-info document.
- (Default: 0)
-
-[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**::
- Relays only.
- When this option is enabled, a Tor relay writes obfuscated
- statistics on its role as hidden-service directory, introduction
- point, or rendezvous point to disk every 24 hours. If
- ExtraInfoStatistics is also enabled, these statistics are further
- published to the directory authorities. (Default: 1)
-
[[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**::
When this option is enabled, Tor includes previously gathered statistics in
its extra-info documents that it uploads to the directory authorities.
@@ -2613,61 +2664,22 @@ is non-zero):
because they are required by BridgeDB.
(Default: 1)
-[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**::
- When this option is enabled, Tor will connect to relays on localhost,
- RFC1918 addresses, and so on. In particular, Tor will make direct OR
- connections, and Tor routers allow EXTEND requests, to these private
- addresses. (Tor will always allow connections to bridges, proxies, and
- pluggable transports configured on private addresses.) Enabling this
- option can create security issues; you should probably leave it off.
- (Default: 0)
-
-[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**::
- This option configures a threshold above which Tor will assume that it
- needs to stop queueing or buffering data because it's about to run out of
- memory. If it hits this threshold, it will begin killing circuits until
- it has recovered at least 10% of this memory. Do not set this option too
- low, or your relay may be unreliable under load. This option only
- affects some queues, so the actual process size will be larger than
- this. If this option is set to 0, Tor will try to pick a reasonable
- default based on your system's physical memory. (Default: 0)
-
-[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**::
- This option disables the code that closes connections when Tor notices
- that it is running low on sockets. Right now, it is on by default,
- since the existing out-of-sockets mechanism tends to kill OR connections
- more than it should. (Default: 1)
-
-[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**::
- For how long should each Ed25519 signing key be valid? Tor uses a
- permanent master identity key that can be kept offline, and periodically
- generates new "signing" keys that it uses online. This option
- configures their lifetime.
- (Default: 30 days)
-
-[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**::
- If non-zero, the Tor relay will never generate or load its master secret
- key. Instead, you'll have to use "tor --keygen" to manage the permanent
- 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**|**auto**::
- If this option is set to 0, don't allow the filesystem group to read the
- KeyDirectory. If the option is set to 1, make the KeyDirectory readable
- by the default GID. If the option is "auto", then we use the
- setting for DataDirectoryGroupReadable when the KeyDirectory is the
- same as the DataDirectory, and 0 otherwise. (Default: auto)
-
-[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
- Tells an authority, or other node tracking node reliability and history,
- that fine-grained information about nodes can be discarded when it hasn't
- changed for a given amount of time. (Default: 24 hours)
+[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**::
+ Relays only.
+ When this option is enabled, a Tor relay writes obfuscated
+ statistics on its role as hidden-service directory, introduction
+ point, or rendezvous point to disk every 24 hours. If
+ ExtraInfoStatistics is also enabled, these statistics are further
+ published to the directory authorities. (Default: 1)
+[[PaddingStatistics]] **PaddingStatistics** **0**|**1**::
+ Relays and bridges 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.
+ If ExtraInfoStatistics is enabled, it will be published
+ as a part of extra-info document. (Default: 1)
== DIRECTORY SERVER OPTIONS
@@ -2675,11 +2687,19 @@ The following options are useful only for directory servers. (Relays with
enough bandwidth automatically become directory servers; see DirCache for
details.)
-[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__::
- When this option is set, it takes an HTML file and publishes it as "/" on
- the DirPort. Now relay operators can provide a disclaimer without needing
- to set up a separate webserver. There's a sample disclaimer in
- contrib/operator-tools/tor-exit-notice.html.
+[[DirCache]] **DirCache** **0**|**1**::
+ When this option is set, Tor caches all current directory documents except
+ extra info documents, and accepts client requests for them. If
+ **DownloadExtraInfo** is set, cached extra info documents are also cached.
+ Setting **DirPort** is not required for **DirCache**, because clients
+ connect via the ORPort by default. Setting either DirPort or BridgeRelay
+ and setting DirCache to 0 is not supported. (Default: 1)
+
+[[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,
+ except that port specifiers are ignored. Any address not matched by
+ some entry in the policy is accepted.
[[DirPort]] **DirPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]::
If this option is nonzero, advertise the directory service on this port.
@@ -2689,19 +2709,11 @@ details.)
+
The same flags are supported here as are supported by ORPort.
-[[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,
- except that port specifiers are ignored. Any address not matched by
- some entry in the policy is accepted.
-
-[[DirCache]] **DirCache** **0**|**1**::
- When this option is set, Tor caches all current directory documents except
- extra info documents, and accepts client requests for them. If
- **DownloadExtraInfo** is set, cached extra info documents are also cached.
- Setting **DirPort** is not required for **DirCache**, because clients
- connect via the ORPort by default. Setting either DirPort or BridgeRelay
- and setting DirCache to 0 is not supported. (Default: 1)
+[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__::
+ When this option is set, it takes an HTML file and publishes it as "/" on
+ the DirPort. Now relay operators can provide a disclaimer without needing
+ to set up a separate webserver. There's a sample disclaimer in
+ contrib/operator-tools/tor-exit-notice.html.
[[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs** __N__ **minutes**|**hours**|**days**|**weeks**::
When this option is nonzero, Tor caches will not try to generate
More information about the tor-commits
mailing list