[tor-commits] [torspec/master] Various changes in proposals/180-pluggable-transport.txt.
nickm at torproject.org
nickm at torproject.org
Thu Jul 14 14:58:38 UTC 2011
commit 58698d7dc4aafe668fc953878eb8daed2fbca87a
Author: George Kadianakis <desnacked at gmail.com>
Date: Wed Jul 13 01:00:39 2011 +0200
Various changes in proposals/180-pluggable-transport.txt.
* Namespaced environment variables.
* BNFed the line metaformat. If we want to be formalizing smartasses, we better do it correctly.
* Played with the protocol strings a bit:
* Replaced "ERROR" with "VERSION-ERROR" to go with the FOO-ERROR pattern.
* Added "ENV-ERROR" for errors in the environment variables.
* Defined the configuration protocol version described in the current 180-pluggable-transport.txt.
* Changed a couple of other stuff that looked kinda weird.
---
proposals/180-pluggable-transport.txt | 142 ++++++++++++++++++++-------------
1 files changed, 85 insertions(+), 57 deletions(-)
diff --git a/proposals/180-pluggable-transport.txt b/proposals/180-pluggable-transport.txt
index 16ad761..f6e25b7 100644
--- a/proposals/180-pluggable-transport.txt
+++ b/proposals/180-pluggable-transport.txt
@@ -179,9 +179,9 @@ Specifications: Client behavior
There are two ways to tell Tor clients about protocol proxies:
external proxies and managed proxies. An external proxy is configured
with
- ClientTransportPlugin method socks4 address:port [auth=X]
+ ClientTransportPlugin <method> socks4 <address:port> [auth=X]
or
- ClientTransportPlugin method socks5 address:port [username=X] [password=Y]
+ ClientTransportPlugin <method> socks5 <address:port> [username=X] [password=Y]
as in
"ClientTransportPlugin trebuchet socks5 127.0.0.1:9999".
This example tells Tor that another program is already running to handle
@@ -190,7 +190,7 @@ Specifications: Client behavior
A managed proxy is configured with
ClientTransportPlugin <method> exec <path> [options]
as in
- "ClientTransportPlugin trebuchet exec /usr/libexec/trebuchet --managed"
+ "ClientTransportPlugin trebuchet exec /usr/libexec/trebuchet --managed".
This example tells Tor to launch an external program to provide a
socks proxy for 'trebuchet' connections. The Tor client only
launches one instance of each external program with a given set of
@@ -228,16 +228,16 @@ Server behavior
launches.
An external server proxy is configured as
- ServerTransportPlugin method proxy address:port param=val..
+ ServerTransportPlugin <method> <address:port> <param=val> ...
as in
- ServerTransportPlugin trebuchet proxy 127.0.0.1:999 rocks=heavy
+ "ServerTransportPlugin trebuchet 127.0.0.1:999 rocks=heavy".
The param=val pairs and the address are used to make the bridge
configuration information that we'll tell users.
A managed proxy is configured as
- ServerTransportPlugin method exec /path/to/binary [options]
+ ServerTransportPlugin <method> exec </path/to/binary> [options]
or
- ServerTransportPlugin * exec /path/to/binary [options]
+ ServerTransportPlugin * exec </path/to/binary> [options]
When possible, Tor should launch only one binary of each binary/option
pair configured. So if the torrc contains
@@ -258,61 +258,81 @@ Managed proxy interface
"HOME", "PATH" -- as you'd expect.
- "STATE_LOCATION" -- a directory where the proxy should store
- state if it wants to. This directory is not required to
- exist, but the proxy SHOULD be able to create it if it
- doesn't. The proxy SHOULD NOT store state elsewhere.
+ "TOR_PT_STATE_LOCATION" -- A filesystem directory path where the
+ proxy should store state if it wants to. This directory is not
+ required to exist, but the proxy SHOULD be able to create it if
+ it doesn't. The proxy MUST NOT store state elsewhere.
+ Example: TOR_PT_STATE_LOCATION=/var/lib/tor/pt_state/
- "MANAGED_TRANSPORT_VER=1" -- To tell the proxy which versions
- of this configuration protocol Tor supports. Future versions
- will give a comma-separated list. Clients MUST accept
+ "TOR_PT_MANAGED_TRANSPORT_VER" -- To tell the proxy which
+ versions of this configuration protocol Tor supports. Future
+ versions will give a comma-separated list. Clients MUST accept
comma-separated lists containing any version that they
- recognize, and MUST work correctly even if some of the
- versions they don't recognize are non-numeric. Valid version
- characters are non-space, non-comma printing ASCII characters.
+ recognize, and MUST work correctly even if some of the versions
+ they don't recognize are non-numeric. Valid version characters
+ are non-space, non-comma printing ASCII characters.
+ Example: TOR_PT_MANAGED_TRANSPORT_VER=1,1a,2,4B
{Client only}
- "CLIENT_TRANSPORTS" -- a comma-separated list of which methods
- this client should enable, or * if all methods should be
- enabled. The proxy SHOULD ignore methods that it doesn't
- recognize.
+ "TOR_PT_CLIENT_TRANSPORTS" -- A comma-separated list of which
+ methods this client should enable, or * if all methods should
+ be enabled. The proxy SHOULD ignore methods that it doesn't
+ recognize.
+ Example: TOR_PT_CLIENT_TRANSPORTS=trebuchet,battering_ram,ballista
{Server only}
- "EXTENDED_SERVER_PORT=addr:portnum" -- A port (probably on localhost)
- that speaks the extended server protocol. (See the "The extended
- ORPort protocol" section below.)
-
- "ORPORT=addr:portnum" -- Our regular ORPort in a form suitable
- for local connections, i.e. connections from the proxy to
- the ORPort.
-
- "BINDADDR=addr" -- An address on which to listen for client proxy
- connections. This might be the advertised address, or might
- be a local address that Tor will forward ports to. It MUST
- be an address that will work with bind().
-
- "SERVER_TRANSPORTS=..." -- A comma-separated list of server
- methods that the proxy should support, or * if all methods
- should be enabled. The proxy SHOULD ignore methods that it
- doesn't recognize.
+ "TOR_PT_EXTENDED_SERVER_PORT" -- A port (probably on localhost)
+ that speaks the extended server protocol. (See the "The extended
+ ORPort protocol" section below.)
+ Example: TOR_PT_EXTENDED_SERVER_PORT=4200
+
+ "TOR_PT_ORPORT" -- Our regular ORPort in a form suitable
+ for local connections, i.e. connections from the proxy to
+ the ORPort.
+ Example: TOR_PT_ORPORT=9001
+
+ "TOR_PT_SERVER_BINDADDR" -- The address[:port] on which to
+ listen for client proxy connections. This might be the
+ advertised address, or might be a local address that Tor will
+ forward ports to. It MUST be an address that will work with
+ bind().
+ Example: TOR_PT_SERVER_BINDADDR=127.0.0.1:1984
+
+ "TOR_PT_SERVER_TRANSPORTS" -- A comma-separated list of server
+ methods that the proxy should support, or * if all methods
+ should be enabled. The proxy SHOULD ignore methods that it
+ doesn't recognize.
+ Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista,balrog
The transport proxy replies by writing NL-terminated lines to
- stdout. The metaformat is
+ stdout. The line metaformat is
- Keyword OptArgs NL
- OptArgs = Args |
- Args = SP ArgChar | Args ArgChar
- ArgChar = Any character but NUL or NL
- Keyword = KeywordChar | Keyword KeywordChar
- KeyWordChar = All alphanumeric characters, dash, and underscore.
+ <Line> ::= <Keyword> <OptArgs> <NL>
+ <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
+ <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
+ <OptArgs> ::= <Args>*
+ <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
+ <ArgChar> ::= <any US-ASCII character but NUL or NL>
+ <SP> ::= <US-ASCII whitespace symbol (32)>
+ <NL> ::= <US-ASCII newline (line feed) character (10)>
Tor MUST ignore lines with keywords that it doesn't recognize.
-
- First, the proxy writes "VERSION 1" to say that it supports this
- protocol. It must either pick a version that Tor told it about, or
- pick no version at all, say "ERROR no-version\n", and exit.
+
+ First, if there's an error parsing the environment variables, the
+ proxy should write:
+ ENV-ERROR <errormessage>
+ and exit.
+
+ If the environment variables were correctly formatted, the proxy
+ should write:
+ VERSION <configuration protocol version>
+ to say that it supports this configuration protocol version (example
+ "VERSION 1"). It must either pick a version that Tor told it about
+ in TOR_PT_MANAGED_TRANSPORT_VER, or pick no version at all, say:
+ VERSION-ERROR no-version
+ and exit.
The proxy should then open its ports. If running as a client
proxy, it should not use fixed ports; instead it should autoselect
@@ -326,12 +346,12 @@ Managed proxy interface
made available and how. It does this by printing zero or more
CMETHOD and SMETHOD lines to its stdout. These lines look like:
- CMETHOD methodname SOCKS4/SOCKS5 address:port [ARGS=arglist] \
+ CMETHOD <methodname> socks4/socks5 <address:port> [ARGS=arglist] \
[OPT-ARGS=arglist]
as in
- CMETHOD trebuchet SOCKS5 127.0.0.1:19999 ARGS=rocks,height \
+ CMETHOD trebuchet socks5 127.0.0.1:19999 ARGS=rocks,height \
OPT-ARGS=tensile-strength
The ARGS field lists mandatory parameters that must appear in
@@ -344,16 +364,18 @@ Managed proxy interface
finished telling Tor about the client methods it provides. If it
tries to supply a client method but can't for some reason, it
should say:
- CMETHOD-ERROR methodname "Message"
+ CMETHOD-ERROR <methodname> <errormessage>
A proxy should also tell Tor about the server methods it is providing
by printing zero or more SMETHOD lines. These lines look like:
- SMETHOD methodname address:port [Options]
+ SMETHOD <methodname> <address:port> [options]
If there's an error setting up a configured server method, the
proxy should say:
- SMETHOD-ERROR methodname "message"
+ SMETHOD-ERROR <methodname> <errormessage>
+ as in
+ SMETHOD-ERROR no support for the 'trebuchet' method
The 'address:port' part of an SMETHOD line is the address to put
in the bridge line. The Options part is a list of space-separated
@@ -404,6 +426,12 @@ Managed proxy interface
closed. Proxies should respond to a second INT signal by shutting
down cleanly.
+ The managed proxy configuration protocol version defined in this
+ section is "1".
+ So, for example, if tor supports this configuration protocol it
+ should set the environment variable:
+ TOR_PT_MANAGED_TRANSPORT_VER=1
+
The extended ORPort protocol
Server transports may need to connect to the bridge and pass
@@ -417,7 +445,7 @@ The extended ORPort protocol
COMMAND [2 bytes, big-endian]
BODYLEN [2 bytes, big-endian]
- BODY [Bodylen bytes]
+ BODY [BODYLEN bytes]
Commands sent from the transport to the server are:
@@ -442,7 +470,7 @@ Advertising bridge methods
Bridges put the 'method' lines in their extra-info documents.
- method SP methodname SP address:port [SP arglist] NL
+ method SP <methodname> SP <address:port> [SP arglist] NL
The address:port are as returned from an SMETHOD line (unless they are
replaced by the FORWARD: directive). The arglist is a K=V,... list as
@@ -451,7 +479,7 @@ Advertising bridge methods
If the SMETHOD line includes a DECLARE: part, the router descriptor gets
a new line:
- method-info SP methodname [SP arglist] NL
+ method-info SP <methodname> [SP arglist] NL
Bridge authority behavior
More information about the tor-commits
mailing list