Documentation for Magic Folder.

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

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 26d8c58bb92c280322440898ece65184e9492a57..e632075e7ebd75d1d46cc6c03a842763a306b77b 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`_
@@ -68,7 +68,7 @@ Client/server nodes provide one or more of the following services:
 * web-API service
 * SFTP service
 * FTP service
-* drop-upload service
+* Magic Folder service
 * helper service
 * storage service.
 
@@ -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
 ======================
 
@@ -418,16 +453,16 @@ SFTP, FTP
     instructions on configuring these services, and the ``[sftpd]`` and
     ``[ftpd]`` sections of ``tahoe.cfg``.
 
-Drop-Upload
+Magic Folder
 
-    As of Tahoe-LAFS v1.9.0, a node running on Linux can be configured to
-    automatically upload files that are created or changed in a specified
-    local directory. See drop-upload.rst_ for details.
+    A node running on Linux or Windows can be configured to automatically
+    upload files that are created or changed in a specified local directory.
+    See `magic-folder.rst`_ for details.
 
 .. _download-status.rst: frontends/download-status.rst
 .. _CLI.rst: frontends/CLI.rst
 .. _FTP-and-SFTP.rst: frontends/FTP-and-SFTP.rst
-.. _drop-upload.rst: frontends/drop-upload.rst
+.. _magic-folder.rst: frontends/magic-folder.rst
 
 
 Storage Server Configuration