From d69757e0695154946ea87f680290a864d22b7205 Mon Sep 17 00:00:00 2001 From: Brian Warner Date: Wed, 14 Sep 2016 13:05:48 -0700 Subject: [PATCH] docs: more server/introducer setup text running.rst: split out the server/introducer text, so someone who only care about running a client doesn't need to read about hostnames or --port/--location. servers.rst: more background text on ports and locations, make section names less storage-centric --- docs/running.rst | 41 +++++++++++++++++------- docs/servers.rst | 82 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 90 insertions(+), 33 deletions(-) diff --git a/docs/running.rst b/docs/running.rst index db3bc72f0..d8a6fef24 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -26,6 +26,9 @@ grid`_ as you only need to create a client node. When you want to create your own grid you'll need to create the introducer and several initial storage nodes (see the note about small grids below). +Running a Client +---------------- + To construct a client node, run “``tahoe create-client``”, which will create ``~/.tahoe`` to be the node's base directory. Acquire the ``introducer.furl`` (see below if you are running your own introducer, or use the one from the @@ -39,23 +42,39 @@ By default, “``tahoe create-client``” creates a client-only node, that does not offer its disk space to other nodes. To configure other behavior, use “``tahoe create-node``” or see :doc:`configuration`. -To construct an introducer, create a new base directory for it (the -name of the directory is up to you), ``cd`` into it, and run -“``tahoe create-introducer .``”. Now run the introducer using -“``tahoe start .``”. After it starts, it will write a file named -``introducer.furl`` into the ``private/`` subdirectory of that base -directory. This file contains the URL the other nodes must use in order -to connect to this introducer. (Note that “``tahoe run .``” doesn't -work for introducers, this is a known issue: `#937`_.) - The “``tahoe run``” command above will run the node in the foreground. On Unix, you can run it in the background instead by using the “``tahoe start``” command. To stop a node started in this way, use “``tahoe stop``”. ``tahoe --help`` gives a summary of all commands. +Running a Server or Introducer +------------------------------ + +To build either a storage server node, or an introducer node, you'll need +a way for clients to connect to it. The simplest case is when the +computer is on the public internet (e.g. a "VPS" virtual private server, +with a public IP address and a DNS hostname like ``example.net``). See +:doc:`servers` for help with more complex scenarios, using the ``--port`` +and ``--location`` arguments. + +To construct an introducer, create a new base directory for it (the name +of the directory is up to you), ``cd`` into it, and run “``tahoe +create-introducer --hostname=example.net .``” (but using the hostname of +your VPS). Now run the introducer using “``tahoe start .``”. After it +starts, it will write a file named ``introducer.furl`` into the +``private/`` subdirectory of that base directory. This file contains the +URL the other nodes must use in order to connect to this introducer. +(Note that “``tahoe run .``” doesn't work for introducers, this is a +known issue: `#937`_.) + +Storage servers are created the same way: ``tahoe create-node +--hostname=HOSTNAME .`` from a new directory. You'll need to provide the +introducer FURL (either as a ``--introducer=`` argument, or by editing +the ``tahoe.cfg`` configuration file afterwards) to connect to the +introducer of your choice. + See :doc:`configuration` for more details about how to configure -Tahoe-LAFS, including how to get other clients to connect to your node if -it is behind a firewall or NAT device. +Tahoe-LAFS. .. _public test grid: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid .. _TestGrid page: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid diff --git a/docs/servers.rst b/docs/servers.rst index 927a19ac4..541514e12 100644 --- a/docs/servers.rst +++ b/docs/servers.rst @@ -1,31 +1,68 @@ -.. -*- coding: utf-8-with-signature -*- +========================= +How To Configure A Server +========================= -================================================================== -Configuring a Tahoe-LAFS server node for various network scenarios -================================================================== +Many Tahoe-LAFS nodes run as "servers", meaning they provide services for +other machines (i.e. "clients"). The two most important kinds are the +Introducer, and Storage Servers. -#. `Storage node has a public DNS name`_ -#. `Storage node has a public IPv4/IPv6 address`_ -#. `Storage node is behind a firewall with port forwarding`_ +To be useful, servers must be reachable by clients. Tahoe servers can listen +on TCP ports, and advertise their "location" (hostname and TCP port number) +so clients can connect to them. They can also listen on Tor "onion services" +and I2P ports. + +Storage servers advertise their location by announcing it to the Introducer, +which then broadcasts the location to all clients. So once the location is +determined, you don't need to do anything special to deliver it. + +The Introducer itself has a location, which must be manually delivered to all +storage servers and clients. You might email it to the new members of your +grid. This location (along with other important cryptographic identifiers) is +written into a file named ``private/introducer.furl`` in the Introducer's +base directory, and should be provided as the ``--introducer=`` argument to +``tahoe create-client`` or ``tahoe create-node``. + +The first step when setting up a server is to figure out how clients will +reach it. Then you need to configure the server to listen on some ports, and +then configure the location properly. + +The following are some suggested scenarios for configuring 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`. + +#. `Server has a public DNS name`_ +#. `Server has a public IPv4/IPv6 address`_ +#. `Server is behind a firewall with port forwarding`_ #. `Using I2P/Tor to Avoid Port-Forwarding`_ -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` +Server has a public DNS name +============================ +The simplest case is where your server host is directly connected to the +internet, without a firewall or NAT box in the way. Most VPS (Virtual Private +Server) and colocated servers are like this, although some providers block +many inbound ports by default. -Storage node has a public DNS name -================================== +For these servers, all you need to know is the external hostname. The system +administrator will tell you this. The main requirement is that this hostname +can be looked up in DNS, and it will map to an IPv4 or IPv6 address which +will reach the machine. -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:: +If your hostname is ``example.net``, then you'll create the introducer like +this:: + + tahoe create-introducer --hostname example.com ~/introducer + +or a storage server like:: tahoe create-node --hostname=example.net +These will allocate a TCP port (e.g. 12345), assign ``tub.port`` to be +``tcp:12345``, and ``tub.location`` will be ``tcp:example.com:12345``. + 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 @@ -34,8 +71,8 @@ support for IPv6 is new, and may still have problems. Please see ticket .. _#867: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/867 -Storage node has a public IPv4/IPv6 address -=========================================== +Server 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 @@ -75,8 +112,8 @@ 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 -====================================================== +Server is behind a firewall with port forwarding +================================================ To configure a storage node behind a firewall with port forwarding you will need to know: @@ -106,7 +143,8 @@ 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:: +penetration without port-forwarding, hostnames, or IP addresses. So setting +up a server that listens only on Tor is simple:: tahoe create-node --listen=tor