Contribute Custom Erlang Network Protocol to CouchDB (#673)

Author: jiahuili430

images/TLS-Handshake.png

@@ -35,4 +35,5 @@ operational instructions on node, database and shard management.
     databases
     sharding
     purging
+    tls_erlang_distribution
     troubleshooting

src/cluster/index.rst

@@ -0,0 +1,122 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _cluster/tls_erlang_distribution:
+
+=======================
+TLS Erlang Distribution
+=======================
+The main purpose is specifically to allow using TLS for Erlang distribution
+between nodes, with the ability to connect to some nodes using TCP as well.
+TLS distribution will enhance data security during data migration between
+nodes.
+
+This section describes how to enable TLS distribution for additional
+verification and security.
+
+Reference: `Using TLS for Erlang Distribution`_
+
+.. _Using TLS for Erlang Distribution: https://erlang.org/doc/apps/ssl/ssl_distribution.html
+
+Generate Certificate
+====================
+For TLS to work properly, at least one public key and one certificate must be
+specified. In the following example (couch_ssl_dist.conf), the PEM file contains
+the ``certificate`` and its ``private key``.
+
+    .. code-block:: text
+
+        [{server,
+          [{certfile, "</path/to/erlserver.pem>"},
+           {secure_renegotiate, true}]},
+         {client,
+          [{secure_renegotiate, true}]}].
+
+The following command is an example of generating a certificate (PEM) file.
+
+    .. code-block:: bash
+
+        $ openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
+        $ cat key.pem cert.pem > erlserver.pem && rm key.pem cert.pem
+
+    .. note::
+       This is **not** an endorsement of a specific expiration limit,
+       key size or algorithm.
+
+Config Settings
+===============
+To enable TLS distribution, make sure to set custom parameters in ``vm.args``.
+
+    .. code-block:: text
+
+        # Don't forget to override the paths to point to your cert and conf file!
+
+        -proto_dist couch
+        -couch_dist no_tls \"[email protected]\"
+        -ssl_dist_optfile <path/to/couch_ssl_dist.conf>
+
+    .. note::
+       * The default value of ``no_tls`` is ``false``. If the user does not
+         set any ``no_tls`` flag, all nodes will use ``TCP``.
+       * To ensure "search" works, make sure to set ``no_tls`` option for the
+         ``clouseau`` node. By default, this will be ``"[email protected]"``.
+
+The ``no_tls`` flag can have these values:
+
+#. Use ``TLS`` only, set to ``false`` (default value), such as:
+
+    .. code-block:: text
+
+        -couch_dist no_tls false
+
+#. Use ``TCP`` only, set to ``true``, such as:
+
+    .. code-block:: text
+
+        -couch_dist no_tls true
+
+#. Specify some nodes to use ``TCP``, others to use ``TLS``, such as:
+
+    .. code-block:: text
+
+        # Specify node1 and node2 to use TCP, others use TLS
+
+        -couch_dist no_tls \"[email protected]\"
+        -couch_dist no_tls \"[email protected]\"
+
+    .. code-block:: text
+
+        # Any nodes end with "@127.0.0.1" will use TCP, others use TLS
+
+        -couch_dist no_tls \"*@127.0.0.1\"
+
+    .. note::
+       **Asterisk(*)**: matches a sequence of zero or more occurrences of the regular
+       expression.
+
+       **Question mark(?)**: matches zero or one occurrences of the regular expression.
+
+Connect to Remsh
+================
+Start Erlang using a remote shell connected to Node.
+
+* If the node uses ``TCP``:
+
+    .. code-block:: bash
+
+        $ ./remsh
+
+* If the node uses ``TLS``:
+
+    .. code-block:: bash
+
+        $ ./remsh -t <path/to/couch_ssl_dist.conf>

src/cluster/tls_erlang_distribution.rst

@@ -28,6 +28,14 @@ Version 3.2.0
 Features and Enhancements
 -------------------------
 
+* :ghissue:`3643`: Contribute a custom Erlang network protocol to CouchDB,
+  users can specify nodes to use TCP or TLS.
+
+.. figure:: ../../images/TLS-Handshake.png
+  :align: center
+  :alt: The SSL/TLS handshake enables the TLS client and server to establish
+        the secret keys with which they communicate.
+
 * :ghissue:`3472`, :ghissue:`3473`: Migrate some config options from [httpd]
   to [chttpd], migrate some from [couch_httpd_auth] to [chttpd_auth], and
   commented out in the default.ini.