new feature: preferred storage servers

[tahoe-lafs/tahoe-lafs.git] / docs / configuration.rst

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 26d8c58bb92c280322440898ece65184e9492a57..f9179376a02c2ec9fa375e1b66f1f86d506accbd 100644 (file)
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -4,7 +4,7 @@
 Configuring a Tahoe-LAFS node
 =============================
 
-1.   `Node Types`_
+1.  `Node Types`_
 2.  `Overall Node Configuration`_
 3.  `Client Configuration`_
 4.  `Storage Server Configuration`_
@@ -159,6 +159,11 @@ set the ``tub.location`` option described below.
     this when using a Tor proxy to avoid revealing your actual IP address
     through the Introducer announcement.
 
+    If ``tub.location`` is specified, by default it entirely replaces the
+    automatically determined set of IP addresses. To include the automatically
+    determined addresses as well as the specified ones, include the uppercase
+    string "``AUTO``" in the list.
+
     The value is a comma-separated string of host:port location hints, like
     this::
 
@@ -177,6 +182,11 @@ set the ``tub.location`` option described below.
         tub.port = 8098
         tub.location = tahoe.example.com:8098
 
+    * Use a DNS name but also include the default set of addresses::
+
+        tub.port = 8098
+        tub.location = tahoe.example.com:8098,AUTO
+
     * Run a node behind a firewall (which has an external IP address) that
       has been configured to forward port 7912 to our internal node's port
       8098::
@@ -386,6 +396,31 @@ Client Configuration
 .. _performance.rst: performance.rst
 .. _mutable.rst: specifications/mutable.rst
 
+``peers.preferred = (string, optional)``
+
+    This is an optional comma-separated list of Node IDs of servers that will
+    be tried first when selecting storage servers for reading or writing.
+
+    Servers should be identified here by their Node ID as it appears in the web
+    ui, underneath the server's nickname. For storage servers running tahoe
+    versions >=1.10 (if the introducer is also running tahoe >=1.10) this will
+    be a "Node Key" (which is prefixed with 'v0-'). For older nodes, it will be
+    a TubID instead. When a preferred server (and/or the introducer) is
+    upgraded to 1.10 or later, clients must adjust their configs accordingly.
+
+    Every node selected for upload, whether preferred or not, will still
+    receive the same number of shares (one, if there are ``N`` or more servers
+    accepting uploads). Preferred nodes are simply moved to the front of the
+    server selection lists computed for each file.
+
+    This is useful if a subset of your nodes have different availability or
+    connectivity characteristics than the rest of the grid. For instance, if
+    there are more than ``N`` servers on the grid, and ``K`` or more of them
+    are at a single physical location, it would make sense for clients at that
+    location to prefer their local servers so that they can maintain access to
+    all of their uploads without using the internet.
+
+
 Frontend Configuration
 ======================