path: root/param-spec.txt

                           Tor network parameters

This file lists the recognized parameters that can appear on the "params"
line of a directory consensus.

Table of Contents

    1. Network protocol parameters
    2. Performance-tuning parameters
    3. Voting-related parameters
    4. Circuit-build-timeout parameters
    5. Directory-related parameters
    6. Pathbias parameters
    7. Relay behavior
    8. V3 onion service parameters
    9. Denial-of-service parameters
    10. Padding-related parameters
    11. Guard-related parameters
    12. Relay behavior
    X. Obsolete 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, Default: 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
    Removed in 0.4.5.1-alpha; now always on.

    "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
    Removed in 0.4.5.1-alpha; now always off.

    "min_paths_for_circs_pct" -- A percentage threshold that determines
    whether clients believe they have enough directory information to
    build circuits.  This value applies to the total fraction of
    bandwidth-weighted paths that the client could build; see
    path-spec.txt for more information.
    Min: 25, Max: 95, Default: 60
    First-appeared: 0.2.4

    "ExtendByEd25519ID" -- If true, clients should include Ed25519
    identities for relays when generating EXTEND2 cells.
    Min: 0. Max: 1. Default: 0.
    First-appeared: 0.3.0

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

    "allow-network-reentry" -- If true, the Exit relays allow connections that
    are exiting the network to re-enter. If false, any exit connections going
    to a relay ORPort or an authority ORPort and DirPort is denied and the
    stream is terminated.
    Min: 0. Max: 1. Default: 0
    First appeared: 0.4.5.1-alpha.

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), Default: 30000.
    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 independently. 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), Default: (user setting of
        BandwidthRate/BandwidthBurst).
    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: 2147483647 (INT32_MAX). Default: 50000.
    First-appeared: 0.3.3.6-rc.

    "KISTSchedRunInterval" -- How frequently should the "KIST" scheduler
    run in order to decide which data to write to the network? Value in
    units of milliseconds.  If 0, then the KIST scheduler should be
    disabled.
    Min: 0. Max: 100. Default: 10.
    First appeared: 0.3.2

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.

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

    "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

7. Relay behavior

    "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

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

    "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

    "overload_dns_timeout_scale_percent" -- This value is a percentage of how
    many DNS timeout over N seconds we accept before reporting the overload
    general state. It is scaled by a factor of 1000 in order to be able to
    represent decimal point. As an example, a value of 1000 means 1%.
    Min: 0. Max: 100000. Default: 1000.
    First-appeared: 0.4.6.8

    "overload_dns_timeout_period_secs" -- This value is the period in seconds
    of the DNS timeout measurements (the N in the
    "overload_dns_timeout_scale_percent" parameter). For this amount of
    seconds, we will gather DNS statistics and at the end, we'll do an
    assessment on the overload general signal with regards to DNS timeouts.
    Min: 0. Max: 2147483647. Default: 600
    First-appeared: 0.4.6.8

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.

    "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 defense if the introduction point supports it
    (for protover HSIntro=5).
    Min: 0. Max: 1. Default: 0.
    First appeared: 0.4.2.1-alpha.

    "HiddenServiceEnableIntroDoSBurstPerSec" -- Maximum burst to be used
    for token bucket for the introduction point rate-limiting.
    Min: 0. Max: INT32_MAX. Default: 200
    First appeared: 0.4.2.1-alpha.

    "HiddenServiceEnableIntroDoSRatePerSec" -- Refill rate to be used
    for token bucket for the introduction point rate-limiting.
    Min: 0. Max: INT32_MAX. Default: 25
    First appeared: 0.4.2.1-alpha.

