param-spec: reindent

                           Tor network parameters

This file lists the recognized parameters that can appear on the "params"

line of a directory consensus.

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.

    "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

        "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.

    "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

        "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.

    "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

        "usecreatefast" -- Used to control whether clients use the

        CREATE_FAST handshake on the first hop of their circuits.

    "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.

    "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

    "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.)

    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.)

    "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

    Min: 0. Max: 255. Default 0. First

    appeared: 0.4.1.1-alpha.

    "KISTSchedRunInterval" -- DOCDOC

    "UseGuardFraction" -- DOCDOC

    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.

    "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", "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).

    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.

    "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.

    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

7. Relay behavior

        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

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].

        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_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.

    "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.

    "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

    "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

    "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.

    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.

        2: Refuse circuit creation for the length of

          "DoSCircuitCreationDefenseTimePeriod".

    "DoSCircuitCreationDefenseTimePeriod" -- The base time period that

    the DoS defense is activated for.

    "DoSConnectionDefenseType" -- Defense type applied to a detected

    client address for the connection mitigation. Possible values are:

        1: No defense.

        2: Immediately close new connections.

    "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.

    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.

    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.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,

    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