torproject/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-12-06 19:41:15 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

clean up control spec, man page

Browse Source 
svn:r2703
This commit is contained in:
Roger Dingledine
2004-11-07 22:36:43 +00:00
parent 5475d1ce4b
commit c063fe6741
2 changed files with 69 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
trunk/doc/control-spec.txt
+40 -30
View File
@@ -4,13 +4,11 @@ $Id$
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 @@ 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
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 @@ 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
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 @@ 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
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 @@ 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.
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)
trunk/doc/tor.1.in
+29 -23
View File
@@ -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
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 @@ 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
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 @@ 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/