diff options
Diffstat (limited to 'spec/dir-list-spec.md')
| -rw-r--r-- | spec/dir-list-spec.md | 44 |
1 files changed, 32 insertions, 12 deletions
diff --git a/spec/dir-list-spec.md b/spec/dir-list-spec.md index e6c1e0c..0dbb750 100644 --- a/spec/dir-list-spec.md +++ b/spec/dir-list-spec.md @@ -28,6 +28,7 @@ Table of Contents ``` <a id="dir-list-spec.txt-1"></a> + # Scope and Preliminaries This document describes the format of Tor's directory lists, which are @@ -58,6 +59,7 @@ Tor 0.2.8.1-alpha through Tor 0.3.1.9. We call this format version 1. Stem and Relay Search have parsers for this legacy format. <a id="dir-list-spec.txt-1.1"></a> + ## Format Overview A directory list is a C code fragment containing an array of C string @@ -84,6 +86,7 @@ The order of directory entries and data fields is not significant, except where noted below. <a id="dir-list-spec.txt-1.2"></a> + ## Acknowledgements The original fallback directory script and format was created by @@ -97,9 +100,10 @@ This specification was revised after feedback from: ``` <a id="dir-list-spec.txt-1.3"></a> + ## Format Versions -The directory list format uses semantic versioning: https://semver.org +The directory list format uses semantic versioning: <https://semver.org> ```text In particular: @@ -120,6 +124,7 @@ The directory list format uses semantic versioning: https://semver.org ``` <a id="dir-list-spec.txt-1.4"></a> + ## Future Plans Tor also has an auth_dirs.inc file, but it is not yet in this format. @@ -135,6 +140,7 @@ We need to write a short proposal, and make some changes to tor and the fallback update script. See #24839 for details. <a id="dir-list-spec.txt-2"></a> + # Format Details Directory lists contain the following sections: @@ -148,6 +154,7 @@ Directory lists contain the following sections: ``` <a id="dir-list-spec.txt-2.1"></a> + ## Nonterminals The following nonterminals are defined in the Onionoo details document @@ -206,12 +213,14 @@ specification in dir-spec.txt: ``` <a id="dir-list-spec.txt-2.2"></a> + ## List Header The list header consists of a number of key-value pairs, embedded in C-style comments. <a id="dir-list-spec.txt-2.2.1"></a> + ### List Header Format "/*" SP+ "type=" Keyword SP+ "*/" SP* NL @@ -286,6 +295,7 @@ C-style comments. ``` <a id="dir-list-spec.txt-2.3"></a> + ## List Generation The list generation information consists of human-readable prose @@ -300,6 +310,7 @@ Future releases may arbitrarily change the content of this section. Parsers MUST NOT rely on a version increment when the format changes. <a id="dir-list-spec.txt-2.3.1"></a> + ### List Generation Format In general, parsers MUST NOT rely on the format of this section. @@ -316,6 +327,7 @@ There MUST NOT be any section separators in the list generation section, other than the terminating section separator. <a id="dir-list-spec.txt-2.4"></a> + ## Directory Entry A directory entry consists of a C string constant, and one or more @@ -329,6 +341,7 @@ these lists after parsing them, and applies the DirAuthorityFallbackRate to their weights.) <a id="dir-list-spec.txt-2.4.1"></a> + ### Directory Entry Format ```text @@ -445,12 +458,14 @@ to their weights.) ``` <a id="dir-list-spec.txt-3"></a> + # Usage Considerations This section contains recommended library behaviours. It does not affect the format of directory lists. <a id="dir-list-spec.txt-3.1"></a> + ## Caching The fallback list typically changes once every 6-12 months. The data in @@ -463,19 +478,20 @@ lists by default every time they are deployed or executed. The latest fallback list can be retrieved from: -https://gitweb.torproject.org/tor.git/plain/src/or/fallback_dirs.inc +<https://gitweb.torproject.org/tor.git/plain/src/or/fallback_dirs.inc> Libraries MUST NOT rely on the availability of the server that hosts these lists. The list can also be retrieved using: -git clone https://git.torproject.org/tor.git +git clone <https://git.torproject.org/tor.git> If you just want the latest list, you may wish to perform a shallow clone. <a id="dir-list-spec.txt-3.2"></a> + ## Retrieving Directory Information Some libraries retrieve directory documents directly from the Tor @@ -503,6 +519,7 @@ schedule. Fallbacks update their own directory information at random intervals, see dir-spec for details. <a id="dir-list-spec.txt-3.3"></a> + ## Fallback Reliability The fallback list is typically regenerated when the fallback failure @@ -514,30 +531,33 @@ few fallback queries fail. For example, Tor clients try 3-4 fallbacks before trying an authority. <a id="dir-list-spec.txt-A.1"></a> + ## Sample Data A sample version 2.0.0 fallback list is available here: -https://trac.torproject.org/projects/tor/raw-attachment/ticket/22759/fallback_dirs_new_format_version.4.inc +<https://trac.torproject.org/projects/tor/raw-attachment/ticket/22759/fallback_dirs_new_format_version.4.inc> A sample transitional version 2.0.0 fallback list is available here: -https://raw.githubusercontent.com/teor2345/tor/fallback-format-2-v4/src/or/fallback_dirs.inc +<https://raw.githubusercontent.com/teor2345/tor/fallback-format-2-v4/src/or/fallback_dirs.inc> <a id="dir-list-spec.txt-A.1.1"></a> + ### Sample Fallback List Header -/* type=fallback */ +/*type=fallback */ /* version=2.0.0 */ -/* ===== */ +/* =====*/ <a id="dir-list-spec.txt-A.1.2"></a> + ### Sample Fallback List Generation -/* Whitelist & blacklist excluded 1326 of 1513 candidates. */ +/*Whitelist & blacklist excluded 1326 of 1513 candidates. */ /* Checked IPv4 DirPorts served a consensus within 15.0s. */ /* -Final Count: 151 (Eligible 187, Target 392 (1963 * 0.20), Max 200) +Final Count: 151 (Eligible 187, Target 392 (1963* 0.20), Max 200) Excluded: 36 (Same Operator 27, Failed/Skipped Download 9, Excess 0) Bandwidth Range: 1.3 - 40.0 MByte/s */ @@ -552,10 +572,11 @@ URL: https:onionoo.torproject.orguptime?first_seen_days=30-&flag=V2Dir&type=rela /* ===== */ <a id="dir-list-spec.txt-A.1.3"></a> + ### Sample Fallback Entries "176.10.104.240:80 orport=443 id=0111BA9B604669E636FFD5B503F382A4B7AD6E80" -/* nickname=foo */ +/*nickname=foo */ /* extrainfo=1 */ /* ===== */ , @@ -563,6 +584,5 @@ URL: https:onionoo.torproject.orguptime?first_seen_days=30-&flag=V2Dir&type=rela " ipv6=[2a01:4f8:162:51e2::2]:9001" /* nickname= */ /* extrainfo=0 */ -/* ===== */ +/* =====*/ , - |