tahoe-lafs/tahoe-lafs
tahoe-lafs
/
tahoe-lafs
2
0
Fork 0
Code Issues Pull Requests 23 Packages Projects Releases 1 Wiki Activity

update config docs, add NEWS snippet

This commit is contained in:
Brian Warner 2016-04-26 22:26:31 -07:00
parent 96c625920c
commit 25b64041cc
2 changed files with 75 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
docs/configuration.rst
View File

@ -137,86 +137,96 @@ set the ``tub.location`` option described below.
``http://127.0.0.1:3456/static/foo.html`` will serve the contents of ``http://127.0.0.1:3456/static/foo.html`` will serve the contents of
``BASEDIR/public_html/foo.html`` . ``BASEDIR/public_html/foo.html`` .
``tub.port = (endpoints specification string, optional)`` ``tub.port = (endpoint specification string, optional)``
This controls the node's "listening port", through which it accepts This controls which port the node uses to accept Foolscap connections
Foolscap connections from other nodes. If not provided, the node will ask from other nodes. It is parsed as a Twisted "server endpoint descriptor",
the kernel to allocate an available port, then saves it to a file (named which accepts values like ``tcp:12345`` and
``client.port`` or ``introducer.port``), so that subsequent runs will ``tcp:23456:interface=127.0.0.1``.
re-use the same port. The value should be ``tcp:`` followed by a port
number, e.g. ``tcp:3457``.
Note that the node can advertise an entirely different host+port (with For backwards compatibility, if this contains a simple integer, it will
``tub.location``, below) than the port that it listens on (controlled by be used as a TCP port number, like ``tcp:%d`` (which will accept
``tub.port``). This is most useful when the node is a storage server and connections on all interfaces). However ``tub.port`` cannot be ``0`` or
lives behind a firewall that has been configured to forward a TCP port. ``tcp:0`` (older versions accepted this, but the node is no longer
``tub.location`` would be set to ``tcp:ADDR1:PORT1`` (where ADDR1 is the willing to ask Twisted to allocate port numbers in this way). To
external hostname or IP address of the firewall box, and PORT1 is the automatically allocate a TCP port, leave ``tub.port`` blank.
externally-visible port), while ``tub.port`` would be ``tcp:PORT2``
(where the firewall is forwarding external PORT1 to internal PORT2).
``tub.port`` cannot be ``tcp:0`` or ``0``: older versions accepted this, If the ``tub.port`` config key is not provided, the node will look in
but the node is no longer willing to ask Twisted to allocate port numbers ``BASEDIR/client.port`` (or ``BASEDIR/introducer.port``, for introducers)
in this way. For backwards compatibility, a ``tub.port`` that is an for the descriptor that was used last time.
integer (other than 0) will be given a ``tcp:`` prefix.
If neither is available, the node will ask the kernel for any available
port (the moral equivalent of ``tcp:0``). The allocated port number will
be written into a descriptor string in ``BASEDIR/client.port`` (or
``introducer.port``), so that subsequent runs will re-use the same port.
``tub.location = (string, optional)`` ``tub.location = (string, optional)``
In addition to running as a client, each Tahoe-LAFS node also runs as a In addition to running as a client, each Tahoe-LAFS node can also run as
server, listening for connections from other Tahoe-LAFS clients. The node a server, listening for connections from other Tahoe-LAFS clients. The
announces its location by publishing a "FURL" (a string with some node announces its location by publishing a "FURL" (a string with some
connection hints) to the Introducer. The string it publishes can be found connection hints) to the Introducer. The string it publishes can be found
in ``BASEDIR/private/storage.furl`` . The ``tub.location`` configuration in ``BASEDIR/private/storage.furl`` . The ``tub.location`` configuration
controls what location is published in this announcement. controls what location is published in this announcement.
If your node is meant to run as a server, you should fill this in, using
a hostname or IP address that is reachable from your intended clients.
If you don't provide ``tub.location``, the node will try to figure out a If you don't provide ``tub.location``, the node will try to figure out a
useful one by itself, by using tools like "``ifconfig``" to determine the useful one by itself, by using tools like "``ifconfig``" to determine the
set of IP addresses on which it can be reached from nodes both near and set of IP addresses on which it can be reached from nodes both near and
far. It will also include the TCP port number on which it is listening far. It will also include the TCP port number on which it is listening
(either the one specified by ``tub.port``, or whichever port was assigned (either the one specified by ``tub.port``, or whichever port was assigned
by the kernel when ``tub.port`` is left unspecified). by the kernel when ``tub.port`` is left unspecified). However this
automatic address-detection is discouraged, and will probably be removed
from a future release. It will include the ``127.0.0.1`` "localhost"
address (which is only useful to clients running on the same computer),
and RFC1918 private-network addresses like ``10.*.*.*`` and
``192.168.*.*`` (which are only useful to clients on the local LAN). In
general, the automatically-detected IP addresses will only be useful if
the node has a public IP address, such as a VPS or colo-hosted server.
You might want to override this value if your node lives behind a You will certainly need to set ``tub.location`` if your node lives behind
firewall that is doing inbound port forwarding, or if you are using other a firewall that is doing inbound port forwarding, or if you are using
proxies such that the local IP address or port number is not the same one other proxies such that the local IP address or port number is not the
that remote clients should use to connect. You might also want to control same one that remote clients should use to connect. You might also want
this when using a Tor proxy to avoid revealing your actual IP address to control this when using a Tor proxy to avoid revealing your actual IP
through the Introducer announcement. address through the Introducer announcement.
If ``tub.location`` is specified, by default it entirely replaces the If ``tub.location`` is specified, by default it entirely replaces the
automatically determined set of IP addresses. To include the automatically automatically determined set of IP addresses. To include the automatically
determined addresses as well as the specified ones, include the uppercase determined addresses as well as the specified ones, include the uppercase
string "``AUTO``" in the list. string "``AUTO``" in the list.
The value is a comma-separated string of host:port location hints, like The value is a comma-separated string of method:host:port location hints,
this:: like this::
123.45.67.89:8098,tahoe.example.com:8098,127.0.0.1:8098 tcp:123.45.67.89:8098,tcp:tahoe.example.com:8098,tcp:127.0.0.1:8098
A few examples: A few examples:
* Emulate default behavior, assuming your host has IP address
123.45.67.89 and the kernel-allocated port number was 8098::
tub.port = 8098
tub.location = 123.45.67.89:8098,127.0.0.1:8098
* Use a DNS name so you can change the IP address more easily:: * Use a DNS name so you can change the IP address more easily::
tub.port = 8098 tub.port = tcp:8098
tub.location = tahoe.example.com:8098 tub.location = tcp:tahoe.example.com:8098
* Run a node behind a firewall (which has an external IP address) that
has been configured to forward external port 7912 to our internal
node's port 8098::
tub.port = tcp:8098
tub.location = tcp:external-firewall.example.com:7912
* Emulate default behavior, assuming your host has public IP address of
123.45.67.89, and the kernel-allocated port number was 8098::
tub.port = tcp:8098
tub.location = tcp:123.45.67.89:8098,tcp:127.0.0.1:8098
* Use a DNS name but also include the default set of addresses:: * Use a DNS name but also include the default set of addresses::
tub.port = 8098 tub.port = tcp:8098
tub.location = tahoe.example.com:8098,AUTO tub.location = tcp:tahoe.example.com:8098,AUTO
* Run a node behind a firewall (which has an external IP address) that
has been configured to forward port 7912 to our internal node's port
8098::
tub.port = 8098
tub.location = external-firewall.example.com:7912
* Run a node behind a Tor proxy (perhaps via ``torsocks``), in * Run a node behind a Tor proxy (perhaps via ``torsocks``), in
client-only mode (i.e. we can make outbound connections, but other client-only mode (i.e. we can make outbound connections, but other
@ -225,8 +235,8 @@ set the ``tub.location`` option described below.
reminder to human observers that this node cannot be reached. "Don't reminder to human observers that this node cannot be reached. "Don't
call us.. we'll call you":: call us.. we'll call you"::
tub.port = 8098 tub.port = tcp:8098
tub.location = unreachable.example.org:0 tub.location = tcp:unreachable.example.org:0
* Run a node behind a Tor proxy, and make the server available as a Tor * Run a node behind a Tor proxy, and make the server available as a Tor
"hidden service". (This assumes that other clients are running their "hidden service". (This assumes that other clients are running their
@ -242,10 +252,8 @@ set the ``tub.location`` option described below.
``/var/lib/tor/hidden_services/tahoe/hostname``. Then set up your ``/var/lib/tor/hidden_services/tahoe/hostname``. Then set up your
``tahoe.cfg`` like:: ``tahoe.cfg`` like::
tub.port = 8098 tub.port = tcp:8098
tub.location = ualhejtq2p7ohfbb.onion:29212 tub.location = tor:ualhejtq2p7ohfbb.onion:29212
Most users will not need to set ``tub.location``.
``log_gatherer.furl = (FURL, optional)`` ``log_gatherer.furl = (FURL, optional)``

11
topfiles/2491.config
View File

@ -12,3 +12,14 @@
user allows NODEDIR/client.port to be written, then later modifies user allows NODEDIR/client.port to be written, then later modifies
tahoe.cfg to set "tub.port" to a different value, this difference will tahoe.cfg to set "tub.port" to a different value, this difference will
persist (and the node will honor tahoe.cfg "tub.port" exclusively). persist (and the node will honor tahoe.cfg "tub.port" exclusively).
* We now encourage static allocation of tub.port, and pre-configuration of
the node's externally-reachable IP address or hostname (by setting
tub.location). Automatic IP-address detection is deprecated. Automatic port
allocation is merely discouraged. Eventually both will be managed by "tahoe
create-node", but for now we recommend users edit their tahoe.cfg after
node creation and before first launch.
* "tahoe start" now creates the Tub, and all primary software components,
before the child process daemonizes. Many configuration errors which would
previously have been reported in a logfile (after node startup), will now
be signalled immediately, via stderr. In these cases, the "tahoe start"
process will exit with a non-zero return code.