commit 12d462f192209ec99221795193322b4d95ccfff3 Author: Andrea Shepard <andrea@persephoneslair.org> Date: Wed Jun 29 21:31:28 2016 +0000 Specify download/ GETINFO queries for controller --- control-spec.txt | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/control-spec.txt b/control-spec.txt index 5c9d3ab..9529d35 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -245,6 +245,10 @@ ISOTime2 = IsoDatePart "T" IsoTimePart ISOTime2Frac = IsoTime2 [ "." 1*DIGIT ] + ; Numbers + LeadingDigit = "1" - "9" + UInt = LeadingDigit *Digit + 3. Commands All commands are case-insensitive, but most keywords are case-sensitive. @@ -892,6 +896,101 @@ The string "up" or "down", indicating whether we currently believe the network is reachable. + "download/" + The keys under download/ are used to query download statuses; they all + return either a sequence of newline-terminated hex encoded digests, or + a serialized download status as follows: + + "next-attempt-at" SP ISOTime CRLF + "n-download-failures" SP UInt CRLF + "n-download-attempts" SP UInt CRLF + "schedule" SP DownloadSchedule CRLF + "want-authority" SP DownloadWantAuthority CRLF + "increment-on" SP DownloadIncrementOn CRLF + "backoff" SP DownloadBackoff CRLF + [ "last-backoff-position" Uint CRLF + "last-delay-used UInt CRLF ] + + where + + DownloadSchedule = + "DL_SCHED_GENERIC" / "DL_SCHED_CONSENSUS" / "DL_SCHED_BRIDGE" + DownloadWantAuthority = + "DL_WANT_ANY_DIRSERVER" / "DL_WANT_AUTHORITY" + DownloadIncrementOn = + "DL_SCHED_INCREMENT_FAILURE" / "DL_SCHED_INCREMENT_ATTEMPT" + DownloadBackoff = + "DL_SCHED_DETERMINISTIC" / "DL_SCHED_RANDOM_EXPONENTIAL" + + The optional last two lines must be present if DownloadBackoff is + "DL_SCHED_RANDOM_EXPONENTIAL" and must be absent if DownloadBackoff + is "DL_SCHED_DETERMINISTIC". + + In detail, the keys supported are: + + "downloads/networkstatus/ns" + The serialized download status for the FLAV_NS consensus for whichever + bootstrap state Tor is currently in. + + "downloads/networkstatus/ns/bootstrap" + The serialized download status for the FLAV_NS consensus at bootstrap + time, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/ns/running" + The serialized download status for the FLAV_NS consensus when running, + regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/microdesc" + The serialized download status for the FLAV_MICRODESC consensus for + whichever bootstrap state Tor is currently in. + + "downloads/networkstatus/microdesc/bootstrap" + The serialized download status for the FLAV_MICRODESC consensus at + bootstrap time, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/microdesc/running" + The serialized download status for the FLAV_MICRODESC consensus when + running, regardless of whether we are currently bootstrapping. + + "downloads/cert/fps" + A newline-separated list of hex-encoded digests for authority certificates + for which we have download status available. + + "downloads/cert/fp/<Fingerprint>" + A serialized download status for the default certificate for the + identity digest <Fingerprint> returned by the downloads/cert/fps key. + + "downloads/cert/fp/<Fingerprint>/sks" + A newline-separated list of hex-encoded signing key digests for the + authority identity digest <Fingerprint> returned by the + downloads/cert/fps key. + + "downloads/cert/fp/<Fingerprint>/<SKDigest>" + A serialized download status for the certificate for the identity + digest <Fingerprint> returned by the downloads/cert/fps key and signing + key digest <SKDigest> returned by the downloads/cert/fp/<Fingerprint>/ + sks key. + + "downloads/desc/descs" + A newline-separated list of hex-encoded router descriptor digests + [note, not identity digests - the Tor process may not have seen them + yet while downloading router descriptors]. If the Tor process is not + using a FLAV_NS consensus, a 551 error is returned. + + "downloads/desc/<Digest>" + A serialized download status for the router descriptor with digest + <Digest> as returned by the downloads/desc/descs key. If the Tor + process is not using a FLAV_NS consensus, a 551 error is returned. + + "downloads/bridge/bridges" + A newline-separated list of hex-encoded bridge identity digests. If + the Tor process is not using bridges, a 551 error is returned. + + "downloads/bridge/<Digest>" + A serialized download status for the bridge descriptor with identity + digest <Digest> as returned by the downloads/bridge/bridges key. If + the Tor process is not using bridges, a 551 error is returned. + Examples: C: GETINFO version desc/name/moria1 S: 250+desc/name/moria=