ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2025-01-29 15:43:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

update docs

Browse Source 
* replace sample IPv4/IPv6 addresses with reserved ones from RFC-6890
* remove initial blank line: prevents github from rendering the .rst
* emphasize --hostname, then have --port/--location as a special-case
* list --port first (describe it "from the inside out"), then --location
* explain difference between --port and --location
* in endpoint strings, put interface= at end, to emphasize port
* add servers.rst to index.rst so it'll show up on readthedocs
* don't mention "partial-cone NAT": that's only relevant if/when we get
  real ICE-style NAT-hole-punching
This commit is contained in:
Brian Warner 2016-09-14 12:37:40 -07:00
parent f3fafa2270
commit 460cc826fd
2 changed files with 80 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/index.rst
View File

@ -24,6 +24,7 @@ Contents:
known_issues
servers
helper
convergence-secret
garbage-collection

126
docs/servers.rst
View File

@ -1,14 +1,13 @@
.. -*- coding: utf-8-with-signature -*-
.. -*- coding: utf-8-with-signature -*-
==================================================================
Configuring a Tahoe-LAFS server node for various network scenarios
==================================================================
#. `storage node has a public IPv4 address`_
#. `storage node has a public IPv6 address`_
#. `storage node is behind a firewall with port forwarding`_
#. `storage node is behind a partial-cone NAT device`_
#. `Storage node has a public DNS name`_
#. `Storage node has a public IPv4/IPv6 address`_
#. `Storage node is behind a firewall with port forwarding`_
#. `Using I2P/Tor to Avoid Port-Forwarding`_
The following are some suggested scenarios for configuring storage
@ -18,63 +17,96 @@ when provisioning storage nodes. For these and other configuration
details please refer to :doc:`configuration`
storage node has a public IPv4 address
======================================
Storage node has a public DNS name
==================================
If for example your publicly routable IPv4 address is 10.10.10.10,
then you could use the following to create a storage node::
tahoe create-node --location=tcp:10.10.10.10:3456 --port=tcp:interface=10.10.10.10:3456
However if you have set a DNS A record for that IP address then the
simplest possible command to create the storage node would also choose
TCP port to listen on::
The simplest case is when your storage host has a public IPv4 address, and
there is a valid DNS "A" record that points to it (e.g. ``example.net``). In
this case, just do::
tahoe create-node --hostname=example.net
Ideally this should work for IPv6-capable hosts too (where the DNS name
provides an "AAAA" record, or both "A" and "AAAA"). However Tahoe-LAFS
support for IPv6 is new, and may still have problems. Please see ticket
`#867`_ for details.
storage node has a public IPv6 address
======================================
Create a storage node that listens on a public IPv6 address::
tahoe create-node --location=tcp:[2001:0DB8:f00e:eb00::1]:3456 --port=tcp:interface=2001\:0DB8\:f00e\:eb00\:\:1:3456
Create a storage node that listens on the IPv6 loopback::
tahoe create-node --location=tcp:[::1]:3456 --port=tcp:interface=\:\:1:3456
.. _#867: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/867
storage node is behind a firewall with port forwarding
Storage node has a public IPv4/IPv6 address
===========================================
If the host has a routeable (public) IPv4 address (e.g. ``203.0.113.1``), but
no DNS name, you will need to choose a TCP port (e.g. ``3457``), and use the
following::
tahoe create-node --port=tcp:3457 --location=tcp:203.0.113.1:3457
``--port`` is an "endpoint specification string" that controls which local
port the node listens on. ``--location`` is the "connection hint" that it
advertises to others, and describes the outbound connections that those
clients will make, so it needs to work from their location on the network.
Tahoe-LAFS nodes listen on all interfaces by default. When the host is
multi-homed, you might want to make the listening port bind to just one
specific interface by adding a ``interface=`` option to the ``--port=``
argument::
tahoe create-node --port=tcp:3457:interface=203.0.113.1 --location=tcp:203.0.113.1:3457
If the host's public address is IPv6 instead of IPv4, use square brackets to
wrap the address, and change the endpoint type to ``tcp6``::
tahoe create-node --port=tcp6:3457 --location=tcp:[2001:db8::1]:3457
You can use ``interface=`` to bind to a specific IPv6 interface too, however
you must backslash-escape the colons, because otherwise they are interpreted
as delimiters by the Twisted "endpoint" specification language. The
``--location=`` argument does not need colons to be escaped, because they are
wrapped by the square brackets::
tahoe create-node --port=tcp6:3457:interface=2001\:db8\:\:1 --location=tcp:[2001:db8::1]:3457
For IPv6-only hosts with AAAA DNS records, if the simple ``--hostname=``
configuration does not work, they can be told to listen specifically on an
IPv6-enabled port with this::
tahoe create-node --port=tcp6:3457 --location=tcp:example.net:3457
Storage node is behind a firewall with port forwarding
======================================================
To configure a storage node behind a firewall with port forwarding you
will need to know::
To configure a storage node behind a firewall with port forwarding you will
need to know:
* public IPv4 address of the router
* the TCP port that is available from outside your network
* internal IPv4 address of the storage node
* the TCP port that is the forwarding destination
* public IPv4 address of the router
* the TCP port that is available from outside your network
* the TCP port that is the forwarding destination
* internal IPv4 address of the storage node (the storage node itself is
unaware of this address, and it is not used during ``tahoe create-node``,
but the firewall must be configured to send connections to this)
The internal and external TCP port numbers could be the same or
different depending on how the port forwarding is configured. If for
example the public IPv4 address of the router is 10.10.10.10 and the
internal IPv4 address of the storage node is 192.168.1.5 then use a
cli command like this::
The internal and external TCP port numbers could be the same or different
depending on how the port forwarding is configured. If it is mapping ports
1-to-1, and the public IPv4 address of the firewall is 203.0.113.1 (and
perhaps the internal IPv4 address of the storage node is 192.168.1.5), then
use a CLI command like this::
tahoe create-node --location=tcp:10.10.10.10:3456 --port=tcp:interface=192.168.1.5:3456
tahoe create-node --port=tcp:3457 --location=tcp:203.0.113.1:3457
If however the port forwarding forwards external port 6656 to 3456
internally, then like this::
If however the firewall/NAT-box forwards external port *6656* to internal
port 3457, then do this::
tahoe create-node --location=tcp:10.10.10.10:6656 --port=tcp:interface=192.168.1.5:3456
tahoe create-node --port=tcp:3457 --location=tcp:203.0.113.1:6656
storage node is behind a partial-cone NAT device
================================================
I2p and Tor onion services among other great properties also provide
NAT penetration::
Using I2P/Tor to Avoid Port-Forwarding
======================================
I2P and Tor onion services, among other great properties, also provide NAT
penetration. So setting up a server that listens only on Tor is simple::
tahoe create-node --listen=tor