summaryrefslogtreecommitdiff
path: root/doc/control-spec.txt
diff options
context:
space:
mode:
authorRoger Dingledine <arma@torproject.org>2006-10-14 03:32:33 +0000
committerRoger Dingledine <arma@torproject.org>2006-10-14 03:32:33 +0000
commit6851d7f85437d4ad6a70bf0aeeda26dc5816c02d (patch)
tree82defd001b86e74c3d223ded3c63d02c2ae6c57d /doc/control-spec.txt
parent45b16c2d9ec7ab49f09fe43f07d84b5dcc252bd1 (diff)
downloadtor-6851d7f85437d4ad6a70bf0aeeda26dc5816c02d.tar.gz
tor-6851d7f85437d4ad6a70bf0aeeda26dc5816c02d.zip
flesh out the status events some more
svn:r8715
Diffstat (limited to 'doc/control-spec.txt')
-rw-r--r--doc/control-spec.txt96
1 files changed, 84 insertions, 12 deletions
diff --git a/doc/control-spec.txt b/doc/control-spec.txt
index b26679f4cb..10d3b9d9be 100644
--- a/doc/control-spec.txt
+++ b/doc/control-spec.txt
@@ -369,6 +369,10 @@ $Id$
"address" -- the best guess at our external IP address. If we
have no guess, return a 551 error. (Added in 0.1.2.2-alpha)
+ "fingerprint" -- the contents of the fingerprint file that Tor
+ writes as a server; or a 551 if we're not a server currently.
+ (Added in 0.1.2.3-alpha)
+
"circuit-status"
A series of lines as for a circuit status event. Each line is of
the form:
@@ -446,6 +450,14 @@ $Id$
information for which this Tor is not authoritative, Tor replies with
an empty string.
+ "status/general/..."
+ "status/client/circuit-established"
+ "status/server/..."
+ These provide the current internal Tor values for various Tor
+ states. See Section 4.1.10 for explanations. (Only a few of the
+ status events are available as getinfo's currently. Let us know if
+ you want more exposed.)
+
Examples:
C: GETINFO version desc/name/moria1
S: 250+desc/name/moria=
@@ -857,31 +869,91 @@ $Id$
4.1.10. Status events
+ [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_CLIENT" / "STATUS_SERVER"
+ Type = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
Action is a string, and Arguments is a series of key=value
pairs; more details below.
+ Actions for STATUS_GENERAL 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
+ its circuits and will establishing them anew. This typically
+ happens when a laptop goes to sleep and then wakes up again. It
+ 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.
+
+ TOO_MANY_CONNECTIONS
+ "limit=NUM"
+ Tor has reached its ulimit -n or whatever the native limit is on
+ file descriptors or sockets. The user should really do something
+ about this. The "limit" argument shows the number of connections
+ currently open.
+
+ BUG
+ "reason=STRING"
+ Tor has encountered a situation that its developers never expected,
+ and the developers would like to learn that it happened. Perhaps
+ the controller can explain this to the user and encourage her to
+ file a bug report?
+
+
Actions for STATUS_CLIENT events can be as follows:
- CIRCUIT_ESTABLISHED means that 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.
+ 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.
+
+ DANGEROUS_SOCKS
+ "protocol=socks4/socks4a/socks5"
+ "address=IP:port"
+
+ SOCKS_UNKNOWN_PROTOCOL
+ A connection was made to Tor's SOCKS port that tried to use it
+ for something other than the SOCKS protocol. Perhaps the user is
+ using Tor as an HTTP 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.
- CLOCK_JUMPED means that Tor spent enough time without CPU cycles
- that it has closed all its circuits and will establishing them
- anew. This typically happens when a laptop goes to sleep and then
- wakes up again. It also happens when the system is swapping so
- heavily that Tor is starving. The Arguments line in this case is
- "time=NUM", a non-negative integer representing the number of
- seconds Tor thinks it was unconscious for.
Actions for STATUS_SERVER events can be as follows:
+ EXTERNAL_ADDRESS
+ "address=IP"
+ "method=guessed/resolved/..."
+
+ CHECKING_REACHABILITY
+ "oraddress=IP:port"
+ "diraddress=IP:port"
+ "timeout=NUM"
+
+ REACHABILITY_FAILED
+ "oraddress=IP:port"
+ "diraddress=IP:port"
+
+
+
+
+ Controllers must tolerate hearing about status types and actions
+ that they don't recognize.
5. Implementation notes