some fixes and questions on the control spec

svn:r4450

doc/control-spec.txt

@@ -17,10 +17,10 @@ $Id$
 1 Protocol outline
 
   TC is a bidirectional message-based protocol.  It assumes an underlying
-  stream for communication between a controlling process (the "client" or
-  "controller") and a Tor process (the "server" or "tor process").  The
-  stream may be implemented via TCP, TLS-over-TCP, a Unix-domain socket, or
-  so on, but it must provide reliable in-order delivery.  For security, the
+  stream for communication between a controlling process (the "client"
+  or "controller") and a Tor process (or "server").  The stream may be
+  implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
+  but it must provide reliable in-order delivery.  For security, the
   stream should not be accessible by untrusted parties.
 
   In TC, the client and server send typed messages to each other over the
@@ -30,15 +30,15 @@ $Id$
   By default, all messages from the server are in response to messages from
   the client.  Some client requests, however, will cause the server to send
   messages to the client indefinitely far into the future.  Such
-  "asynchronous" replies are marked to such.
+  "asynchronous" replies are marked as such.
 
   Servers respond to messages in the order messages are received.
 
 2 Message format
 
-2.1 Description format.
+2.1 Description format
 
-  The message formates listed below use ABNF as described in RFC2234.
+  The message formats listed below use ABNF as described in RFC2234.
   The protocol itself is loosely based on SMTP (see RFC 2821).
 
   We use the following nonterminals from RFC2822: atom, qcontent
@@ -50,7 +50,7 @@ $Id$
   There are explicitly no limits on line length.  All 8-bit characters are
   permitted unless explicitly disallowed.
 
-2.2 Commands from controller to Tor.
+2.2 Commands from controller to Tor
 
     Command = Keyword Arguments CRLF / "+" Keyword Arguments CRLF Data
     Keyword = 1*ALPHA
@@ -77,6 +77,7 @@ $Id$
   ; Identifiers for servers.
   ServerID = Nickname / Fingerprint
   Nickname = 1*NicknameChar
+[XXX perhaps this should be 1*19 NicknameChar ? -RD]
   NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
   Fingerprint = "$" 40*HEXDIG
 
@@ -119,7 +120,7 @@ $Id$
   syntax error, or a "553 impossible configuration setting" reply on a
   semantic error.
 
-  When a configuration options takes multiple values, or when multiple
+  When a configuration option takes multiple values, or when multiple
   configuration keys form a context-sensitive group (see GETCONF below), then
   setting _any_ of the options in a SETCONF command is taken to reset all of
   the others.  For example, if two ORBindAddress values are configured, and a
@@ -161,6 +162,9 @@ $Id$
      EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
          "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC"
 
+[XXX We should have an "ADDRESSMAP" event to hear when we learn
+about dns resolves, etc, so the controller can keep synced. -RD]
+
   Any events *not* listed in the SETEVENTS line are turned off; thus, sending
   SETEVENTS with an empty body turns off all event reporting.
 
@@ -189,8 +193,8 @@ $Id$
      "SAVECONF" CRLF
 
   Instructs the server to write out its config options into its torrc. Server
-  returns "250 OK" if successful, or " if it can't write the file or some
-  other error occurs.
+  returns "250 OK" if successful, or "551 Unable to write configuration
+  to disk" if it can't write the file or some other error occurs.
 
 3.6 SIGNAL
 
@@ -202,14 +206,14 @@ $Id$
 
   The meaning of the signals are:
 
-      RELOAD    -- Reload: reload config items, refetch directory. (as for HUP)
+      RELOAD    -- Reload: reload config items, refetch directory. (like HUP)
       SHUTDOWN  -- Controlled shutdown: if server is an OP, exit immediately.
                    If it's an OR, close listeners and exit after 30 seconds.
-                   (as for INT)
+                   (like INT)
       DUMP      -- Dump stats: log information about open connections and
