Skip to content
Permalink
Browse files
Contribute Custom Erlang Network Protocol to CouchDB (#673)
  • Loading branch information
jiahuili430 committed Jul 29, 2021
1 parent d4f16d7 commit 96e2fff434e48d0b9e1c1f2c09be48da1a5cad24
Showing 4 changed files with 131 additions and 0 deletions.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -35,4 +35,5 @@ operational instructions on node, database and shard management.
databases
sharding
purging
tls_erlang_distribution
troubleshooting
@@ -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 \"clouseau@127.0.0.1\"
-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 ``"clouseau@127.0.0.1"``.

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 \"node1@127.0.0.1\"
-couch_dist no_tls \"node2@127.0.0.1\"

.. 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>
@@ -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.

0 comments on commit 96e2fff

Please sign in to comment.