clean up control spec, man page

svn:r2703

doc/control-spec.txt

@@ -4,13 +4,11 @@ $Id$
 
 0. Scope
 
-(8 Aug 2004) This document describes an implementation-specific protocol to
+This document describes an implementation-specific protocol that is used
-be implemented in a future version of Tor.  It is not part of the Tor onion
+for other programs (such as frontend user-interfaces) to communicate
+with a locally running Tor process.  It is not part of the Tor onion
 routing protocol.
 
-The protocol described in this document is used for other programs (such as
-frontend user-interfaces) to communicate with a locally running Tor process.
-
 We're trying to be pretty extensible here, but not infinitely
 forward-compatible.
 
@@ -19,11 +17,12 @@ forward-compatible.
 TC is a bidirectional message-based protocol.  It assumes an underlying
 stream for communication between a controlling process (the "client") and
 a Tor process (the "server").  The stream may be implemented via TCP,
-TLS-over-TCP, a Unix-domain socket, or so on.  For security, the stream
+TLS-over-TCP, a Unix-domain socket, or so on, but it must provide
-should not be observable by untrusted parties.
+reliable in-order delivery.  For security, the stream should not be
+accessible by untrusted parties.
 
-In TC, the client and server send typed variable-length messages to one
+In TC, the client and server send typed variable-length messages to each
-another over the underlying stream.  By default, all messages from the server
+other over the underlying stream.  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.
@@ -39,7 +38,7 @@ The messages take the following format:
    Body   [Length octets]
 
 Upon encountering a recognized Type, implementations behave as described in
-section 3 below.  If the type is not recognized, servers respond with an
+section 3 below.  If the type is not recognized, servers respond with a
 "STAT" message (code UNRECOGNIZED; see 3.1 below), and clients simply ignore
 the message.
 
@@ -79,12 +78,12 @@ the message.
   When a configuration options takes multiple values, or when multiple
   configuration keys form a context-sensitive group (see 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 provided,
+  the others.  For example, if two ORBindAddress values are configured,
   and a SETCONF command arrives containing a single ORBindAddress value, the
   new command's value replaces the two old values.
 
-  To _remove_ all settings for a given option entirely, send a single line
+  To _remove_ all settings for a given option entirely (and go back to its
-  containing the key and no value.
+  default value), send a single line containing the key and no value.
 
 3.4. GETCONF (Type 0x0003)
 
@@ -96,21 +95,17 @@ the message.
   key-value pairs are returned in order.
 
   Some options are context-sensitive, and depend on other options with
-  different keywords.  These cannot be fetched directly.  Instead, clients
+  different keywords.  These cannot be fetched directly.  Currently there
-  should use the "LogOptions" virtual keyword to get all LogFile, LogLevel,
+  is only one such option: clients should use the "HiddenServiceOptions"
-  and SysLog option settings; and "HiddenServiceOptions" to get all
+  virtual keyword to get all HiddenServiceDir, HiddenServicePort,
-  HiddenServiceDir, HiddenServicePort, HiddenServiceNodes, and
+  HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
-  HiddenServiceExcludeNodes options.
 
 3.5. CONFVALUE (Type 0x0004)
 
-  Sent in response to a GETCONF message; contains a list of list of "Key
+  Sent in response to a GETCONF message; contains a list of "Key Value\n"
-  Value\n" (A non-whitespace keyword, a single space, a non-NL value, a NL)
+  (A non-whitespace keyword, a single space, a non-NL value, a NL)
   strings.
 
-  [XXXX note that you'll get more keys than you expect with things like
-  loglevel.]
-
 3.6. SETEVENTS (Type 0x0005)
 
   Request the server to inform the client about interesting events.
@@ -123,9 +118,9 @@ the message.
 
 3.7. EVENT (Type 0x0006)
 
-  Sent from the server to the client when an event has occurred, and the
+  Sent from the server to the client when an event has occurred and the
   client has requested that kind of event.  The body contains a 2-byte
-  event code, followed by additional event-dependent information.  Event
+  event code followed by additional event-dependent information.  Event
   codes are:
       0x0001 -- Circuit status changed
 
@@ -152,8 +147,9 @@ the message.
                    (Launched=0,connected=1,failed=2,closed=3)
                 OR nickname/identity [NUL-terminated]
 
-      0x0004 -- Bandwidth used in last N seconds. (N=1? 5?)
+      0x0004 -- Bandwidth used in last N seconds.
 
+                Number of seconds covered in interval [2 octets]
                 Bytes read [4 octets]
                 Bytes written [4 octets]
 
@@ -167,9 +163,15 @@ the message.
   that client is really the admin for this Tor process.  The server responds
   with DONE or ERROR.
 
+3.9. SAVECONF (Type 0x0008)
+
+  Sent from the client to the server. Instructs the server to write out
+  its config options into its torrc. Server returns DONE if successful, or
+  ERROR if it can't write the file or some other error occurs.
+
 4. Implementation notes
 
-There are four ways we could authenticate, for now:
+4.1. There are four ways we could authenticate, for now:
 
  1) Listen on 127.0.0.1; trust all local users.
 
