diff --git a/docs/configuration.rst b/docs/configuration.rst index 7a9189797..034f31df0 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -6,15 +6,16 @@ Configuring a Tahoe-LAFS node 1. `Node Types`_ 2. `Overall Node Configuration`_ -3. `Client Configuration`_ -4. `Storage Server Configuration`_ -5. `Frontend Configuration`_ -6. `Running A Helper`_ -7. `Running An Introducer`_ -8. `Other Files in BASEDIR`_ -9. `Static Server Definitions`_ -10. `Other files`_ -11. `Example`_ +3. `Connection Management`_ +4. `Client Configuration`_ +5. `Storage Server Configuration`_ +6. `Frontend Configuration`_ +7. `Running A Helper`_ +8. `Running An Introducer`_ +9. `Other Files in BASEDIR`_ +10. `Static Server Definitions`_ +11. `Other files`_ +12. `Example`_ A Tahoe-LAFS node is configured by writing to files in its base directory. These files are read by the node when it starts, so each time you change @@ -317,6 +318,183 @@ set the ``tub.location`` option described below. string will be interpreted relative to the node's base directory. +Connection Management +===================== + +Three sections (``[tor]``, ``[i2p]``, and ``[connections]``) control how the +Tahoe node makes outbound connections. Tor and I2P are configured here. This +also controls when Tor and I2P are used: for all TCP connections (to hide +your IP address), or only when necessary (just for servers which declare that +they need Tor, because they use ``.onion`` addresses). + +``[connections]`` +----------------- + +This section controls *when* Tor and I2P are used. The ``[tor]`` and +``[i2p]`` sections (described later) control *how* Tor/I2P connections are +managed. + +All Tahoe nodes need to make a connection to the Introducer; the ``[node] +introducer.furl`` setting (described below) indicates where the Introducer +lives. Tahoe client nodes must also make connections to storage servers: +these targets are specified in announcements that come from the Introducer. +Both are expressed as FURLs (a Foolscap URL), which include a list of +"connection hints". Each connection hint describes one (of perhaps many) +network endpoints where the service might live. + +Connection hints include a type, and look like: + +* ``tcp:tahoe.example.org:12345`` +* ``tor:u33m4y7klhz3b.onion:1000`` +* ``i2p:c2ng2pbrmxmlwpijn`` + +``tor`` hints are always handled by the ``tor`` handler (configured in the +``[tor]`` section, described below). Likewise, ``i2p`` hints are always +routed to the ``i2p`` handler. But either will be ignored if Tahoe was not +installed with the necessary Tor/I2P support libraries, or if the Tor/I2P +daemon is unreachable. + +The ``[connections]`` section lets you control how ``tcp`` hints are handled. +By default, they use the normal TCP handler, which just makes direct +connections (revealing your node's IP address to both the target server and +the intermediate network). The node behaves this way if the ``[connections]`` +section is missing entirely, or if it looks like this:: + + [connections] + tcp = tcp + +To hide the Tahoe node's IP address from the servers that it uses, set the +``[connections]`` section to use Tor for TCP hints:: + + [connections] + tcp = tor + +(Note that I2P does not support connections to normal TCP ports, so +``[connections] tcp = i2p`` is invalid) + +In the future, Tahoe services may be changed to live on HTTP/HTTPS URLs +instead of Foolscap. In that case, connections will be made using whatever +handler is configured for ``tcp`` hints. So the same ``tcp = tor`` +configuration will work. + +``[tor]`` +--------- + +This controls how Tor connections are made. The defaults (all empty) mean +that, when Tor is needed, the node will try to connect to a Tor daemon's +SOCKS proxy on localhost port 9050 or 9150. Port 9050 is the default Tor +SOCKS port, so it should be available under any system Tor instance (e.g. the +one launched at boot time when the standard Debian ``tor`` package is +installed). Port 9150 is the SOCKS port for the Tor Browser Bundle, so it +will be available any time the TBB is running. + +You can set ``launch = True`` to cause the Tahoe node to launch a new Tor +daemon when it starts up (and kill it at shutdown), if you don't have a +system-wide instance available. Note that it takes 30-60 seconds for Tor to +get running, so using a long-running Tor process may enable a faster startup. +If your Tor executable doesn't live on ``$PATH``, use ``tor.executable=`` to +specify it. + +``[tor]`` + +``enable = (boolean, optional, defaults to True)`` + + If False, this will disable the use of Tor entirely. The default of True + means the node will use Tor, if necessary, and if possible. + +``socks.port = (string, optional, PORT, defaults to empty)`` + + This tells the node that Tor connections should be routed to a SOCKS + proxy listening on the given port. The default (of an empty value) will + cause the node to first try localhost port 9050, then if that fails, try + localhost port 9150. These are the default listening ports of the + standard Tor daemon, and the Tor Browser Bundle, respectively. + +``control.port = (string, optional, endpoint specification string)`` + + This tells the node to connect to a pre-existing Tor daemon on the given + control port (which is typically ``unix://var/run/tor/control`` or + ``tcp:localhost:9051``). The node will then ask Tor what SOCKS port it is + using, and route Tor connections to that. + +``launch = (bool, optional, defaults to False)`` + + If True, the node will spawn a new (private) copy of Tor at startup, and + will kill it at shutdown. The new Tor will be given a persistent state + directory under ``NODEDIR/private/``, where Tor's microdescriptors will + be cached, to speed up subsequent startup. + +``tor.executable = (string, optional, defaults to empty)`` + + This controls which Tor executable is used when ``launch = True``. If + empty, the first executable program named ``tor`` found on ``$PATH`` will + be used. + +There are 5 valid combinations of these configuration settings: + +* 1: ``(empty)``: use SOCKS on port 9050/9150 +* 2: ``launch = true``: launch a new Tor +* 3: ``socks.port = HOST:PORT``: use an existing Tor on the given SOCKS port +* 4: ``control.port = PORT``: use an existing Tor at the given control port +* 5: ``enable = false``: no Tor at all + +1 is the default, and should work for any Linux host with the system Tor +package installed. 2 should work on any box with Tor installed into $PATH, +but will take an extra 30-60 seconds at startup. 3 and 4 can be used for +specialized installations, where Tor is already running, but not listening on +the default port. 5 should be used in environments where Tor is installed, +but should not be used (perhaps due to a site-wide policy). + +Note that Tor support depends upon some additional Python libraries. To +install Tahoe with Tor support, use ``pip install tahoe-lafs[tor]``. + +``[i2p]`` +--------- + +This controls how I2P connections are made. Like with Tor, the all-empty +defaults will cause I2P connections to be routed to a pre-existing I2P daemon +on port 7656. This is the default SAM port for the ``i2p`` daemon. + + +``[i2p]`` + +``enable = (boolean, optional, defaults to True)`` + + If False, this will disable the use of I2P entirely. The default of True + means the node will use I2P, if necessary, and if possible. + +``sam.port = (string, optional, endpoint descriptor, defaults to empty)`` + + This tells the node that I2P connections should be made via the SAM + protocol on the given port. The default (of an empty value) will cause + the node to try localhost port 7656. This is the default listening port + of the standard I2P daemon. + +``launch = (bool, optional, defaults to False)`` + + If True, the node will spawn a new (private) copy of I2P at startup, and + will kill it at shutdown. The new I2P will be given a persistent state + directory under ``NODEDIR/private/``, where I2P's microdescriptors will + be cached, to speed up subsequent startup. The daemon will allocate its + own SAM port, which will be queried from the config directory. + +``i2p.configdir = (string, optional, directory)`` + + This tells the node to parse an I2P config file in the given directory, + and use the SAM port it finds there. If ``launch = True``, the new I2P + daemon will be told to use the given directory (which can be + pre-populated with a suitable config file). If ``launch = False``, we + assume there is a pre-running I2P daemon running from this directory, and + can again parse the config file for the SAM port. + +``i2p.executable = (string, optional, defaults to empty)`` + + This controls which I2P executable is used when ``launch = True``. If + empty, the first executable program named ``i2p`` found on ``$PATH`` will + be used. + + + Client Configuration ==================== @@ -569,6 +747,8 @@ Other Files in BASEDIR Some configuration is not kept in ``tahoe.cfg``, for the following reasons: +* it doesn't fit into the INI format of ``tahoe.cfg`` (e.g. + ``private/servers.yaml``) * it is generated by the node at startup, e.g. encryption keys. The node never writes to ``tahoe.cfg``. * it is generated by user action, e.g. the "``tahoe create-alias``" command. @@ -740,6 +920,38 @@ Or, if you're feeling really lazy:: .. _YAML: http://yaml.org/ +Overriding Connection-Handlers for Static Servers +------------------------------------------------- + +A ``connections`` entry will override the default connection-handler mapping +(as established by ``tahoe.cfg [connections]``). This can be used to build a +"Tor-mostly client": one which is restricted to use Tor for all connections, +except for a few private servers to which normal TCP connections will be +made. To override the published announcement (and thus avoid connecting twice +to the same server), the server ID must exactly match. + +``tahoe.cfg``:: + + [connections] + # this forces the use of Tor for all "tcp" hints + tcp = tor + +``private/servers.yaml``:: + + storage: + v0-c2ng2pbrmxmlwpijn3mr72ckk5fmzk6uxf6nhowyosaubrt6y5mq: + ann: + nickname: my-server-1 + anonymous-storage-FURL: pb://u33m4y7klhz3bypswqkozwetvabelhxt@tcp:10.1.2.3:51298/eiu2i7p6d6mm4ihmss7ieou5hac3wn6b + connections: + # this overrides the tcp=tor from tahoe.cfg, for just this server + tcp: tcp + +The ``connections`` table is needed to override the ``tcp = tor`` mapping +that comes from ``tahoe.cfg``. Without it, the client would attempt to use +Tor to connect to ``10.1.2.3``, which would fail because it is a +local/non-routeable (RFC1918) address. + Other files ===========