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

@@ -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
+Tahoe-LAFS.
-it is behind a firewall or NAT device.
 
 .. _public test grid: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid
 .. _TestGrid page: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid

docs/servers.rst

@@ -1,31 +1,68 @@
-.. -*- coding: utf-8-with-signature -*-
+=========================
+How To Configure A Server
+=========================
 
-==================================================================
+Many Tahoe-LAFS nodes run as "servers", meaning they provide services for
-Configuring a Tahoe-LAFS server node for various network scenarios
+other machines (i.e. "clients"). The two most important kinds are the
-==================================================================
+Introducer, and Storage Servers.
 
-#.  `Storage node has a public DNS name`_
+To be useful, servers must be reachable by clients. Tahoe servers can listen
-#.  `Storage node has a public IPv4/IPv6 address`_
+on TCP ports, and advertise their "location" (hostname and TCP port number)
-#.  `Storage node is behind a firewall with port forwarding`_
+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
+Server has a public DNS name
-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`
 
+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
+If your hostname is ``example.net``, then you'll create the introducer like
-there is a valid DNS "A" record that points to it (e.g. ``example.net``). In
+this::
-this case, just do::
+
+  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