diff options
Diffstat (limited to 'spec/dir-list-spec.md')
| -rw-r--r-- | spec/dir-list-spec.md | 70 |
1 files changed, 24 insertions, 46 deletions
diff --git a/spec/dir-list-spec.md b/spec/dir-list-spec.md index a3e6aae..ecb47cb 100644 --- a/spec/dir-list-spec.md +++ b/spec/dir-list-spec.md @@ -1,35 +1,13 @@ +# Tor Directory List Format + ```text - Tor Directory List Format - Tim Wilson-Brown (teor) -Table of Contents - - 1. Scope and Preliminaries - 1.1. Format Overview - 1.2. Acknowledgements - 1.3. Format Versions - 1.4. Future Plans - 2. Format Details - 2.1. Nonterminals - 2.2. List Header - 2.2.1. List Header Format - 2.3. List Generation - 2.3.1. List Generation Format - 2.4. Directory Entry - 2.4.1. Directory Entry Format - 3. Usage Considerations - 3.1. Caching - 3.2. Retrieving Directory Information - 3.3. Fallback Reliability - A.1. Sample Data - A.1.1. Sample Fallback List Header - A.1.2. Sample Fallback List Generation - A.1.3. Sample Fallback Entries + Tim Wilson-Brown (teor) ``` <a id="dir-list-spec.txt-1"></a> -# Scope and Preliminaries +## Scope and Preliminaries This document describes the format of Tor's directory lists, which are compiled and hard-coded into the tor binary. There is currently one @@ -60,7 +38,7 @@ Stem and Relay Search have parsers for this legacy format. <a id="dir-list-spec.txt-1.1"></a> -## Format Overview +### Format Overview A directory list is a C code fragment containing an array of C string constants. Each double-quoted C string constant is a valid torrc @@ -87,7 +65,7 @@ except where noted below. <a id="dir-list-spec.txt-1.2"></a> -## Acknowledgements +### Acknowledgements The original fallback directory script and format was created by weasel. The current script uses code written by gsathya & karsten. @@ -101,7 +79,7 @@ This specification was revised after feedback from: <a id="dir-list-spec.txt-1.3"></a> -## Format Versions +### Format Versions The directory list format uses semantic versioning: <https://semver.org> @@ -125,7 +103,7 @@ The directory list format uses semantic versioning: <https://semver.org> <a id="dir-list-spec.txt-1.4"></a> -## Future Plans +### Future Plans Tor also has an auth_dirs.inc file, but it is not yet in this format. Tor uses slightly different formats for authorities and fallback @@ -141,7 +119,7 @@ fallback update script. See #24839 for details. <a id="dir-list-spec.txt-2"></a> -# Format Details +## Format Details Directory lists contain the following sections: @@ -155,7 +133,7 @@ Directory lists contain the following sections: <a id="dir-list-spec.txt-2.1"></a> -## Nonterminals +### Nonterminals The following nonterminals are defined in the Onionoo details document specification: @@ -214,14 +192,14 @@ specification in dir-spec.txt: <a id="dir-list-spec.txt-2.2"></a> -## List Header +### 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 +#### List Header Format "/*" SP+ "type=" Keyword SP+ "*/" SP\* NL @@ -296,7 +274,7 @@ C-style comments. <a id="dir-list-spec.txt-2.3"></a> -## List Generation +### List Generation The list generation information consists of human-readable prose describing the content and origin of this directory list. It is contained @@ -311,7 +289,7 @@ 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 +#### List Generation Format In general, parsers MUST NOT rely on the format of this section. @@ -328,7 +306,7 @@ section, other than the terminating section separator. <a id="dir-list-spec.txt-2.4"></a> -## Directory Entry +### Directory Entry A directory entry consists of a C string constant, and one or more C-style comments. The C string constant is a valid argument to the @@ -342,7 +320,7 @@ to their weights.) <a id="dir-list-spec.txt-2.4.1"></a> -### Directory Entry Format +#### Directory Entry Format ```text If a directory entry does not conform to this format, the entry SHOULD @@ -459,14 +437,14 @@ to their weights.) <a id="dir-list-spec.txt-3"></a> -# Usage Considerations +## 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 +### Caching The fallback list typically changes once every 6-12 months. The data in the list represents the state of the fallback directory entries when the @@ -492,7 +470,7 @@ clone. <a id="dir-list-spec.txt-3.2"></a> -## Retrieving Directory Information +### Retrieving Directory Information Some libraries retrieve directory documents directly from the Tor Directory Authorities. The directory authorities are designed to support @@ -520,7 +498,7 @@ intervals, see dir-spec for details. <a id="dir-list-spec.txt-3.3"></a> -## Fallback Reliability +### Fallback Reliability The fallback list is typically regenerated when the fallback failure rate exceeds 25%. Libraries SHOULD NOT rely on any particular fallback @@ -532,7 +510,7 @@ before trying an authority. <a id="dir-list-spec.txt-A.1"></a> -## Sample Data +### Sample Data A sample version 2.0.0 fallback list is available here: @@ -544,7 +522,7 @@ A sample transitional version 2.0.0 fallback list is available here: <a id="dir-list-spec.txt-A.1.1"></a> -### Sample Fallback List Header +#### Sample Fallback List Header /*type=fallback */ /* version=2.0.0 */ @@ -552,7 +530,7 @@ A sample transitional version 2.0.0 fallback list is available here: <a id="dir-list-spec.txt-A.1.2"></a> -### Sample Fallback List Generation +#### Sample Fallback List Generation /*Whitelist & blacklist excluded 1326 of 1513 candidates. */ /* Checked IPv4 DirPorts served a consensus within 15.0s. */ @@ -573,7 +551,7 @@ 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 +#### Sample Fallback Entries "176.10.104.240:80 orport=443 id=0111BA9B604669E636FFD5B503F382A4B7AD6E80" /*nickname=foo */ |