[or-cvs] r8805: spec and implement some more status events. start to build s (in tor/trunk: doc src/or)

arma at seul.org arma at seul.org
Mon Oct 23 10:16:50 UTC 2006


Author: arma
Date: 2006-10-23 06:16:43 -0400 (Mon, 23 Oct 2006)
New Revision: 8805

Modified:
   tor/trunk/doc/control-spec.txt
   tor/trunk/doc/rend-spec.txt
   tor/trunk/src/or/circuitbuild.c
   tor/trunk/src/or/main.c
   tor/trunk/src/or/routerlist.c
Log:
spec and implement some more status events. start to build
some conventions.


Modified: tor/trunk/doc/control-spec.txt
===================================================================
--- tor/trunk/doc/control-spec.txt	2006-10-23 10:15:01 UTC (rev 8804)
+++ tor/trunk/doc/control-spec.txt	2006-10-23 10:16:43 UTC (rev 8805)
@@ -40,10 +40,10 @@
 
 2.1. Description format
 
-  The message formats listed below use ABNF as described in RFC2234.
+  The message formats listed below use ABNF as described in RFC 2234.
   The protocol itself is loosely based on SMTP (see RFC 2821).
 
-  We use the following nonterminals from RFC2822: atom, qcontent
+  We use the following nonterminals from RFC 2822: atom, qcontent
 
   We define the following general-use nonterminals:
 
@@ -113,7 +113,7 @@
   ; A "Data" section is a sequence of octets concluded by the terminating
   ; sequence CRLF "." CRLF.  The terminating sequence may not appear in the
   ; body of the data.  Leading periods on lines in the data are escaped with
-  ; an additional leading period as in RFC2821 section 4.5.2
+  ; an additional leading period as in RFC 2821 section 4.5.2.
   Data = *DataLine "." CRLF
   DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
   LineItem = NonCR / 1*CR NonCRLF
@@ -942,27 +942,11 @@
      pairs on the same line.
 
      Controllers who listen to these events will be assumed to want
-     both EXTENDED_EVENTS and VERBOSE_NAMES; see the USEFEATURE command
-     for details.
+     both EXTENDED_EVENTS and VERBOSE_NAMES; see the explanations
+     in the USEFEATURE section command for details.
 
-[
-     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.
-no plans to use this yet -RD]
-
   Actions for STATUS_GENERAL severity NOTICE events can be as follows:
 
-     [none yet]
-
-  Actions for STATUS_GENERAL severity WARN events can be as follows:
-
-     DANGEROUS_VERSION
-     "current=version"
-     "recommended=version,version,..."
-     "reason=new/old/unrecommended"
-
      CLOCK_JUMPED
      "time=NUM"
        Tor spent enough time without CPU cycles that it has closed all
@@ -971,9 +955,22 @@
        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.]
+       This status event is sent as WARN severity if Tor is acting
+       as a server currently.
 
+       [Recommendation for controller: ignore it, since we don't really
+       know what the user should do anyway. Hm.]
+
+     DIR_REACHABLE
+     [not implemented yet]
+
+  Actions for STATUS_GENERAL severity WARN events can be as follows:
+
+     DANGEROUS_VERSION
+     "current=version"
+     "reason=new/old/unrecommended"
+     "recommended=\"version, version, ...\""
+
      TOO_MANY_CONNECTIONS
      "current=NUM"
        Tor has reached its ulimit -n or whatever the native limit is on
@@ -981,6 +978,7 @@
        about this. The "current" argument shows the number of connections
        currently open.
 
+   [rest not implemented yet]
      BUG
      "reason=STRING"
        Tor has encountered a situation that its developers never expected,
@@ -1000,28 +998,51 @@
 
   Actions for STATUS_GENERAL severity ERR events can be as follows:
 
-     BAD_PROXY
+U    BAD_PROXY
      // bad http or https proxy?
 
-     DIR_ALL_UNREACHABLE
+I    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:
+  [all implemented]
 
+     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.
+
+     NOT_ENOUGH_DIR_INFO
+       We discarded expired statuses and router descriptors to fall
+       below the desired threshold of directory information. We won't
+       try to build any circuits until ENOUGH_DIR_INFO occurs again.
+
      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.
+       Suggested use: controllers can notify their users that Tor is
+       ready for use as a client once they see this status event. [Perhaps
+       controllers should also have a timeout if too much time passes and
+       this event hasn't arrived, to give tips on how to troubleshoot.
+       On the other hand, hopefully Tor will send further status events
+       if it can identify the problem.]
 
+     CIRCUIT_NOT_ESTABLISHED
+     "reason=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED"
+       We are no longer confident that we can build circuits. The "reason"
+       keyword provides an explanation: which other status event type caused
+       our lack of confidence.
+
+       Suggested use: Vidalia can turn its onion yellow again.
+       [Note: only REASON=CLOCK_JUMPED is implemented currently.]
+
   Actions for STATUS_CLIENT severity WARN events can be as follows:
+  [none implemented yet]
 
      DANGEROUS_SOCKS
      "protocol=socks4/socks4a/socks5"
@@ -1042,6 +1063,7 @@
      [none yet]
 
   Actions for STATUS_SERVER severity NOTICE events can be as follows:
+  [none implemented yet]
 
      EXTERNAL_ADDRESS
      "address=IP"
