[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
Date: 2006-10-18 00:33:58 -0400 (Wed, 18 Oct 2006)
New Revision: 8745
hammer farther on the status events. still a lot of questions.
--- 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.)
+ 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.]
C: GETINFO version desc/name/moria1
@@ -873,43 +888,24 @@
[Don't rely on any of these until we work out more of the details. -RD]
- "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.
- 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:
- 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]
+ Actions for STATUS_GENERAL severity WARN events can be as follows:
- // hibernating
- Actions for STATUS_WARN events can be as follows:
@@ -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.]
@@ -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:]
// unexpected dir response. behind a hotel/airport firewall?
- // bad http or https proxy?
- // clock is skewed
// (either from talking to a dir authority, or from perusing a
// network-status timestamp)
+ Actions for STATUS_GENERAL severity ERR events can be as follows:
+ // bad http or https proxy?
+ 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:
+ 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.
+ 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:
@@ -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.
+ Actions for STATUS_CLIENT severity ERR events can be as follows:
+ [none yet]
+ Actions for STATUS_SERVER severity NOTICE events can be as follows:
+ // hibernating
+ 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?
+ // eventdns statements. like, hijacked dns.
// dir authorities didn't like my descriptor
- // eventdns statements. like, hijacked dns.
+ Actions for STATUS_SERVER severity ERR events can be as follows:
Controllers must tolerate hearing about actions that they don't
+4.1.11. Our set of guard nodes has changed
+ "650" SP "GUARDS" SP Type SP ...
+ Type = "ENTRY"
+ [needs to be fleshed out; not implemented yet]
5. Implementation notes
--- 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