ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2024-12-21 13:57:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

document tor/i2p/connections

Browse Source
This commit is contained in:
Brian Warner 2016-08-27 13:16:28 -07:00
parent 30b421d48b
commit 2db38e0cf3
1 changed files with 221 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
docs/configuration.rst
View File

@ -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
===========