@@ -186,10 +188,18 @@ There are four ways we could authenticate, for now:
  4) Store a salted-and-hashed passphrase in Tor's configuration.  Use the
     passphrase for authentication.  Trust all users who know the passphrase.
 
+  On Win32, our only options are 1, 3, and 4.  Since the semantics for 2
+  and 3 are so similar, we chose to not support 2, and just always bind
+  on 127.0.0.1.  We've implemented 1, 3, and 4.
+
+  By default, the Tor client accepts authentication approach #1. If
+  the controller wants Tor to demand more authentication, it should use
+  setconf and saveconf to configure Tor to demand more next time.
+
+4.2. Don't let the buffer get too big.
 
-On Win32, our only options are 1, 3, and 4.  Since the semantics for 2 and 3
+  If you ask for lots of events, and 16MB of them queue up on the buffer,
-are so similar, I'm recommending that we not support 2, and just always bind
+  the Tor process will close the socket.
-on 127.0.0.1.  I've implemented 3 and 4; 1 would be trivial.  -NM
 
 -----------
 (for emacs)

doc/tor.1.in

@@ -1,4 +1,4 @@
-.TH TOR 1 "November 2003" "TOR"
+.TH TOR 1 "November 2004" "TOR"
 .SH NAME
 tor \- The second-generation onion router
 .SH SYNOPSIS
@@ -28,9 +28,9 @@ Other options can be specified either on the commandline (\fI--option
 value\fR), or in the configuration file (\fIoption value\fR).
 Options are case-insensitive.
 .TP
-\fBLog \fR\fIminSeverity\fR-\fImaxSeverity\fR \fBstderr\fR|\fBstdout\fR|\fBsyslog\fR\fP
+\fBLog \fR\fIminSeverity\fR[-\fImaxSeverity\fR] \fBstderr\fR|\fBstdout\fR|\fBsyslog\fR\fP
 Send all messages between \fIminSeverity\fR and \fImaxSeverity\fR to
-the standard output stream, the standard error strem, or to the system
+the standard output stream, the standard error stream, or to the system
 log. (The "syslog" value is only supported on Unix.)  Recognized
 severity levels are debug, info, notice, warn, and err.  If only one
 severity level is given, all messages of that level or higher will be
@@ -39,13 +39,13 @@ sent to the listed destination.
 \fBLog \fR\fIminSeverity\fR-\fImaxSeverity\fR \fBfile\fR \fIFILENAME\fP
 As above, but send log messages to the listed filename.  The "Log"
 option may appear more than once in a configuration file.  Messages
-messaes are sent to all the logs that match their severity level.
+are sent to all the logs that match their severity level.
 .TP
-\fBBandwidthRate \fR\fINUM\fP
+\fBBandwidthRateBytes \fR\fINUM\fP
 A token bucket limits the average incoming bandwidth on this node to NUM bytes per second. (Default: 800000)
 .TP
-\fBBandwidthBurst \fR\fINUM\fP
+\fBBandwidthBurstBytes \fR\fINUM\fP
-Limit the maximum token bucket size (also known as the burst) to NUM bytes. (Default: 10000000)
+Limit the maximum token bucket size (also known as the burst) to NUM bytes. (Default: 50000000)
 .TP
 \fBDirServer \fR\fIaddress:port fingerprint\fP
 Use a nonstandard authoritative directory server at the provided
@@ -57,14 +57,19 @@ directory servers: moria1, moria2, and tor26.
 \fBGroup \fR\fIGID\fP
 On startup, setgid to this user.
 .TP
+\fBHttpProxy\fR \fIhost\fR[:\fIport\fR]\fP
+If set, Tor will make all its directory requests through this host:port,
+rather than connecting directly to any directory servers.
+.TP
 \fBKeepalivePeriod \fR\fINUM\fP
-To keep firewalls from expiring connections, send a padding keepalive cell on open connections every NUM seconds. (Default: 300)
+To keep firewalls from expiring connections, send a padding keepalive
+cell on open connections every NUM seconds. (Default: 300)
 .TP
 \fBMaxConn \fR\fINUM\fP
-Maximum number of simultaneous connections allowed.  You probably don't need
+Maximum number of simultaneous sockets allowed.  You probably don't need
-to adjust this. (Default: 900)
+to adjust this. (Default: 1024)
 .TP
-\fBOutboundBindAddress \fR\fIP\fP
+\fBOutboundBindAddress \fR\fIIP\fP
 Make all outbound connections originate from the IP address specified.  This
 is only useful when you have multiple network interfaces, and you want all
 of Tor's outgoing connections to use a single one.