-                   circuits.  (as for USR1)
-      DEBUG     -- Debug: switch all open logs to loglevel debug. (as for USR2)
-      TERM      -- Immediate shutdown: clean up and exit now. (as for TERM)
+                   circuits. (like USR1)
+      DEBUG     -- Debug: switch all open logs to loglevel debug. (like USR2)
+      TERM      -- Immediate shutdown: clean up and exit now. (like TERM)
 
   The server responds with "250 OK" if the signal is recognized (or simply
   closes the socket if it was asked to close immediately), or "552
@@ -264,7 +268,10 @@ $Id$
         has resolved to that IP.
   This functionality is designed to help implement the 3rd approach.}
 
-  [XXXX When, if ever, can mappings expire?  Should they expire?]
+  Mappings set by the controller last until the Tor process exits:
+  they never expire. If the controller wants the mapping to last only
+  a certain time, then it must explicitly un-map the address when that
+  time has elapsed.
 
 3.8 GETINFO
 
@@ -314,7 +321,7 @@ $Id$
          StreamID SP StreamStatus SP Target CRLF
 
     "orconn-status"
-      A series of lines as for a OR connection status event.  Each is of the
+      A series of lines as for an OR connection status event.  Each is of the
       form:
          ServerID SP ORStatus CRLF
 
@@ -329,7 +336,7 @@ $Id$
 3.9 EXTENDCIRCUIT
 
   Sent from the client to the server.  The format is:
-      "EXTENDCIRCUIT" SP CircuitID SP SeverID *("," ServerID) CRLF
+      "EXTENDCIRCUIT" SP CircuitID SP ServerID *("," ServerID) CRLF
 
   This request takes one of two forms: either the Circuit ID is zero, in
   which case it is a request for the server to build a new circuit according
@@ -338,8 +345,10 @@ $Id$
   to the specified path.
 
   If the request is successful, the server sends a "250 OK" message containing
-  a message body consisting of the four-octet Circuit ID of the newly created
-  circuit.
+  a message body consisting of the four-octet Circuit ID of the (maybe
+  newly created) circuit.
+
+[XXX four-octet? that sounds binary to me, yes? -RD]
 
 3.10 ATTACHSTREAM
 
@@ -350,7 +359,8 @@ $Id$
   associated with the specified circuit.  Each stream may be associated with
   at most one circuit, and multiple streams may share the same circuit.
   Streams can only be attached to completed circuits (that is, circuits that
-  have sent a circuit status 'built' event).
+  have sent a circuit status 'built' event or are listed as built in a
+  GETINFO circuit-status request).
 
   If the circuit ID is 0, responsibility for attaching the given stream is
   returned to Tor.
@@ -376,7 +386,9 @@ $Id$
   fields, including fields for its nickname and identity.
 
   If there is an error in parsing the descriptor, the server must send an
-  appropriate error message.  If the descriptor is well-formed but the server
+  appropriate error message.
+[XXX let's specify the status code here too -RD]
+  If the descriptor is well-formed but the server
   chooses not to add it, it must reply with a 251 message whose body
   explains why the server was not added.
 
@@ -421,7 +433,7 @@ $Id$
 
   Reply codes follow the same 3-character format as used by SMTP, with the
   first character defining a status, the second character defining a
-  subsystem, and the third designates fine-grained information.
+  subsystem, and the third designating fine-grained information.
 
   The TC protocol currently uses the following first characters:
 
@@ -446,7 +458,7 @@ $Id$
     x1z   Protocol
        Refers to operations of the Tor Control protocol.
 
-    x2z   Tor
+    x5z   Tor
        Refers to actual operations of Tor system.
 
   The following codes are defined:
@@ -482,7 +494,7 @@ $Id$
 
      650 Asynchronous event notification
 
-4.1 Anynchronous events
+4.1 Asynchronous events
 
   These replies can be sent after a corresponding SETEVENTS command has been
   received.  They will not be interleaved with other Reply elements, but they
@@ -602,3 +614,4 @@ $Id$
   whether the third byte the first command is zero.  If it is, Tor
   assumes that version 0 is in use.  This feature is deprecated, and will be
   removed in the 0.1.2.x Tor development series.
+