commit 2b0093c2c972853e5c2c6bc9e41dc83a4a2e7793 Author: David Goulet dgoulet@torproject.org Date: Mon Nov 1 14:44:43 2021 -0400

dir-spec: Merge prop328 into main specifications

Signed-off-by: David Goulet dgoulet@torproject.org --- dir-spec.txt | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+)

diff --git a/dir-spec.txt b/dir-spec.txt index 543e341..5076366 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -955,6 +955,75 @@ Table of Contents

[Before Tor 0.4.5.1-alpha, this field was optional.]

+ "overload-general" SP version SP YYYY-MM-DD HH:MM:SS NL + + [At most once.] + + Indicate that the relay is overloaded due to one or many conditions + listed in proposal 328 section 1.1. + + The timestamp is always rounded to the hour indicating when was the last + time the relay detected an overloaded state. + + The 'version' field is a versioning field and is set to '1'. See prop328 + for what consists of an overload state. + + This field remains in place for 72 hours since last triggered. If the + limits are reached again in this period, the timestamp is updated, and + this 72 hour period restarts. + + This indicator is not persistent on disk meaning that if the relay + restarts, the overload state is reset and disappear from the descriptor. + + [Introduced in version 0.4.6.1-alpha] + + "overload-ratelimits" SP version SP YYYY-MM-DD SP HH:MM:SS + SP rate-limit SP burst-limit + SP read-overload-count SP write-overload-count NL + + [At most once.] + + Indiate that the relay read or write rate limits were reached which is + a specific overload signal. + + The 'version' field is a versioning field and is set to '1'. + + The '{rate|burst}-limit' are respectively the torrc options + 'BandwidthBurst' and 'BandwidthRate' limits set by the relay. In other + words, they are the bandwidth limitations of the relay. + + The "{read|write}-overload-count" are the counts of how many times the + reported limits of burst/rate were exhausted and thus the maximum + between the read and write count occurrences. To make the counter more + meaningful and to avoid multiple connections saturating the counter when + a relay is overloaded, we only increment it once a minute. + + They span from the past 24 hours starting at the provided timestamp + rounded down to the hour. + + These counters are not persistent on disk meaning that if the relay + restarts, the overload state is reset and disappear from the descriptor. + + [Introduced in version 0.4.6.1-alpha] + + "overload-fd-exhausted" SP version YYYY-MM-DD HH:MM:SS NL + + [At most once.] + + As the overloaded line, the timestamp indicates that the maximum of file + descriptors was reached between this timestamp and the "published" + timestamp of the document. + + This overload field remains in place for 72 hours since last triggered. + If the limits are reached again in this period, the timestamp is + updated, and this 72 hour period restarts. + + The 'version' field is a versioning field and is set to '1'. + + This indicator is not persistent on disk meaning that if the relay + restarts, the overload state is reset and disappear from the descriptor. + + [Introduced in version 0.4.6.1-alpha]

2.1.2. Extra-info document format