[or-cvs] clean up control spec, man page
Roger Dingledine
arma at seul.org
Sun Nov 7 22:36:45 UTC 2004
Update of /home/or/cvsroot/doc
In directory moria.mit.edu:/home2/arma/work/onion/cvs/doc
Modified Files:
tor.1.in control-spec.txt
Log Message:
clean up control spec, man page
Index: tor.1.in
===================================================================
RCS file: /home/or/cvsroot/doc/tor.1.in,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -d -r1.28 -r1.29
--- tor.1.in 5 Nov 2004 21:22:38 -0000 1.28
+++ tor.1.in 7 Nov 2004 22:36:43 -0000 1.29
@@ -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 @@
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 @@
\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
-Limit the maximum token bucket size (also known as the burst) to NUM bytes. (Default: 10000000)
+\fBBandwidthBurstBytes \fR\fINUM\fP
+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 @@
\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
-to adjust this. (Default: 900)
+Maximum number of simultaneous sockets allowed. You probably don't need
+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 @@
\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 @@
.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 @@
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 @@
\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 @@
.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 @@
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 @@
.SH SEE ALSO
.BR privoxy (1),
-.BR tsocks (1)
+.BR tsocks (1),
+.BR torify (1)
.BR http://freehaven.net/tor/
Index: control-spec.txt
===================================================================
RCS file: /home/or/cvsroot/doc/control-spec.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- control-spec.txt 4 Nov 2004 22:30:14 -0000 1.5
+++ control-spec.txt 7 Nov 2004 22:36:43 -0000 1.6
@@ -4,13 +4,11 @@
0. Scope
-(8 Aug 2004) This document describes an implementation-specific protocol to
-be implemented in a future version of Tor. It is not part of the Tor onion
+This document describes an implementation-specific protocol that is used
+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 @@
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
-should not be observable by untrusted parties.
+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 variable-length messages to one
-another over the underlying stream. By default, all messages from the server
+In TC, the client and server send typed variable-length messages to each
+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 @@
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 @@
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
- containing the key and no value.
+ To _remove_ all settings for a given option entirely (and go back to its
+ default value), send a single line containing the key and no value.
3.4. GETCONF (Type 0x0003)
@@ -96,21 +95,17 @@
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
- should use the "LogOptions" virtual keyword to get all LogFile, LogLevel,
- and SysLog option settings; and "HiddenServiceOptions" to get all
- HiddenServiceDir, HiddenServicePort, HiddenServiceNodes, and
- HiddenServiceExcludeNodes options.
+ different keywords. These cannot be fetched directly. Currently there
+ is only one such option: clients should use the "HiddenServiceOptions"
+ virtual keyword to get all HiddenServiceDir, HiddenServicePort,
+ HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
3.5. CONFVALUE (Type 0x0004)
- Sent in response to a GETCONF message; contains a list of list of "Key
- Value\n" (A non-whitespace keyword, a single space, a non-NL value, a NL)
+ Sent in response to a GETCONF message; contains a list of "Key Value\n"
+ (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 @@
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 @@
(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 @@
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 @@
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.
-On Win32, our only options are 1, 3, and 4. Since the semantics for 2 and 3
-are so similar, I'm recommending that we not support 2, and just always bind
-on 127.0.0.1. I've implemented 3 and 4; 1 would be trivial. -NM
+ 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.
+
+ If you ask for lots of events, and 16MB of them queue up on the buffer,
+ the Tor process will close the socket.
-----------
(for emacs)
More information about the tor-commits
mailing list