From f3fafa227070cd8dd409f8f1f30e19c929e5fcd5 Mon Sep 17 00:00:00 2001 From: David Stainton Date: Tue, 13 Sep 2016 14:00:26 +0000 Subject: [PATCH 1/2] Add server-side network considerations to servers.rst This includes configuring servers to use IPv4, IPv6, IPv6 with port forwarding firewall and suggesting the use of i2p/tor if NAT penetration is needed: provided links to configuration and anonymity-configuration --- docs/servers.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/servers.rst diff --git a/docs/servers.rst b/docs/servers.rst new file mode 100644 index 000000000..9d75fe9e9 --- /dev/null +++ b/docs/servers.rst @@ -0,0 +1,82 @@ + +.. -*- 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`_ + + +The following are some suggested scenarios for configuring storage +servers using various network transports. These examples do not +include specifying an introducer FURL which normally you would want +when provisioning storage nodes. For these and other configuration +details please refer to :doc:`configuration` + + +storage node has a public IPv4 address +====================================== + +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:: + + tahoe create-node --hostname=example.net + + +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 + + +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:: + + * 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 + +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:: + + tahoe create-node --location=tcp:10.10.10.10:3456 --port=tcp:interface=192.168.1.5:3456 + +If however the port forwarding forwards external port 6656 to 3456 +internally, then like this:: + + tahoe create-node --location=tcp:10.10.10.10:6656 --port=tcp:interface=192.168.1.5:3456 + + +storage node is behind a partial-cone NAT device +================================================ + +I2p and Tor onion services among other great properties also provide +NAT penetration:: + + tahoe create-node --listen=tor + +For more information about using Tahoe-LAFS with I2p and Tor see +:doc:`anonymity-configuration` From 460cc826fda1d8f86fffd614e902ae94fb6e7b78 Mon Sep 17 00:00:00 2001 From: Brian Warner Date: Wed, 14 Sep 2016 12:37:40 -0700 Subject: [PATCH 2/2] update docs * 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 --- docs/index.rst | 1 + docs/servers.rst | 126 +++++++++++++++++++++++++++++------------------ 2 files changed, 80 insertions(+), 47 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 29decd973..ed160b221 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,7 @@ Contents: known_issues + servers helper convergence-secret garbage-collection diff --git a/docs/servers.rst b/docs/servers.rst index 9d75fe9e9..927a19ac4 100644 --- a/docs/servers.rst +++ b/docs/servers.rst @@ -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