commit 138ae7f3180f961314df4630b67162cc12369b91 Author: teor teor2345@gmail.com Date: Tue Oct 17 22:17:27 2017 -0400

Document the current "or-address" and "a" line implementation

Preparation for #20916. --- dir-spec.txt | 56 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 15 deletions(-)

diff --git a/dir-spec.txt b/dir-spec.txt index 45726cd..a0133d5 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -757,8 +757,8 @@ duplicate the address:port pair from its "router" line.

The ordering of or-address lines and their PORT entries matter because - Tor MAY accept a limited number of addresses or ports. As of Tor 0.2.3.x - only the first address and the first port are used. + Tor MAY accept a limited number of address/port pairs. As of + Tor 0.2.3.x only the first address/port pair is advertised and used.

"tunnelled-dir-server" NL

@@ -1463,9 +1463,18 @@

"a" SP address ":" port NL

- [Any number] + [At most once] + + The first advertised IPv6 address for the OR. + + Present only if the OR advertises at least one IPv6 address. + Any other IPv4 or IPv6 addresses are ignored. + + Address and port are as for "or-address" as specified in + section 2.1.1.

- The "or-address" element as specified in section 2.1.1. + (Only included when generating microdescriptors for + consensus-method 14 or later.)

"family" names NL

@@ -2126,9 +2135,13 @@

"a" SP address ":" port NL

- [Any number.] + [At most once]

- Present only if the OR has at least one IPv6 address. + The first advertised IPv6 address for the OR, if it is reachable. + + Present only if the OR advertises at least one IPv6 address, and the + authority believes that the first advertised address is reachable. + Any other IPv4 or IPv6 addresses are ignored.

Address and port are as for "or-address" as specified in section 2.1.1. @@ -2156,10 +2169,11 @@ "NoEdConsensus" if any Ed25519 key in the router's descriptor or microdesriptor does not reflect authority consensus. "Stable" if the router is suitable for long-lived circuits. - "Running" if the router is currently usable. Relays without this - flag are omitted from the consensus, and current clients - (since 0.2.9.4-alpha) assume that every listed relay has - this flag. + "Running" if the router is currently usable over the ORPorts that + an authority considers mandatory. Relays without this flag are + omitted from the consensus, and current clients + (since 0.2.9.4-alpha) assume that every listed relay has this + flag. "Valid" if the router has been 'validated'. Clients before 0.2.9.4-alpha would not use routers without this flag by default. Currently, relays without this flag are omitted @@ -2364,7 +2378,12 @@ canonically linked to its public key.

"Running" -- A router is 'Running' if the authority managed to connect to - it successfully within the last 45 minutes. + it successfully within the last 45 minutes on the ORPorts it considers + mandatory. Since 0.2.4.x, the mandatory ORPorts are: + * the IPv4 ORPort in the "r" line, and + * the IPv6 ORPort considered for the "a" line, if: + * the router advertises at least one IPv6 ORPort, and + * AuthDirHasIPv6Connectivity 1 is set on the authority

"Stable" -- A router is 'Stable' if it is active, and either its Weighted MTBF is at least the median for known active routers or its Weighted MTBF @@ -2637,9 +2656,9 @@ * If consensus method 13 or later is used, microdesc consensuses omit any router for which no microdesc was agreed upon.

- * If consensus method 14 or later is used, votes and - consensuses may include "a" lines listing additional OR - ports. + * If consensus method 14 or later is used, the ns consensus and + microdescriptors may include an "a" line for each router, listing + an IPv6 OR port.

* If consensus method 15 or later is used, microdescriptors include "p6" lines including IPv6 exit policies. @@ -2757,7 +2776,7 @@ "11" -- Don't consider BadExits when calculating bandwidth weights "12" -- Params are only included if enough auths voted for them "13" -- Omit router entries with missing microdescriptors. - "14" -- Adds support for "a" lines. + "14" -- Adds support for "a" lines in ns consensues and microdescriptors. "15" -- Adds support for "p6" lines. "16" -- Adds ntor keys to microdescriptors "17" -- Adds "Unmeasured=1" flags to "w" lines @@ -3056,6 +3075,13 @@

Similar to "r" lines in section 3.4.1, but without the digest element.

+ "a" SP address ":" port NL + + [Zero times.] + + IPv6 ORPorts are contained in microdescriptors and therefore omitted + in the microdescriptor consensus. + "p" ... NL

[Zero times.]