Merge pull request #564 from rabbitmq/lrb-ssl_dist_optfile-159602360

Add documentation for the ssl_dist_optfile argument

Author: michaelklishin

site/clustering-ssl.xml

@@ -29,7 +29,7 @@ limitations under the License.
       <doc:section name="intro">
         <p class="intro">Sometimes is desirable to make the Erlang
         nodes talk to each other using TLS (SSL), and thus make the whole RabbitMQ
-        cluster communication via TLS. To achieve that we need to make the
+        cluster communication via TLS. To achieve that we need to configure the
         Erlang distribution mechanism to use TLS. In this document we are
         going to review the steps to make this possible.</p>
       </doc:section>
@@ -57,12 +57,12 @@ cat server_certificate.pem server_key.pem &gt; rabbit.pem
 # /etc/rabbitmq/rabbitmq-env.conf and will preserve the existing
 # contents of that file if it already exists
 
-erl -noinput -eval 'io:format("ERL_SSL_PATH=~p~n",[code:lib_dir(ssl, ebin)]),halt().' > /tmp/ssl-path.txt
+erl -noinput -eval 'io:format("ERL_SSL_PATH=~s~n", [filename:dirname(code:which(inet_tls_dist))])' -s init stop > /tmp/ssl-path.txt
 cat /tmp/ssl-path.txt /etc/rabbitmq/rabbitmq-env.conf > /tmp/new-rabbitmq-env.conf
 mv -f /tmp/new-rabbitmq-env.conf /etc/rabbitmq/rabbitmq-env.conf
 </pre>
 
-        <p>First we find where Erlang has the ssl library, and then the
+      <p>First we find where Erlang has the <code>inet_tls_dist</code> library, and then the
         variable <code>ERL_SSL_PATH</code> is set with the result from that command.</p>
 
         <p>By using the previous information now is time to craft the
@@ -92,7 +92,10 @@ SERVER_ADDITIONAL_ERL_ARGS="-pa $ERL_SSL_PATH \
         <code>/etc/rabbitmq/rabbitmq-env.conf</code> file:</p>
 
 <pre class="sourcecode bash">
-# NOTE: the following path is **system dependent**
+# NOTE: the following path is **system dependent** (will
+#       change depending on Erlang version, distribution used
+#       installation method used). Please double check it before
+#       proceeding.
 ERL_SSL_PATH="/usr/lib64/erlang/lib/ssl-8.2.4/ebin"
 
 SERVER_ADDITIONAL_ERL_ARGS="-pa $ERL_SSL_PATH \
@@ -131,9 +134,68 @@ CTL_ERL_ARGS="-pa $ERL_SSL_PATH \
         </p>
       </doc:section>
 
-      <doc:section name="how-to-osx">
-        <doc:heading>OS X</doc:heading>
-        <p>If you are using the OSX Standalone Release, then you need
+      <doc:section name="how-to-linux-ssl_dist_optfile">
+        <doc:heading>Linux (Erlang 20.2 and later)</doc:heading>
+        <p>Starting with <a href="http://www.erlang.org/news/116">version 20.2</a>,
+          Erlang supports the <code>-ssl_dist_optfile</code>
+          argument that allows configuring TLS for distributed Erlang in a file. This greatly simplifies
+          the arguments passed on the command line itself.
+        </p>
+        <p>
+          Here is a complete <code>/etc/rabbitmq/rabbitmq-env.conf</code> file using this setting.
+          Note that the name of the <code>-ssl_dist_optfile</code> file is not significant, it just
+          must be saved in a location readable by the <code>rabbitmq</code> user:
+        </p>
+
+<pre class="sourcecode bash">
+# NOTE: the following path is **system dependent**
+ERL_SSL_PATH="/usr/lib64/erlang/lib/ssl-8.2.4/ebin"
+
+SERVER_ADDITIONAL_ERL_ARGS="-pa $ERL_SSL_PATH \
+-proto_dist inet_tls \
+-ssl_dist_optfile /etc/rabbitmq/ssl_dist.config
+
+CTL_ERL_ARGS="-pa $ERL_SSL_PATH \
+-proto_dist inet_tls \
+-ssl_dist_optfile /etc/rabbitmq/ssl_dist.config
+</pre>
+
+        <p>
+          Here is an example <code>/etc/rabbitmq/ssl_dist.config</code> file:
+        </p>
+
+<pre class="sourcecode bash">
+[
+  {server, [
+    {cacertfile, "/full/path/to/ca_certificate.pem"},
+    {certfile, "/full/path/to/server_certificate.pem"},
+    {keyfile,  "/full/path/to/server_key.pem"},
+    {secure_renegotiate, true},
+    {verify, verify_peer},
+    {fail_if_no_peer_cert, true}
+  ]},
+  {client, [
+    {cacertfile, "/full/path/to/ca_certificate.pem"},
+    {certfile, "/full/path/to/client_certificate.pem"},
+    {keyfile, "/full/path/to/client_key.pem"},
+    {secure_renegotiate, true},
+    {verify, verify_peer},
+    {fail_if_no_peer_cert, true}
+  ]}
+].
+</pre>
+        <p>
+          The file contains many of the most common options enabled to fully validate certificates.
+          These options are documented further in the Erlang/OTP documentation:
+          <a href="http://erlang.org/doc/apps/ssl/ssl_distribution.html">Using TLS for Erlang Distribution</a>
+          as well as in the <a href="http://erlang.org/doc/man/ssl.html">ssl library documentation</a>.
+        </p>
+
+      </doc:section>
+
+      <doc:section name="how-to-macos">
+        <doc:heading>MacOS</doc:heading>
+        <p>If you are using the <a href="/install-standalone-mac.html#standalone-mac">MacOS standalone distribution</a>, then you need
         to add some extra arguments in order to run the <code>erl</code>
         command to find the path of Erlang's TLS library.  Assuming you are
         inside the folder where you installed the standalone release, the
@@ -146,14 +208,18 @@ echo erts-6.1/bin/erl -boot releases/3.4.3/start_clean \
 export ERL_SSL_PATH=/path/to/erl/lib/ssl-5.3.5/ebin
 </pre>
 
-        <p>The difference is that we need to specify the path to the
-        <code>erl</code> executable and also provide a path to a boot file,
-        which in our case is inside the releases folder of our standalone
-        installation.</p>
+        <p>
+          The difference is that we need to specify the path to the
+          <code>erl</code> executable and also provide a path to a boot file,
+          which in our case is inside the releases folder of our standalone
+          installation.
+        </p>
 
-        <p>Once you have ran the previous commands, then you can
-        proceed to create the environment variables as explained above on the
-        <a href="/clustering-ssl.html#how-to-linux">Linux section</a></p>
+        <p>
+          Once you have ran the previous commands, then you can
+          proceed to create the environment variables as explained above on the
+          <a href="/clustering-ssl.html#how-to-linux">Linux section</a>
+        </p>
 
       </doc:section>