@@ -72,7 +77,7 @@ of Tor's outgoing connections to use a single one.
 \fBPIDFile \fR\fIFILE\fP
 On startup, write our PID to FILE. On clean shutdown, remove FILE.
 .TP
-\fBRunAsDaemon \fR\fI0|1\fP
+\fBRunAsDaemon \fR\fB0\fR|\fB1\fR\fP
 If 1, Tor forks and daemonizes to the background. (Default: 0)
 .TP
 \fBUser \fR\fIUID\fP
@@ -82,7 +87,7 @@ On startup, setuid to this user.
 .PP
 The following options are useful only for clients (that is, if \fBSOCKSPort\fP is non-zero):
 .TP
-\fBAllowUnverifiedNodes \fR\fIentry|exit|middle|introduction|rendezvous,...\fP
+\fBAllowUnverifiedNodes\fR \fBentry\fR|\fBexit\fR|\fBmiddle\fR|\fBintroduction\fR|\fBrendezvous\fR|...\fP
 Where on our circuits should we allow Tor servers that the directory
 servers haven't authenticated as "verified"?  (Default: middle,rendezvous.)
 \fBdirfetchpostperiod \fR\fIseconds\fP
@@ -92,10 +97,10 @@ running as a server, Tor also re-uploads information about itself to
 the directory servers.  (Tor also uploads this information whenever it 
 changes.)  (Default: 600.)
 .TP
-\fBClientOnly \fR\fI0|1\fP
+\fBClientOnly \fR\fB0\fR|\fB1\fR\fP
 If set to 1, Tor will under no circumstances run as a server.  (Usually,
 you don't need to set this; Tor is pretty smart at figuring out whether
-you are reliable and high-bandwith enough to be a good server.)
+you are reliable and high-bandwidth enough to be a good server.)
 .TP
 \fBEntryNodes \fR\fInickname,nickname,...\fP
 A list of preferred nodes to use for the first hop in the circuit, if possible.
@@ -106,23 +111,23 @@ A list of preferred nodes to use for the last hop in the circuit, if possible.
 \fBExcludeNodes \fR\fInickname,nickname,...\fP
 A list of nodes to never use when building a circuit.
 .TP
-\fBStrictExitNodes \fR\fI0|1\fP
+\fBStrictExitNodes \fR\fB0\fR|\fB1\fR\fP
 If 1, Tor will never use any nodes besides those listed in "exitnodes" for
 the last hop of a circuit.
 .TP
-\fBStrictEntryNodes \fR\fI0|1\fP
+\fBStrictEntryNodes \fR\fB0\fR|\fB1\fR\fP
 If 1, Tor will never use any nodes besides those listed in "entrynodes" for
 the first hop of a circuit.
 .TP
-\fBFascistFirewall \fR\fI0|1\fP
+\fBFascistFirewall \fR\fB0\fR|\fB1\fR\fP
 If 1, Tor will only create outgoing connections to ORs running on ports that
-your firewall allows (defaults to 80 and 443; see firewallports).  This will
+your firewall allows (defaults to 80 and 443; see \fBFirewallPorts\fR).  This will
 allow you to run Tor as a client behind a firewall with restrictive policies,
 but will not allow you to run as a server behind such a firewall.
 .TP
 \fBFirewallPorts \fR\fIPORTS\fP
 A list of ports that your firewall allows you to connect to.  Only used when
-fascistfirewall is set. (Default: 80, 443.)
+\fBFascistFirewall\fR is set. (Default: 80, 443.)
 .TP
 \fB
 \fBNewCircuitPeriod \fR\fINUM\fP
@@ -242,7 +247,7 @@ considered.
 .PP
 The following options are useful only for directory servers (that is, if \fBDirPort\fP is non-zero):
 .TP
-\fBAuthoritativeDirectory \fR\fI0|1\fP
+\fBAuthoritativeDirectory \fR\fB0\fR|\fB1\fR\fP
 When this option is set to 1, Tor operates as an authoritative
 directory server.  Instead of caching the directory, it generates its
 own list of good servers, signs it, and sends that to the clients.
@@ -269,7 +274,7 @@ pull down the directory learn whether they need to upgrade.  This
 option can appear multiple times: the values from multiple lines are
 spliced together.
 .TP
-\fBRunTesting \fR\fI0|1\fP
+\fBRunTesting \fR\fB0\fR|\fB1\fR\fP
 If set to 1, Tor tries to build circuits through all of the servers it
 knows about, so it can tell which are up and which are down.  This
 option is only useful for authoritative directories, so you probably
@@ -316,7 +321,8 @@ The tor process stores keys and other data here.
 
 .SH SEE ALSO
 .BR privoxy (1),
-.BR tsocks (1)
+.BR tsocks (1),
+.BR torify (1)
 
 .BR http://freehaven.net/tor/