[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [torspec/master] Split out list of consensus parameters into a new file.



commit 13d2337917f43566095caf88ff2dc4bbf08482ba
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date:   Mon Sep 28 09:03:55 2020 -0400

    Split out list of consensus parameters into a new file.
    
    No editing yet; only movement.
---
 dir-spec.txt   | 233 +--------------------------------------------------------
 param-spec.txt | 233 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 234 insertions(+), 232 deletions(-)

diff --git a/dir-spec.txt b/dir-spec.txt
index 27d380f..236ee55 100644
--- a/dir-spec.txt
+++ b/dir-spec.txt
@@ -1921,238 +1921,7 @@
         (Only included when the vote is generated with consensus-method 7 or
         later.)
 
-        Commonly used "param" arguments at this point include:
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "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.
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "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
-
-        "min_paths_for_circs_pct" -- DOCDOC
-
-        "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
-
-        "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
-
-        "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.
-
-        "max-consensuses-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)
-
-        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.)
-
-        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.
-
-        Denial of Service mitigation parameters. Introduced in 0.3.3.2-alpha:
-
-         "DoSCircuitCreationEnabled" -- Enable the circuit creation DoS
-         mitigation.
-
-         "DoSCircuitCreationMinConnections" -- Minimum threshold of concurrent
-         connections before a client address can be flagged as executing a
-         circuit creation DoS
-
-         "DoSCircuitCreationRate" -- Allowed circuit creation rate per second
-         per client IP address once the minimum concurrent connection
-         threshold is reached.
-
-         "DoSCircuitCreationBurst" -- The allowed circuit creation burst 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.
-
-            1: No defense.
-            2: Refuse circuit creation for the
-               DoSCircuitCreationDefenseTimePeriod period.
-
-         "DoSCircuitCreationDefenseTimePeriod" -- The base time period that
-         the DoS defense is activated for.
-
-         "DoSConnectionEnabled" -- Enable the connection DoS mitigation.
-
-         "DoSConnectionMaxConcurrentCount" -- The maximum threshold of
-         concurrent connection from a client IP address.
-
-         "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.
-
-        "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.
-
-        "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.
-
-        "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.
-
-        "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.
+        See param-spec.txt for a list of parameters and their meanings.
 
     "shared-rand-previous-value" SP NumReveals SP Value NL
 
diff --git a/param-spec.txt b/param-spec.txt
new file mode 100644
index 0000000..31aa4be
--- /dev/null
+++ b/param-spec.txt
@@ -0,0 +1,233 @@
+
+        Commonly used "param" arguments at this point include:
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "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.
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "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
+
+        "min_paths_for_circs_pct" -- DOCDOC
+
+        "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
+
+        "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
+
+        "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.
+
+        "max-consensuses-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)
+
+        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.)
+
+        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.
+
+        Denial of Service mitigation parameters. Introduced in 0.3.3.2-alpha:
+
+         "DoSCircuitCreationEnabled" -- Enable the circuit creation DoS
+         mitigation.
+
+         "DoSCircuitCreationMinConnections" -- Minimum threshold of concurrent
+         connections before a client address can be flagged as executing a
+         circuit creation DoS
+
+         "DoSCircuitCreationRate" -- Allowed circuit creation rate per second
+         per client IP address once the minimum concurrent connection
+         threshold is reached.
+
+         "DoSCircuitCreationBurst" -- The allowed circuit creation burst 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.
+
+            1: No defense.
+            2: Refuse circuit creation for the
+               DoSCircuitCreationDefenseTimePeriod period.
+
+         "DoSCircuitCreationDefenseTimePeriod" -- The base time period that
+         the DoS defense is activated for.
+
+         "DoSConnectionEnabled" -- Enable the connection DoS mitigation.
+
+         "DoSConnectionMaxConcurrentCount" -- The maximum threshold of
+         concurrent connection from a client IP address.
+
+         "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.
+
+        "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.
+
+        "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.
+
+        "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.
+
+        "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.



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits