commit 14cc126e3ee0a0287f3546ab8f026807161fcec2 Author: Nick Mathewson nickm@torproject.org Date: Mon Sep 28 09:40:36 2020 -0400
param-spec: reindent --- param-spec.txt | 451 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 237 insertions(+), 214 deletions(-)
diff --git a/param-spec.txt b/param-spec.txt index af0c0a3..bc28044 100644 --- a/param-spec.txt +++ b/param-spec.txt @@ -1,88 +1,87 @@
Tor network parameters
-1. Network protocol parameters - - "circwindow" -- the default package window that circuits should - be established with. It started out at 1000 cells, but some - research indicates that a lower value would mean fewer cells in - transit in the network at any given time. - Min: 100, Max: 1000 - First-appeared: Tor 0.2.1.20 +This file lists the recognized parameters that can appear on the "params" +line of a directory consensus.
- "refuseunknownexits" -- if set to one, exit relays look at - the previous hop of circuits that ask to open an exit stream, - and refuse to exit if they don't recognize it as a relay. The - goal is to make it harder for people to use them as one-hop - proxies. See trac entry 1751 for details. - Min: 0, Max: 1 - First-appeared: 0.2.2.17-alpha +1. Network protocol parameters
+ "circwindow" -- the default package window that circuits should be + established with. It started out at 1000 cells, but some research + indicates that a lower value would mean fewer cells in transit in the + network at any given time. + Min: 100, Max: 1000 + First-appeared: Tor 0.2.1.20
- "UseOptimisticData" -- If set to zero, clients by default - shouldn't try to send optimistic data to servers until they have - received a RELAY_CONNECTED cell. - Min: 0, Max: 1, Default: 1 - First-appeared: 0.2.3.3-alpha - Default was 0 before: 0.2.9.1-alpha + "refuseunknownexits" -- if set to one, exit relays look at the previous + hop of circuits that ask to open an exit stream, and refuse to exit if + they don't recognize it as a relay. The goal is to make it harder for + people to use them as one-hop proxies. See trac entry 1751 for details. + Min: 0, Max: 1 + First-appeared: 0.2.2.17-alpha
- "usecreatefast" -- Used to control whether clients use the - CREATE_FAST handshake on the first hop of their circuits. - Min: 0, Max: 1. Default: 1. - First-appeared: 0.2.4.23, 0.2.5.2-alpha + "UseOptimisticData" -- If set to zero, clients by default shouldn't try + to send optimistic data to servers until they have received a + RELAY_CONNECTED cell. + Min: 0, Max: 1, Default: 1 + First-appeared: 0.2.3.3-alpha + Default was 0 before: 0.2.9.1-alpha
- "min_paths_for_circs_pct" -- DOCDOC + "usecreatefast" -- Used to control whether clients use the CREATE_FAST + handshake on the first hop of their circuits. + Min: 0, Max: 1. Default: 1. + First-appeared: 0.2.4.23, 0.2.5.2-alpha
+ "min_paths_for_circs_pct" -- DOCDOC
- "AllowNonearlyExtend" -- If true, permit EXTEND cells that are not - inside RELAY_EARLY cells. - Min: 0. Max: 1. Default: 0. - First-appeared: 0.2.3.11-alpha + "AllowNonearlyExtend" -- If true, permit EXTEND cells that are not inside + RELAY_EARLY cells. + Min: 0. Max: 1. Default: 0. + First-appeared: 0.2.3.11-alpha
- "ExtendByEd25519ID" -- DOCDOC + "ExtendByEd25519ID" -- DOCDOC
2. Performance-tuning parameters
- "CircuitPriorityHalflifeMsec" -- the halflife parameter used when - weighting which circuit will send the next cell. Obeyed by Tor - 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha - and 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter, - but mishandled it badly.) - Min: -1, Max: 2147483647 (INT32_MAX) - First-appeared: Tor 0.2.2.11-alpha - - "perconnbwrate" and "perconnbwburst" -- if set, each relay sets - up a separate token bucket for every client OR connection, - and rate limits that connection indepedently. Typically left - unset, except when used for performance experiments around trac - entry 1750. Only honored by relays running Tor 0.2.2.16-alpha - and later. (Note that relays running 0.2.2.7-alpha through - 0.2.2.14-alpha looked for bwconnrate and bwconnburst, but then - did the wrong thing with them; see bug 1830 for details.) - Min: 1, Max: 2147483647 (INT32_MAX) - First-appeared: 0.2.2.7-alpha - Removed-in: 0.2.2.16-alpha - - "NumNTorsPerTAP" -- When balancing ntor and TAP cells at relays, - how many ntor handshakes should we perform for each TAP handshake? - Min: 1. Max: 100000. Default: 10. - First-appeared: 0.2.4.17-rc - - "circ_max_cell_queue_size" -- This parameter determines the maximum - number of cells allowed per circuit queue. - Min 1000. Max 4294967295. Default 50000. - First-appeared: 0.3.3.6-rc. - - - "sendme_emit_min_version" -- Minimum SENDME version that can be sent. - Min: 0. Max: 255. Default 0. First - appeared: 0.4.1.1-alpha. - - "sendme_accept_min_version" -- Minimum SENDME version that is accepted. - Min: 0. Max: 255. Default 0. First - appeared: 0.4.1.1-alpha. - + "CircuitPriorityHalflifeMsec" -- the halflife parameter used when + weighting which circuit will send the next cell. Obeyed by Tor + 0.2.2.10-alpha and later. (Versions of Tor between 0.2.2.7-alpha and + 0.2.2.10-alpha recognized a "CircPriorityHalflifeMsec" parameter, but + mishandled it badly.) + Min: -1, Max: 2147483647 (INT32_MAX) + First-appeared: Tor 0.2.2.11-alpha + + "perconnbwrate" and "perconnbwburst" -- if set, each relay sets up a + separate token bucket for every client OR connection, and rate limits + that connection indepedently. Typically left unset, except when used for + performance experiments around trac entry 1750. Only honored by relays + running Tor 0.2.2.16-alpha and later. (Note that relays running + 0.2.2.7-alpha through 0.2.2.14-alpha looked for bwconnrate and + bwconnburst, but then did the wrong thing with them; see bug 1830 for + details.) + Min: 1, Max: 2147483647 (INT32_MAX) + First-appeared: 0.2.2.7-alpha + Removed-in: 0.2.2.16-alpha + + "NumNTorsPerTAP" -- When balancing ntor and TAP cells at relays, + how many ntor handshakes should we perform for each TAP handshake? + Min: 1. Max: 100000. Default: 10. + First-appeared: 0.2.4.17-rc + + "circ_max_cell_queue_size" -- This parameter determines the maximum + number of cells allowed per circuit queue. + Min 1000. Max 4294967295. Default 50000. + First-appeared: 0.3.3.6-rc. + + + "sendme_emit_min_version" -- Minimum SENDME version that can be sent. + Min: 0. Max: 255. Default 0. First + appeared: 0.4.1.1-alpha. + + "sendme_accept_min_version" -- Minimum SENDME version that is accepted. + Min: 0. Max: 255. Default 0. First + appeared: 0.4.1.1-alpha.
"KISTSchedRunInterval" -- DOCDOC
@@ -91,227 +90,251 @@
3. Voting-related parameters
- "bwweightscale" -- Value that bandwidth-weights are divided by. If not - present then this defaults to 10000. - Min: 1 - First-appeared: 0.2.2.10-alpha - - "maxunmeasuredbw" -- Used by authorities during voting with - method 17 or later. The maximum value to give for any Bandwidth= - entry for a router that isn't based on at least three - measurements. - First-appeared: 0.2.4.11-alpha - - "FastFlagMinThreshold", "FastFlagMaxThreshold" -- lowest and - highest allowable values for the cutoff for routers that should get - the Fast flag. This is used during voting to prevent the threshold - for getting the Fast flag from being too low or too high. - FastFlagMinThreshold: Min: 4. Max: INT32_MAX: Default: 4. - FastFlagMaxThreshold: Min: -. Max: INT32_MAX: Default: INT32_MAX - First-appeared: 0.2.3.11-alpha - - "AuthDirNumSRVAgreements" -- Minimum number of agreeing directory - authority votes required for a fresh shared random value to be written - in the consensus (this rule only applies on the first commit round of - the shared randomness protocol). - Min: 1. Max: INT32_MAX. Default: 2/3 of the total number of - dirauth. + "bwweightscale" -- Value that bandwidth-weights are divided by. If not + present then this defaults to 10000. + Min: 1 + First-appeared: 0.2.2.10-alpha + + "maxunmeasuredbw" -- Used by authorities during voting with method 17 or + later. The maximum value to give for any Bandwidth= entry for a router + that isn't based on at least three measurements. + First-appeared: 0.2.4.11-alpha + + "FastFlagMinThreshold", "FastFlagMaxThreshold" -- lowest and highest + allowable values for the cutoff for routers that should get the Fast + flag. This is used during voting to prevent the threshold for getting + the Fast flag from being too low or too high. + FastFlagMinThreshold: Min: 4. Max: INT32_MAX: Default: 4. + FastFlagMaxThreshold: Min: -. Max: INT32_MAX: Default: INT32_MAX + First-appeared: 0.2.3.11-alpha + + "AuthDirNumSRVAgreements" -- Minimum number of agreeing directory + authority votes required for a fresh shared random value to be written in + the consensus (this rule only applies on the first commit round of the + shared randomness protocol). + Min: 1. Max: INT32_MAX. Default: 2/3 of the total number of + dirauth.
4. Circuit-build-timeout parameters
- "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts", - "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq", - "cbtmintimeout", "cbtlearntimeout", "cbtmaxopencircs", and - "cbtinitialtimeout" -- see "2.4.5. Consensus parameters governing - behavior" in path-spec.txt for a series of circuit build time related - consensus params. + "cbtdisabled", "cbtnummodes", "cbtrecentcount", "cbtmaxtimeouts", + "cbtmincircs", "cbtquantile", "cbtclosequantile", "cbttestfreq", + "cbtmintimeout", "cbtlearntimeout", "cbtmaxopencircs", and + "cbtinitialtimeout" -- see "2.4.5. Consensus parameters governing + behavior" in path-spec.txt for a series of circuit build time related + consensus parameters.
5. Directory-related parameters
- "max-consensus-age-to-cache-for-diff" -- Determines how - much consensus history (in hours) relays should try to cache - in order to serve diffs. (min 0, max 8192, default 72) + "max-consensus-age-to-cache-for-diff" -- Determines how much + consensus history (in hours) relays should try to cache in order to + serve diffs. (min 0, max 8192, default 72)
- "try-diff-for-consensus-newer-than" -- This parameter - determines how old a consensus can be (in hours) before a - client should no longer try to find a diff for it. (min 0, - max 8192, default 72) + "try-diff-for-consensus-newer-than" -- This parameter determines how + old a consensus can be (in hours) before a client should no longer + try to find a diff for it. (min 0, max 8192, default 72)
6. Pathbias parameters
- "pb_mincircs", "pb_noticepct", "pb_warnpct", "pb_extremepct", - "pb_dropguards", "pb_scalecircs", "pb_scalefactor", - "pb_multfactor", "pb_minuse", "pb_noticeusepct", - "pb_extremeusepct", "pb_scaleuse" -- DOCDOC + "pb_mincircs", "pb_noticepct", "pb_warnpct", "pb_extremepct", + "pb_dropguards", "pb_scalecircs", "pb_scalefactor", + "pb_multfactor", "pb_minuse", "pb_noticeusepct", + "pb_extremeusepct", "pb_scaleuse" -- DOCDOC
7. Relay behavior
+ "onion-key-rotation-days" -- (min 1, max 90, default 28) + + "onion-key-grace-period-days" -- (min 1, max + onion-key-rotation-days, default 7)
- onion key lifetime parameters: - "onion-key-rotation-days" -- (min 1, max 90, default 28) - "onion-key-grace-period-days" -- (min 1, max - onion-key-rotation-days, default 7) - Every relay should list each onion key it generates for - onion-key-rotation-days days after generating it, and then - replace it. Relays should continue to accept their most recent - previous onion key for an additional onion-key-grace-period-days - days after it is replaced. (Introduced in 0.3.1.1-alpha; - prior versions of tor hardcoded both of these values to 7 days.) + Every relay should list each onion key it generates for + onion-key-rotation-days days after generating it, and then + replace it. Relays should continue to accept their most recent + previous onion key for an additional onion-key-grace-period-days + days after it is replaced. (Introduced in 0.3.1.1-alpha; + prior versions of tor hardcoded both of these values to 7 days.)
8. V3 onion service parameters
+ "hs_intro_min_introduce2", "hs_intro_max_introduce2" -- + Minimum/maximum amount of INTRODUCE2 cells allowed per circuits + before rotation (actual amount picked at random between these two + values). + + "hs_intro_min_lifetime", "hs_intro_max_lifetime" -- Minimum/maximum + lifetime in seconds that a service should keep an intro point for + (actual lifetime picked at random between these two values). + + "hs_intro_num_extra" -- Number of extra intro points a service is + allowed to open. This concept comes from proposal #155. + + "hsdir_interval" -- The length of a time period. See + rend-spec-v3.txt section [TIME-PERIODS]. + + "hsdir_n_replicas" -- Number of HS descriptor replicas. + + "hsdir_spread_fetch" -- Total number of HSDirs per replica a tor + client should select to try to fetch a descriptor.
+ "hsdir_spread_store" -- Total number of HSDirs per replica a service + will upload its descriptor to.
- Hidden service v3 parameters: - "hs_intro_min_introduce2" - "hs_intro_max_introduce2" -- Minimum/maximum amount of INTRODUCE2 cells - allowed per circuits before rotation (actual - amount picked at random between these two values). - "hs_intro_min_lifetime" - "hs_intro_max_lifetime" -- Minimum/maximum lifetime in seconds that a service - should keep an intro point for (actual lifetime picked at - random between these two values). - "hs_intro_num_extra" -- Number of extra intro points a service is allowed to open. - This concept comes from proposal #155. - "hsdir_interval" -- The length of a time period. See rend-spec-v3.txt - section [TIME-PERIODS]. - "hsdir_n_replicas" -- Number of HS descriptor replicas. - "hsdir_spread_fetch" -- Total number of HSDirs per replica a tor client - should select to try to fetch a descriptor. - "hsdir_spread_store" -- Total number of HSDirs per replica a service - will upload its descriptor to. - "HSV3MaxDescriptorSize" -- Maximum descriptor size (in bytes). - - "hs_service_max_rdv_failures" -- This parameter determines the maximum - number of rendezvous attempt an HS service can make per introduction. - Min 1. Max 10. Default 2. - First-appeared: 0.3.3.0-alpha. - - "HiddenServiceEnableIntroDoSDefense" -- This parameter makes tor start - using this new proposed extension if available by the introduction - point (for protover HSIntro=5). Min: 0. Max: 1. Default: 0. First - appeared: 0.4.2.1-alpha. + "HSV3MaxDescriptorSize" -- Maximum descriptor size (in bytes). + + "hs_service_max_rdv_failures" -- This parameter determines the + maximum number of rendezvous attempt an HS service can make per + introduction. Min 1. Max 10. Default 2. First-appeared: + 0.3.3.0-alpha. + + "HiddenServiceEnableIntroDoSDefense" -- This parameter makes tor + start using this new proposed extension if available by the + introduction point (for protover HSIntro=5). Min: 0. Max: + 1. Default: 0. First appeared: 0.4.2.1-alpha.
"HiddenServiceEnableIntroDoSBurstPerSec" -- DOCDOC - "HiddenServiceEnableIntroDoSRatePerSec" -- DOCDOC
+ "HiddenServiceEnableIntroDoSRatePerSec" -- DOCDOC
9. Denial-of-service parameters
- Denial of Service mitigation parameters. Introduced in 0.3.3.2-alpha: - - "DoSCircuitCreationEnabled" -- Enable the circuit creation DoS - mitigation. + Denial of Service mitigation parameters. Introduced in 0.3.3.2-alpha:
- "DoSCircuitCreationMinConnections" -- Minimum threshold of concurrent - connections before a client address can be flagged as executing a - circuit creation DoS + "DoSCircuitCreationEnabled" -- Enable the circuit creation DoS + mitigation.
- "DoSCircuitCreationRate" -- Allowed circuit creation rate per second - per client IP address once the minimum concurrent connection - threshold is reached. + "DoSCircuitCreationMinConnections" -- Minimum threshold of + concurrent connections before a client address can be flagged as + executing a circuit creation DoS
- "DoSCircuitCreationBurst" -- The allowed circuit creation burst per - client IP address once the minimum concurrent connection threshold is - reached. + "DoSCircuitCreationRate" -- Allowed circuit creation rate per second + per client IP address once the minimum concurrent connection + threshold is reached.
- "DoSCircuitCreationDefenseType" -- Defense type applied to a detected - client address for the circuit creation mitigation. + "DoSCircuitCreationBurst" -- The allowed circuit creation burst per + client IP address once the minimum concurrent connection threshold + is reached.
- 1: No defense. - 2: Refuse circuit creation for the - DoSCircuitCreationDefenseTimePeriod period. + "DoSCircuitCreationDefenseType" -- Defense type applied to a + detected client address for the circuit creation mitigation. + 1: No defense. + 2: Refuse circuit creation for the length of + "DoSCircuitCreationDefenseTimePeriod".
- "DoSCircuitCreationDefenseTimePeriod" -- The base time period that - the DoS defense is activated for.
- "DoSConnectionEnabled" -- Enable the connection DoS mitigation. + "DoSCircuitCreationDefenseTimePeriod" -- The base time period that + the DoS defense is activated for.
- "DoSConnectionMaxConcurrentCount" -- The maximum threshold of - concurrent connection from a client IP address. + "DoSConnectionEnabled" -- Enable the connection DoS mitigation.
- "DoSConnectionDefenseType" -- Defense type applied to a detected - client address for the connection mitigation. Possible values are: + "DoSConnectionMaxConcurrentCount" -- The maximum threshold of + concurrent connection from a client IP address.
- 1: No defense. - 2: Immediately close new connections. + "DoSConnectionDefenseType" -- Defense type applied to a detected + client address for the connection mitigation. Possible values are: + 1: No defense. + 2: Immediately close new connections.
- "DoSRefuseSingleHopClientRendezvous" -- Refuse establishment of - rendezvous points for single hop clients. + "DoSRefuseSingleHopClientRendezvous" -- Refuse establishment of + rendezvous points for single hop clients.
10. Padding-related parameters
- "circpad_max_circ_queued_cells" -- The circuitpadding module will - stop sending more padding cells if more than this many cells are in - the circuit queue a given circuit. Min: 0. Max: 50000. Default 1000. - First appeared: 0.4.0.3-alpha. + "circpad_max_circ_queued_cells" -- The circuitpadding module will + stop sending more padding cells if more than this many cells are in + the circuit queue a given circuit. + Min: 0. Max: 50000. Default 1000. + First appeared: 0.4.0.3-alpha.
"circpad_global_allowed_cells" -- DOCDOC + "circpad_global_max_padding_pct" -- DOCDOC + "circpad_padding_disabled" -- DOCDOC + "circpad_padding_reduced" -- DOCDOC
"nf_conntimeout_clients" -- DOCDOC + "nf_conntimeout_relays" -- DOCDOC + "nf_ito_high_reduced" -- DOCDOC + "nf_ito_low" -- DOCDOC + "nf_ito_low_reduced" -- DOCDOC + "nf_pad_before_usage" -- DOCDOC + "nf_pad_relays" -- DOCDOC + "nf_pad_single_onion" -- DOCDOC
11. Guard-related parameters
"guard-confirmed-min-lifetime-days" -- DOCDOC + "guard-extreme-restriction-percent" -- DOCDOC + "guard-internet-likely-down-interval" -- DOCDOC + "guard-lifetime-days" -- DOCDOC + "guard-max-samlines" -- DOCDOC + "guard-max-sample-size" -- DOCDOC + "guard-meaningful-restriction-percent" -- DOCDOC + "guard-min-filtered-sample-size" -- DOCDOC + "guard-n-primary-dir-guards-to-use" -- DOCDOC + "guard-n-primary-guards" -- DOCDOC + "guard-n-primary-guards-to-use" -- DOCDOC + "guard-nonprimary-guard-connect-timeout" -- DOCDOC + "guard-nonprimary-guard-idle-timeout" -- DOCDOC + "guard-remove-unlisted-guards-after-days" -- DOCDOC
12. Relay behavior
"assume-reachable" -- DOCDOC + "assume-reachable-ipv6" -- DOCDOC
X. Obsolete parameters
- "NumDirectoryGuards", "NumEntryGuards" -- Number of guard nodes - clients should use by default. If NumDirectoryGuards is 0, - we default to NumEntryGuards. - NumDirectoryGuards: Min: 0. Max: 10. Default: 0 - NumEntryGuards: Min: 1. Max: 10. Default: 3 - First-appeared: 0.2.4.23, 0.2.5.6-alpha - Removed in: 0.3.0 - - "GuardLifetime" -- Duration for which clients should choose guard - nodes, in seconds. - Min: 30 days. Max: 1826 days. Default: 60 days. - First-appeared: 0.2.4.12-alpha - Removed in: 0.3.0. - - "UseNTorHandshake" -- If true, then versions of Tor that support - NTor will prefer to use it by default. - Min: 0, Max: 1. Default: 1. - First-appeared: 0.2.4.8-alpha - Removed in: 0.2.9. - - "Support022HiddenServices" -- Used to implement a mass switch-over - from sending timestamps to hidden services by default to sending - no timestamps at all. If this option is absent, or is set to 1, - clients with the default configuration send timestamps; otherwise, - they do not. - Min: 0, Max: 1. Default: 1. - First-appeared: 0.2.4.18-rc - Removed in: 0.2.6 - + "NumDirectoryGuards", "NumEntryGuards" -- Number of guard nodes + clients should use by default. If NumDirectoryGuards is 0, we + default to NumEntryGuards. + NumDirectoryGuards: Min: 0. Max: 10. Default: 0 + NumEntryGuards: Min: 1. Max: 10. Default: 3 + First-appeared: 0.2.4.23, 0.2.5.6-alpha + Removed in: 0.3.0 + + "GuardLifetime" -- Duration for which clients should choose guard + nodes, in seconds. + Min: 30 days. Max: 1826 days. Default: 60 days. + First-appeared: 0.2.4.12-alpha + Removed in: 0.3.0. + + "UseNTorHandshake" -- If true, then versions of Tor that support + NTor will prefer to use it by default. + Min: 0, Max: 1. Default: 1. + First-appeared: 0.2.4.8-alpha + Removed in: 0.2.9. + + "Support022HiddenServices" -- Used to implement a mass switch-over + from sending timestamps to hidden services by default to sending no + timestamps at all. If this option is absent, or is set to 1, + clients with the default configuration send timestamps; otherwise, + they do not. + Min: 0, Max: 1. Default: 1. + First-appeared: 0.2.4.18-rc + Removed in: 0.2.6