[or-cvs] r8745: hammer farther on the status events. still a lot of question (tor/trunk/doc)
arma at seul.org
arma at seul.org
Wed Oct 18 04:34:02 UTC 2006
Author: arma
Date: 2006-10-18 00:33:58 -0400 (Wed, 18 Oct 2006)
New Revision: 8745
Modified:
tor/trunk/doc/control-spec.txt
tor/trunk/doc/dir-spec.txt
Log:
hammer farther on the status events. still a lot of questions.
Modified: tor/trunk/doc/control-spec.txt
===================================================================
--- tor/trunk/doc/control-spec.txt 2006-10-18 03:47:31 UTC (rev 8744)
+++ tor/trunk/doc/control-spec.txt 2006-10-18 04:33:58 UTC (rev 8745)
@@ -194,7 +194,7 @@
EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
"INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /
"AUTHDIR_NEWDESCS" / "DESCCHANGED" / "STATUS_GENERAL" /
- "STATUS_CLIENT" / "STATUS_SERVER"
+ "STATUS_CLIENT" / "STATUS_SERVER" / "GUARDS"
Any events *not* listed in the SETEVENTS line are turned off; thus, sending
SETEVENTS with an empty body turns off all event reporting.
@@ -458,6 +458,21 @@
status events are available as getinfo's currently. Let us know if
you want more exposed.)
+ "status/client"
+ "status/server"
+ These two special cases of internal Tor values return a (possibly
+ empty) list of status events from Section 4.1.10 that Tor believes
+ are still accurate. Controllers can use them to get a summary of
+ any current problems with Tor's operation.
+ [The answers should include notice events, not just warns and
+ errs, for example so Tor can learn whether any circuits have been
+ established yet.]
+ [Does this mean that Tor must keep state on its side of all the
+ statuses it's sent, and recognize when they're cancelled out,
+ and so on? It's a shame that Tor needs to do this and also Vidalia
+ needs to do this.]
+
+
Examples:
C: GETINFO version desc/name/moria1
S: 250+desc/name/moria=
@@ -873,43 +888,24 @@
[Don't rely on any of these until we work out more of the details. -RD]
Syntax:
- "650" SP Type SP Action SP Arguments
- Type = "STATUS_NOTICE" / "STATUS_WARN"
+ "650" SP Type SP Severity SP Action SP Arguments
+ Type = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
+ Severity = "NOTICE" / "WARN" / "ERR"
+
Action is a string, and Arguments is a series of key=value
pairs on the same line.
- Actions for STATUS_NOTICE events can be as follows:
+ The reserved keyword "message" can optionally be used to provide a
+ string describing the nature of the action. Message strings MUST
+ NOT include items that a controller might be tempted to parse,
+ such as numbers.
-client notices:
- CIRCUIT_ESTABLISHED
- Tor is able to establish circuits for client use. This event will
- only be sent if we just built a circuit that changed our mind --
- that is, prior to this event we didn't know whether we could
- establish circuits.
+ Actions for STATUS_GENERAL severity NOTICE events can be as follows:
- DIR_ALL_UNREACHABLE
- Tor believes that none of the known directory servers are
- reachable -- this is most likely because the local network is
- down or otherwise not working, and might help to explain for the
- user why Tor appears to be broken.
+ [none yet]
- GUARD_NODES_CHANGED
+ Actions for STATUS_GENERAL severity WARN events can be as follows:
-server notices:
- EXTERNAL_ADDRESS
- "address=IP"
- "method=guessed/resolved/..."
-
- // hibernating
-
- CHECKING_REACHABILITY
- "oraddress=IP:port"
- "diraddress=IP:port"
- "timeout=NUM"
-
- Actions for STATUS_WARN events can be as follows:
-
-general warns:
DANGEROUS_VERSION
"current=version"
"recommended=version,version,..."
@@ -923,6 +919,8 @@
also happens when the system is swapping so heavily that Tor is
starving. The "time" argument includes the number of seconds Tor
thinks it was unconscious for.
+ [This status event can generally be ignored by the controller,
+ since we don't really know what the user should do anyway. Hm.]
TOO_MANY_CONNECTIONS
"limit=NUM"
@@ -938,15 +936,41 @@
the controller can explain this to the user and encourage her to
file a bug report?
+ [The following two are sent as WARNs if CIRCUIT_ESTABLISHED and
+ not DIR_ALL_UNREACHABLE, else as ERRs:]
+
+ BAD_DIR_RESPONSE
// unexpected dir response. behind a hotel/airport firewall?
- // bad http or https proxy?
-
- // clock is skewed
+ CLOCK_SKEWED
// (either from talking to a dir authority, or from perusing a
// network-status timestamp)
-client warns:
+ Actions for STATUS_GENERAL severity ERR events can be as follows:
+
+ BAD_PROXY
+ // bad http or https proxy?
+
+ DIR_ALL_UNREACHABLE
+ Tor believes that none of the known directory servers are
+ reachable -- this is most likely because the local network is
+ down or otherwise not working, and might help to explain for the
+ user why Tor appears to be broken.
+
+ Actions for STATUS_CLIENT severity NOTICE events can be as follows:
+
+ CIRCUIT_ESTABLISHED
+ Tor is able to establish circuits for client use. This event will
+ only be sent if we just built a circuit that changed our mind --
+ that is, prior to this event we didn't know whether we could
+ establish circuits.
+
+ ENOUGH_DIR_INFO
+ Tor now knows enough network-status documents and enough server
+ descriptors that it's going to start trying to build circuits now.
+
+ Actions for STATUS_CLIENT severity WARN events can be as follows:
+
DANGEROUS_SOCKS
"protocol=socks4/socks4a/socks5"
"address=IP:port"
@@ -961,7 +985,29 @@
// a nickname we asked for is unavailable. no need for this
// quite yet, since no end-user controllers let you configure that.
-server warns:
+ Actions for STATUS_CLIENT severity ERR events can be as follows:
+
+ [none yet]
+
+ Actions for STATUS_SERVER severity NOTICE events can be as follows:
+
+ EXTERNAL_ADDRESS
+ "address=IP"
+ "method=guessed/resolved/..."
+
+ // hibernating
+
+ CHECKING_REACHABILITY
+ "oraddress=IP:port"
+ "diraddress=IP:port"
+ "timeout=NUM"
+
+ GOOD_SERVER_DESCRIPTOR
+ We successfully uploaded our server descriptor to each of the
+ directory authorities, with no complaints.
+
+ Actions for STATUS_SERVER severity WARN events can be as follows:
+
// something about failing to parse our address?
// from resolve_my_address() in config.c
@@ -969,18 +1015,29 @@
// too many onions queued. threading problem or slow cpu?
- REACHABILITY_FAILED
- "oraddress=IP:port"
- "diraddress=IP:port"
+ // eventdns statements. like, hijacked dns.
+ BAD_SERVER_DESCRIPTOR
+ "dirauth=nickname"
// dir authorities didn't like my descriptor
- // eventdns statements. like, hijacked dns.
+ Actions for STATUS_SERVER severity ERR events can be as follows:
+ REACHABILITY_FAILED
+ "oraddress=IP:port"
+ "diraddress=IP:port"
Controllers must tolerate hearing about actions that they don't
recognize.
+4.1.11. Our set of guard nodes has changed
+
+ Syntax:
+ "650" SP "GUARDS" SP Type SP ...
+ Type = "ENTRY"
+ ...
+ [needs to be fleshed out; not implemented yet]
+
5. Implementation notes
5.1. Authentication
Modified: tor/trunk/doc/dir-spec.txt
===================================================================
--- tor/trunk/doc/dir-spec.txt 2006-10-18 03:47:31 UTC (rev 8744)
+++ tor/trunk/doc/dir-spec.txt 2006-10-18 04:33:58 UTC (rev 8745)
@@ -793,3 +793,7 @@
...
+7.0 Error and return codes in the directory protocol
+
+We should write down what return codes dirservers send in what situations.
+
More information about the tor-commits
mailing list