9. Denial-of-service parameters

    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 length of
          "DoSCircuitCreationDefenseTimePeriod".


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

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

    (See guard-spec.txt for more information on the vocabulary used here.)

    "UseGuardFraction" -- If true, clients use `GuardFraction`
    information from the consensus in order to decide how to weight
    guards when picking them.
    Min: 0. Max: 1. Default: 0.
    First appeared: 0.2.6

    "guard-lifetime-days" -- Controls guard lifetime. If an unconfirmed
    guard has been sampled more than this many days ago, it should be
    removed from the guard sample.
    Min: 1. Max: 3650. Default: 120.
    First appeared: 0.3.0

    "guard-confirmed-min-lifetime-days" -- Controls confirmed guard
    lifetime: if a guard was confirmed more than this many days ago, it
    should be removed from the guard sample.
    Min: 1. Max: 3650. Default: 60.
    First appeared: 0.3.0

    "guard-internet-likely-down-interval" -- If Tor has been unable to
    build a circuit for this long (in seconds), assume that the internet
    connection is down, and treat guard failures as unproven.
    Min: 1. Max: INT32_MAX. Default: 600.
    First appeared: 0.3.0

    "guard-max-sample-size" -- Largest number of guards that clients
    should try to collect in their sample.
    Min: 1. Max: INT32_MAX. Default: 60.
    First appeared: 0.3.0

    "guard-max-sample-threshold-percent" -- Largest bandwidth-weighted
    fraction of guards that clients should try to collect in their
    sample.
    Min: 1. Max: 100. Default: 20.
    First appeared: 0.3.0

    "guard-meaningful-restriction-percent" -- If the client has
    configured tor to exclude so many guards that the available guard
    bandwidth is less than this percentage of the total, treat the guard
    sample as "restricted", and keep it in a separate sample.
    Min: 1. Max: 100. Default: 20.
    First appeared: 0.3.0

    "guard-extreme-restriction-percent" -- Warn the user if they have
    configured tor to exclude so many guards that the available guard
    bandwidth is less than this percentage of the total.
    Min: 1. Max: 100. Default: 1.
    First appeared: 0.3.0.  MAX was INT32_MAX, which would have no meaningful
    effect.  MAX lowered to 100 in 0.4.7.

    "guard-min-filtered-sample-size" -- If fewer than this number of
    guards is available in the sample after filtering out unusable
    guards, the client should try to add more guards to the sample (if
    allowed).
    Min: 1. Max: INT32_MAX. Default: 20.
    First appeared: 0.3.0

    "guard-n-primary-guards" -- The number of confirmed guards that the
    client should treat as "primary guards".
    Min: 1. Max: INT32_MAX. Default: 3.
    First appeared: 0.3.0

    "guard-n-primary-guards-to-use", "guard-n-primary-dir-guards-to-use"
    -- number of primary guards and primary directory guards that the
    client should be willing to use in parallel.  Other primary guards
    won't get used unless the earlier ones are down.
    "guard-n-primary-guards-to-use":
       Min 1, Max INT32_MAX: Default: 1.
    "guard-n-primary-dir-guards-to-use"
       Min 1, Max INT32_MAX: Default: 3.
    First appeared: 0.3.0

    "guard-nonprimary-guard-connect-timeout" -- When trying to confirm
    nonprimary guards, if a guard doesn't answer for more than this long
    in seconds, treat lower-priority guards as usable.
    Min: 1. Max: INT32_MAX. Default: 15
    First appeared: 0.3.0

    "guard-nonprimary-guard-idle-timeout" -- When trying to confirm
    nonprimary guards, if a guard doesn't answer for more than this long
    in seconds, treat it as down.
    Min: 1. Max: INT32_MAX. Default: 600
    First appeared: 0.3.0

    "guard-remove-unlisted-guards-after-days" -- If a guard has been
    unlisted in the consensus for at least this many days, remove it
    from the sample.
    Min: 1. Max: 3650. Default: 20.
    First appeared: 0.3.0

12. Relay behavior

    "assume-reachable" -- If true, relays should publish descriptors
    even when they cannot make a connection to their IPv4 ORPort.
    Min: 0. Max: 1. Default: 0.
    First appeared: 0.4.5.1-alpha.

    "assume-reachable-ipv6" -- If true, relays should publish
    descriptors even when they cannot make a connection to their IPv6
    ORPort.
    Min: 0. Max: 1. Default: 0.
    First appeared: 0.4.5.1-alpha.

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