commit 14cc126e3ee0a0287f3546ab8f026807161fcec2
Author: Nick Mathewson <nickm(a)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
