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

docs: more server/introducer setup text

Browse Source 
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
This commit is contained in:
Brian Warner 2016-09-14 13:05:48 -07:00
parent 8a4dc213f9
commit d69757e069
2 changed files with 90 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/running.rst
View File

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

82
docs/servers.rst
View File

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