Minimal HTTPS documentation.

docs/architecture.rst

@@ -57,6 +57,20 @@ The key-value store is implemented by a grid of Tahoe-LAFS storage servers --
 user-space processes. Tahoe-LAFS storage clients communicate with the storage
 servers over TCP.
 
+There are two supported protocols:
+
+* Foolscap, the only supported protocol in release before v1.19.
+* HTTPS, new in v1.19.
+
+By default HTTPS is disabled (this will change in
+https://tahoe-lafs.org/trac/tahoe-lafs/ticket/4041). When HTTPS is enabled on
+the server, the server transparently listens for both Foolscap and HTTP on the
+same port. Clients can use either; by default they will only use Foolscap, but
+when configured appropriately they will use HTTPS when possible (this will
+change in https://tahoe-lafs.org/trac/tahoe-lafs/ticket/4041). At this time the
+only limitations of HTTPS is that I2P is not supported, so any usage of I2P only
+uses Foolscap.
+
 Storage servers hold data in the form of "shares". Shares are encoded pieces
 of files. There are a configurable number of shares for each file, 10 by
 default. Normally, each share is stored on a separate server, but in some

docs/configuration.rst

@@ -679,6 +679,14 @@ Client Configuration
     location to prefer their local servers so that they can maintain access to
     all of their uploads without using the internet.
 
+``force_foolscap = (boolean, optional)``
+
+    If this is ``True``, the client will only connect to storage servers via
+    Foolscap, regardless of whether they support HTTPS. If this is ``False``,
+    the client will prefer HTTPS when it is available on the server. The default
+    value is ``True`` (this will change in
+    https://tahoe-lafs.org/trac/tahoe-lafs/ticket/4041).
+
 In addition,
 see :doc:`accepting-donations` for a convention for donating to storage server operators.
 
@@ -796,6 +804,14 @@ Storage Server Configuration
     (i.e. ``BASEDIR/storage``), but it can be placed elsewhere. Relative paths
     will be interpreted relative to the node's base directory.
 
+``force_foolscap = (boolean, optional)``
+
+    If this is ``True``, the node will expose the storage server via Foolscap
+    only, with no support for HTTPS. If this is ``False``, the server will
+    support both Foolscap and HTTPS on the same port. The default value is
+    ``True`` (this will change in
+    https://tahoe-lafs.org/trac/tahoe-lafs/ticket/4041).
+
 In addition,
 see :doc:`accepting-donations` for a convention encouraging donations to storage server operators.
 

newsfragments/4039.documentation

@@ -0,0 +1 @@
+Document the ``force_foolscap`` configuration options for ``[storage]`` and ``[client]``.