[tor-commits] [torspec/master] Standardizing on the name 'server descriptor'
nickm at torproject.org
nickm at torproject.org
Wed Feb 25 14:14:28 UTC 2015
commit ed1a0dbfbb9b4a9075a96e256988360bb157775f
Author: Damian Johnson <atagar at torproject.org>
Date: Tue Feb 24 20:12:39 2015 -0800
Standardizing on the name 'server descriptor'
We use a few names for the main self-published descriptor documents...
https://trac.torproject.org/projects/tor/ticket/14987
Standardizing on the name 'server descriptor'. This change was made with a
few quick runs of sed...
% find ./* -type f -exec sed -i 's/router descriptor/server descriptor/' "{}" +;
% find ./* -type f -exec sed -i 's/Router descriptor/Server descriptor/' "{}" +;
% find ./* -type f -exec sed -i 's/Router Descriptor/Server Descriptor/' "{}" +;
... then reverting the attic changes, and scanning the rest to be sure it
doesn't include any functional impact.
---
control-spec.txt | 6 ++---
dir-spec.txt | 78 +++++++++++++++++++++++++++---------------------------
path-spec.txt | 4 +--
3 files changed, 44 insertions(+), 44 deletions(-)
diff --git a/control-spec.txt b/control-spec.txt
index 871c353..b527a40 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -1703,7 +1703,7 @@
4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
Tor generates this event when it's an directory authority, and
- somebody has just uploaded a router descriptor.
+ somebody has just uploaded a server descriptor.
Syntax:
"650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF
@@ -1711,7 +1711,7 @@
Action = "ACCEPTED" / "DROPPED" / "REJECTED"
Message = Text
- The Descriptor field is the text of the router descriptor; the Action
+ The Descriptor field is the text of the server descriptor; the Action
field is "ACCEPTED" if we're accepting the descriptor as the new
best valid descriptor for its router, "REJECTED" if we aren't taking
the descriptor and we're complaining to the uploading relay about
@@ -1946,7 +1946,7 @@
to tell them so.}
NOT_ENOUGH_DIR_INFO
- We discarded expired statuses and router descriptors to fall
+ We discarded expired statuses and server descriptors to fall
below the desired threshold of directory information. We won't
try to build any circuits until ENOUGH_DIR_INFO occurs again.
diff --git a/dir-spec.txt b/dir-spec.txt
index f74b16d..85492e9 100644
--- a/dir-spec.txt
+++ b/dir-spec.txt
@@ -33,7 +33,7 @@
Early versions of Tor (0.0.2) introduced "Directory authorities": servers
that served signed "directory" documents containing a list of signed
- "router descriptors", along with short summary of the status of each
+ "server descriptors", along with short summary of the status of each
router. Thus, clients could get up-to-date information on the state of
the network automatically, and be certain that the list they were getting
was attested by a trusted directory authority.
@@ -56,7 +56,7 @@
documents in order to address two major problems:
* Directories had grown quite large (over 1MB), and most directory
- downloads consisted mainly of router descriptors that clients
+ downloads consisted mainly of server descriptors that clients
already had.
* Every directory authority was a trust bottleneck: if a single
@@ -75,10 +75,10 @@
statements about routers iff they were attested to by more than half of
the authorities.
- Instead of downloading all router descriptors at once, clients
+ Instead of downloading all server descriptors at once, clients
downloaded only the descriptors that they did not have. Descriptors
were indexed by their digests, in order to prevent malicious caches
- from giving different versions of a router descriptor to different
+ from giving different versions of a server descriptor to different
clients.
Routers began working harder to upload new descriptors only when their
@@ -90,7 +90,7 @@
Version 3 of the Tor directory protocol tries to solve the following
issues:
- * A great deal of bandwidth used to transmit router descriptors was
+ * A great deal of bandwidth used to transmit server descriptors was
used by two fields that are not actually used by Tor routers
(namely read-history and write-history). We save about 60% by
moving them into a separate document that most clients do not
@@ -153,7 +153,7 @@
directory authorities describing their keys, capabilities, and other
information. Routers may also upload signed "extra info documents"
containing information that is not required for the Tor protocol.
- Directory authorities serve router descriptors indexed by router
+ Directory authorities serve server descriptors indexed by router
identity, or by hash of the descriptor.
Routers may act as directory caches to reduce load on the directory
@@ -170,7 +170,7 @@
Clients, directory caches, and directory authorities all use consensus
documents to find out when their list of routers is out-of-date.
(Directory authorities also use vote statuses.) If it is, they download
- any missing router descriptors. Clients download missing descriptors
+ any missing server descriptors. Clients download missing descriptors
from caches; caches and authorities download from authorities.
Descriptors are downloaded by the hash of the descriptor, not by the
relay's identity key: this prevents directory servers from attacking
@@ -193,7 +193,7 @@
1.2. Document meta-format
- Router descriptors, directories, and running-routers documents all obey the
+ Server descriptors, directories, and running-routers documents all obey the
following lightweight extensible information format.
The highest level object is a Document, which consists of one or more
@@ -319,9 +319,9 @@
2. Router operation and formats
-2.1. Uploading router descriptors and extra-info documents
+2.1. Uploading server descriptors and extra-info documents
- ORs SHOULD generate a new router descriptor and a new extra-info
+ ORs SHOULD generate a new server descriptor and a new extra-info
document whenever any of the following events have occurred:
- A period of time (18 hrs by default) has passed since the last
@@ -338,7 +338,7 @@
[XXX this list is incomplete; see router_differences_are_cosmetic()
in routerlist.c for others]
- ORs SHOULD NOT publish a new router descriptor or extra-info document
+ ORs SHOULD NOT publish a new server descriptor or extra-info document
if none of the above events have occurred and not much time has passed
(12 hours by default).
@@ -347,13 +347,13 @@
http://<hostname:port>/tor/
- Router descriptors may not exceed 20,000 bytes in length; extra-info
+ Server descriptors may not exceed 20,000 bytes in length; extra-info
documents may not exceed 50,000 bytes in length. If they do, the
authorities SHOULD reject them.
-2.1.1. Router descriptor format
+2.1.1. Server descriptor format
- Router descriptors consist of the following items. For backward
+ Server descriptors consist of the following items. For backward
compatibility, there should be an extra NL at the end of each router
descriptor.
@@ -365,7 +365,7 @@
[At start, exactly once.]
- Indicates the beginning of a router descriptor. "nickname" must be a
+ Indicates the beginning of a server descriptor. "nickname" must be a
valid router nickname as specified in section 2.1.3. "address" must
be an IPv4
address in dotted-quad format. The last three numbers indicate the
@@ -490,9 +490,9 @@
[At end, exactly once]
The "SIGNATURE" object contains a signature of the PKCS1-padded
- hash of the entire router descriptor, taken from the beginning of the
+ hash of the entire server descriptor, taken from the beginning of the
"router" line, through the newline after the "router-signature" line.
- The router descriptor is invalid unless the signature is performed
+ The server descriptor is invalid unless the signature is performed
with the router's identity key.
"contact" info NL
@@ -632,7 +632,7 @@
The time, in UTC, when this document (and its corresponding router
descriptor if any) was generated. It MUST match the published time
- in the corresponding router descriptor.
+ in the corresponding server descriptor.
"read-history" YYYY-MM-DD HH:MM:SS (NSEC s) NUM,NUM,NUM,NUM,NUM... NL
[At most once.]
@@ -975,17 +975,17 @@
2.1.2.1. Moving history fields to extra-info documents
Tools that want to use the read-history and write-history values SHOULD
- download extra-info documents as well as router descriptors. Such
+ download extra-info documents as well as server descriptors. Such
tools SHOULD accept history values from both sources; if they appear in
both documents, the values in the extra-info documents are authoritative.
- New versions of Tor no longer generate router descriptors
+ New versions of Tor no longer generate server descriptors
containing read-history or write-history. Tools should continue to
- accept read-history and write-history values in router descriptors
+ accept read-history and write-history values in server descriptors
produced by older versions of Tor until all Tor versions earlier
than 0.2.0.x are obsolete.
-2.1.3. Nonterminals in router descriptors
+2.1.3. Nonterminals in server descriptors
nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]),
case-insensitive.
@@ -1098,7 +1098,7 @@
Authorities MUST generate a new signing key and corresponding
certificate before the key expires.
-3.2. Accepting router descriptor and extra-info document uploads
+3.2. Accepting server descriptor and extra-info document uploads
When a router posts a signed descriptor to a directory authority, the
authority first checks whether it is well-formed and correctly
@@ -1120,7 +1120,7 @@
- Enough time has passed between the descriptors' publication times.
(Currently, 12 hours.)
- Differences between router descriptors are "non-cosmetic" if they would be
+ Differences between server descriptors are "non-cosmetic" if they would be
sufficient to force an upload as described in section 2.1 above.
Note that the "cosmetic difference" test only applies to uploaded
@@ -1135,7 +1135,7 @@
3.3. Computing microdescriptors
- Microdescriptors are a stripped-down version of router descriptors
+ Microdescriptors are a stripped-down version of server descriptors
generated by the directory authorities which may additionally contain
authority-generated information. Microdescriptors contain only the
most relevant parts that clients care about. Microdescriptors are
@@ -1144,7 +1144,7 @@
use to decide which servers to fetch information about, or which
servers to fetch information from.
- Microdescriptors are a straight transform from the router descriptor
+ Microdescriptors are a straight transform from the server descriptor
and the consensus method. Microdescriptors have no header or footer.
Microdescriptors are identified by the hash of its concatenated
elements without a signature by the router. Microdescriptors do not
@@ -1152,9 +1152,9 @@
by the consensus method.
Starting with consensus method 8, microdescriptors contain the
- following elements taken from or based on the router descriptor. Order
+ following elements taken from or based on the server descriptor. Order
matters here, because different directory authorities must be able to
- transform a given router descriptor and consensus method into the exact
+ transform a given server descriptor and consensus method into the exact
same microdescriptor.
"onion-key" NL a public key in PEM format
@@ -1955,7 +1955,7 @@
The bandwidth in a "w" line should be taken as the best estimate
of the router's actual capacity that the authority has. For now,
this should be the lesser of the observed bandwidth and bandwidth
- rate limit from the router descriptor. It is given in kilobytes
+ rate limit from the server descriptor. It is given in kilobytes
per second, and capped at some arbitrary value (currently 10 MB/s).
The Measured= keyword on a "w" line vote is currently computed
@@ -1976,7 +1976,7 @@
XXX when to download certificates.
-3.6. Downloading router descriptors from other directory authorities
+3.6. Downloading server descriptors from other directory authorities
Periodically (currently, every 10 seconds), directory authorities check
whether there are any specific descriptors that they do not have and that
@@ -2011,7 +2011,7 @@
3.7. Downloading extra-info documents from other directory authorities
Periodically, an authority checks whether it is missing any extra-info
- documents: in other words, if it has any router descriptors with an
+ documents: in other words, if it has any server descriptors with an
extra-info-digest field that does not match any of the extra-info
documents currently held. If so, it downloads whatever extra-info
documents are missing. We follow the same splitting and back-off rules
@@ -2608,7 +2608,7 @@
length. Caches serve all consensus flavors from the same locations as
the directory authorities.
-4.2. Downloading router descriptors from directory authorities
+4.2. Downloading server descriptors from directory authorities
Periodically (currently, every 10 seconds), directory caches check
whether there are any specific descriptors that they do not have and that
@@ -2658,7 +2658,7 @@
section.
Periodically, the Tor instance checks whether it is missing any extra-info
- documents: in other words, if it has any router descriptors with an
+ documents: in other words, if it has any server descriptors with an
extra-info-digest field that does not match any of the extra-info
documents currently held. If so, it downloads whatever extra-info
documents are missing. Caches download from authorities. We follow the
@@ -2732,7 +2732,7 @@
the same update strategy as for the normal consensus. They should not
download more than one consensus flavor.
-5.2. Downloading router descriptors or microdescriptors
+5.2. Downloading server descriptors or microdescriptors
Clients try to have the best descriptor for each router. A descriptor is
"best" if:
@@ -2754,7 +2754,7 @@
client tried to download descriptors, it launches requests for all
downloadable descriptors.
- When downloading multiple router descriptors, the client chooses multiple
+ When downloading multiple server descriptors, the client chooses multiple
mirrors so that:
- At least 3 different mirrors are used, except when this would result
in more than one request for under 4 descriptors.
@@ -2783,7 +2783,7 @@
Clients which chose to download the microdescriptor consensus instead
of the general consensus must download the referenced microdescriptors
- instead of router descriptors. Clients fetch and cache
+ instead of server descriptors. Clients fetch and cache
microdescriptors preemptively from dir mirrors when starting up, like
they currently fetch descriptors. After bootstrapping, clients only
need to fetch the microdescriptors that have changed.
@@ -2811,7 +2811,7 @@
Note that generally, clients don't need extra-info documents.
Periodically, the Tor instance checks whether it is missing any extra-info
- documents: in other words, if it has any router descriptors with an
+ documents: in other words, if it has any server descriptors with an
extra-info-digest field that does not match any of the extra-info
documents currently held. If so, it downloads whatever extra-info
documents are missing. Clients try to download from caches.
@@ -2932,8 +2932,8 @@
them.
Servers SHOULD disable caching of multiple network statuses or multiple
- router descriptors. Servers MAY enable caching of single descriptors,
- single network statuses, the list of all router descriptors, a v1
+ server descriptors. Servers MAY enable caching of single descriptors,
+ single network statuses, the list of all server descriptors, a v1
directory, or a v1 running routers document. XXX mention times.
6.2. HTTP status codes
diff --git a/path-spec.txt b/path-spec.txt
index 64886dc..896195a 100644
--- a/path-spec.txt
+++ b/path-spec.txt
@@ -602,9 +602,9 @@ of their choices.
Tor does not add a guard persistently to the list until the first time we
have connected to it successfully.
-6. Router descriptor purposes
+6. Server descriptor purposes
- There are currently three "purposes" supported for router descriptors:
+ There are currently three "purposes" supported for server descriptors:
general, controller, and bridge. Most descriptors are of type general
-- these are the ones listed in the consensus, and the ones fetched
and used in normal cases.
More information about the tor-commits
mailing list