@@ -1059,6 +1081,7 @@
        directory authorities, with no complaints.
 
   Actions for STATUS_SERVER severity WARN events can be as follows:
+  [not implemented yet]
 
      // something about failing to parse our address?
      // from resolve_my_address() in config.c
@@ -1076,6 +1099,7 @@
      // think it's malformed, you're invalid, or wrong key.
 
   Actions for STATUS_SERVER severity ERR events can be as follows:
+  [not implemented yet]
 
      REACHABILITY_FAILED
      "oraddress=IP:port"

Modified: tor/trunk/doc/rend-spec.txt
===================================================================
--- tor/trunk/doc/rend-spec.txt	2006-10-23 10:15:01 UTC (rev 8804)
+++ tor/trunk/doc/rend-spec.txt	2006-10-23 10:16:43 UTC (rev 8805)
@@ -265,7 +265,7 @@
    Omitting a string is taken to mean auth type [00 00].
    See section 2 of this document for details on auth mechanisms.
 
-   [Yes, numbers are allowed at the beginning.  See RFC1123. -NM]
+   [Yes, numbers are allowed at the beginning.  See RFC 1123. -NM]
 
 1.6. Alice's OP retrieves a service descriptor.
 

Modified: tor/trunk/src/or/circuitbuild.c
===================================================================
--- tor/trunk/src/or/circuitbuild.c	2006-10-23 10:15:01 UTC (rev 8804)
+++ tor/trunk/src/or/circuitbuild.c	2006-10-23 10:16:43 UTC (rev 8805)
@@ -652,14 +652,14 @@
 void
 circuit_note_clock_jumped(int seconds_elapsed)
 {
-  if (server_mode(get_options()))
-    log(LOG_WARN, LD_GENERAL,
-        "Please report: your clock just jumped %d seconds forward; "
-        "assuming established circuits no longer work.", seconds_elapsed);
-  else
-    log(LOG_NOTICE, LD_GENERAL, "Your clock just jumped %d seconds forward; "
-        "assuming established circuits no longer work.", seconds_elapsed);
+  int severity = server_mode(get_options()) ? LOG_WARN : LOG_NOTICE;
+  log(severity, LD_GENERAL, "Your clock just jumped %d seconds forward; "
+      "assuming established circuits no longer work.", seconds_elapsed);
+  control_event_general_status(LOG_WARN, "CLOCK_JUMPED TIME=%d",
+                               seconds_elapsed);
   has_completed_circuit=0; /* so it'll log when it works again */
+  control_event_client_status(severity, "CIRCUIT_NOT_ESTABLISHED REASON=%s",
+                              "CLOCK_JUMPED");
   circuit_mark_all_unused_circs();
   circuit_expire_all_dirty_circs();
 }

Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c	2006-10-23 10:15:01 UTC (rev 8804)
+++ tor/trunk/src/or/main.c	2006-10-23 10:16:43 UTC (rev 8805)
@@ -563,6 +563,7 @@
     connection_mark_unattached_ap(edge_conn,
                                   END_STREAM_REASON_NET_UNREACHABLE);
   }
+  control_event_general_status(LOG_ERR, "DIR_ALL_UNREACHABLE");
 }
 
 /** This function is called whenever we successfully pull down some new

Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c	2006-10-23 10:15:01 UTC (rev 8804)
+++ tor/trunk/src/or/routerlist.c	2006-10-23 10:16:43 UTC (rev 8805)
@@ -3080,6 +3080,9 @@
                  n_versioning-n_recommended, n_versioning, n_versioning/2,
                  n_versioning/2 > 1 ? "ies" : "y", rec);
           have_warned_about_new_version = 1;
+          control_event_general_status(LOG_WARN, "DANGEROUS_VERSION "
+                 "CURRENT=%s REASON=%s RECOMMENDED=\"%s\"",
+                 VERSION, "NEW", rec);
           tor_free(rec);
         }
       } else {
@@ -3092,6 +3095,9 @@
                  n_versioning-n_recommended, n_versioning, n_versioning/2,
                  n_versioning/2 > 1 ? "ies" : "y", rec);
         have_warned_about_old_version = 1;
+        control_event_general_status(LOG_WARN, "DANGEROUS_VERSION "
+                 "CURRENT=%s REASON=%s RECOMMENDED=\"%s\"",
+                 VERSION, consensus == VS_OLD ? "OLD" : "UNRECOMMENDED", rec);
         tor_free(rec);
       }
     } else {
@@ -3980,14 +3986,16 @@
   if (res && !have_min_dir_info) {
     log(LOG_NOTICE, LD_DIR,
         "We now have enough directory information to build circuits.");
+    control_event_client_status(LOG_NOTICE, "ENOUGH_DIR_INFO");
   }
   if (!res && have_min_dir_info) {
     log(LOG_NOTICE, LD_DIR,"Our directory information is no longer up-to-date "
         "enough to build circuits.%s",
         num_running > 2 ? "" : " (Not enough servers seem reachable -- "
         "is your network connection down?)");
+    control_event_client_status(LOG_NOTICE, "NOT_ENOUGH_DIR_INFO");
   }
-  need_to_update_have_min_dir_info = 0;
+  need_to_update_have_min_dir_info = 0; /* XXX redundant */
   have_min_dir_info = res;
 }
 



More information about the tor-commits mailing list